[GNUnet-SVN] r26256 - monkey/trunk/doc/man/man7

[gnunet]

Author: grothoff
Date: 2013-03-02 05:44:29 +0100 (Sat, 02 Mar 2013)
New Revision: 26256

Modified:
   monkey/trunk/doc/man/man7/monkey.7
Log:
minor edits

Modified: monkey/trunk/doc/man/man7/monkey.7
===================================================================
--- monkey/trunk/doc/man/man7/monkey.7  2013-03-02 04:34:37 UTC (rev 26255)
+++ monkey/trunk/doc/man/man7/monkey.7  2013-03-02 04:44:29 UTC (rev 26256)
@@ -6,33 +6,35 @@
 .SH DESCRIPTION
 .P
 The Monkey Debugging System is a three part toolset for automtically generating
-bug reports.
+bug reports from program crashes.
 .P
-To allow automated stack analysis with pathologist, you first have to generate
+To allow automated crash analysis with pathologist, you first have to generate
 an expression database with
 .B seaspider(1)
 . Seaspider will do some static code analysis and generate a sqlite database
-file containing all the expressions in your source code. Seaspider will also
-analyze preprocessor macros and add them to the database. If you have some
-variables in your source code, which contain private information of the user,
-you can specify an ignore file which contains regular expressions to exclude
-those variables from the database and therefore prevent later appearance of
+file containing all the expressions in your source code.  If you have
+some variables in your source code which contain private information
+of the user that must not be included in bug reports, you can specify
+an ignore file which contains regular expressions to exclude those
+variables from the database, and therefore prevent later appearance of
 the private data in the bug report.
 
 .P
 After the expression database has been generated, you can ship this database
-along with the
+together with your application.  On the target system, the user can then use
 .B pathologist(1)
-binary, which will run your application and catch any crashes, which might
-occur. Post mortem the stack will be analyzed via gdb and all relevant
-expressions in the stacktrace will be evaluated and written to the bug report
-in xml format. When the report has been succesfully written, pathologist can
-send it back to the developer via mail.
+, to run your application under supervision using 
+.B gdb(1)
+.  If the application crashes,
+a post-mortem analysis will be performed. The stack will be analyzed and all 
relevant
+expressions in the stacktrace and other information about the crash will be 
evaluated and written to a bug report
+in XML format. When the report has been succesfully written, Pathologist can
+send the report to the developer via mail.
 
 .P
-The third part,
-.B Entomologist(1)
-, is not yet functional, but will provide comparison and clustering algorithms
+The third component of the monkey debugging system is the
+.B entomologist(1)
+, which is not yet functional.  The Entomologist but will provide comparison 
and clustering algorithms
 for the generated reports.
 
 .SH REQUIREMENTS
@@ -41,26 +43,28 @@
 requirements.
 
 .P
-Your project has to be written in C (no C++ support).
+Your project has to be written in C (C++ support is missing in Seaspider).
 
 .P
-To use seaspider, your project has to be built with GNU Autotools. Other Build
+To use Seaspider, your project has to be built with GNU Autotools. Other Build
 Systems are not supported, but it should still be possible to use them as well,
-if you can set the compiler and compileroptions yourself.
+if you can set the compiler and compiler options yourself.
 
+.P
+You need gdb in version 7 or later, and we have only tested the system on 
GNU/Linux.
+
 .SH LIMITATIONS
 .P
-Pathologist can only handle the following signals yet: SIGSEGV (Segfault),
-SIGABRT (Assertion), SIGBUS (Bad Memory Access), SIGFPE (Arithmetic Exception).
+Pathologist can only (nicely) handle the following signals at this time: 
SIGSEGV (Segfault),
+SIGABRT (Assertion), SIGBUS (Bad Memory Access), and SIGFPE (Arithmetic 
Exception).
 
 .P
-Your C source file names have to be unique, because gdb does not ensure to
-output the full path correctly.
+Your C source file names have to be globally unique in your project.
 
 .P
 Due to gdb changing the respective values on the stack while evaluating,
 increments and decrements are problematic if contained in the line of code,
-which causes the crash. seaspider will just remove every single increment and
+which causes the crash. Seaspider will just remove every single increment and
 decrement operator before writing expressions to the database, so if your
 program crashes on a line
 .B a = b[++c];