Language and text improvements. No significant change to content.
authorBenny Lyons <Benny.Lyons@gmx.net>
Wed, 11 Aug 2010 16:05:14 +0000 (18:05 +0200)
committerBenny Lyons <Benny.Lyons@gmx.net>
Wed, 11 Aug 2010 16:05:14 +0000 (18:05 +0200)
Language corrected and some text additions, but no new information.

doc/annotationtable.txt
doc/buildinstall.txt
doc/dumpexample.txt
doc/dumping.txt

index ce4edf1..f1339e2 100644 (file)
@@ -1,8 +1,14 @@
-
-The advantage of this tagging over plain source comments is that we can take
-some actions if we run in such a tag at compile or runtime:
-
-the action to be taken when such a macro is hit depends on the build level:
+Obsolete, buggy or precarious code can be marked in the code itself in 
+comments at the location where the code occurs.  However these code 
+locations can be easily overlooked, especially in large projects.  The
+advantage of this tagging scheme is that it provides an additional 
+instrument to alert or remind the programmer that there is still dubious 
+code embedded in the application. This tagging scheme not only informs
+the programmer at compile time that there is code in the application
+that needs attending to, but long after compilitation a test team
+might become aware of dubbious code due to runtime messages.
+The action that should be taken when such a message occurs depends
+on the build level:
 
 [grid="all"]
 `-------------`-----`------------`-----------------------------------------
@@ -18,9 +24,9 @@ NOTREACHED    abort abort        removed
 
 Legend:
 
-  * abort means first log and then abort
-  * log will only log once for each sourceline (not on each hit)
-  * wont compile will abort compilation with a error message
+  * abort means first log, then abort
+  * log will only log once for each source line (not on each hit)
+  * will not compile, will abort compilation with a error message
   * nothing optimized out, sane way
-  * removed optimized out for performance reasons
+  * removed and optimized out for performance reasons
 
index 184355b..a2afdfe 100644 (file)
@@ -111,14 +111,18 @@ Currently, NoBug installs the following:
 
 HEAD== Generating This Documentation;;
 
-There are Makefile targets for generating the documentation, Either one of the
-following does what you may expect:
+There are Makefile targets for generating the documentation, either one of the
+following does what you might expect:
 
  $ make nobug_manual.txt nobug_manual.html nobug_manual.pdf
 
-building the documentation has quite some more dependencies than building
-NoBug itself. Unless you are a packager you may want to refer to the online
-documentation or the shipped 'README' which is this complete nobug reference
+Alternatively, you can generate all the documentation in one go as follows:
+
+  $ make doc
+
+Building the documentation has quite some more dependencies than building
+NoBug itself. Unless you are a packager you may prefer to refer to the online
+documentation or the shipped 'README' which is the complete nobug reference
 manual in text form. Generating the documentation requires: gawk, asciidoc,
-graphviz and some toolchains to further process docbook and latex.
+graphviz and some tool chains to further process docbook and latex.
 
index 66a473e..a01076c 100644 (file)
@@ -10,7 +10,7 @@ struct STRUCTNAME
 }
 -------------------------------------------------------
 
-then you define a function like:
+Thereafter, define a funcion as follows:
 
 [source,c]
 -------------------------------------------------------
@@ -21,7 +21,7 @@ nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
                        void* extra)
 {
   // check for self != NULL and that the depth
-  // limit did not exceed in recursive datastructures
+  // limit was not exceeded in recursive data structures
   if (self && depth)
   {
     // you may or may not do something with the extra parameter here
@@ -39,7 +39,7 @@ nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
 }
 -------------------------------------------------------
 
-now you can use the DUMP() macros within the code
+Now you can use the DUMP() macros within the code
 
 [source,c]
 -------------------------------------------------------
index ff56589..13341a7 100644 (file)
@@ -1,12 +1,12 @@
-HEAD- Dumping Datastructures;dumping;
+HEAD- Dumping Data Structures;dumping;
 
 TODO How to write DUMP handlers
 
-One can write functions for dumping complex datastructures using the NoBug
+One can write functions to dump complex data structures using the NoBug
 facilities. This is done by writing a custom function for each
-datastructure to be dumped which may recursively call other dumping
-functions. There are macros for logging within such a dumper function
-and for initiating a dump of a given datastructure.
+data structure to be dumped, which may recursively call other dumping
+functions. There are macros that can log within such a dumper function
+and to initialise a dump of a given data structure.
 
 A dump function has the prototype:
 
@@ -20,8 +20,8 @@ nobug_NAME_dump (const struct NAME* POINTER,
 -------------------------------------------------------
 
 where NAME is the identifier for what you want to dump, POINTER is a pointer
-to the data to be dumped, DEPTH is a integer which will be decremented when
-recursing into the datastructure dumper (your dump function does that, see
+to the data to be dumped, DEPTH is an integer which will be decremented when
+recursing into the data structure dumper (your dump function does that, see
 below) to limit the recursion depth, CONTEXT is a source context generated by
 nobug when you call DUMP() and EXTRA is a pointer transparently passed around
-you can use to store some extra state.
+that you can use to store some additional state.