This is release 201005.1
[nobug] / README
diff --git a/README b/README
index 5f190ce..37956aa 100644 (file)
--- a/README
+++ b/README
@@ -151,8 +151,14 @@ Currently, NoBug installs the following:
 
 .Generating This Documentation
 
- $ make nobug_manual.txt
- $ ascidoc -a toc nobug_manual.txt
+There are Makefile targets for generating the documentation, Either one of the
+following does what you may 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
+doc or the shipped 'README' which is actually this full nobug manual.
 
 // doc/using.txt:1 //
 Using NoBug
@@ -161,11 +167,11 @@ Using NoBug
 Your application will have to include the header file 'nobug.h' before NoBug
 can be used:
 
- #include "nobug.h"
+ #include <nobug.h>
 
 
 Once you've included the NoBug API in your application, you'll then have to select
-a 'build-level'.  Build-levels are discussed later, c.f., 
+a 'build-level'.  Build-levels are discussed later, c.f.,
 xref:buildlevel[buildlevel].   Build-levels are used to define the amount of
 information NoBug provides to you.  Maximum information is generally required while
 developing an application and the ALPHA build-level is most apropriate during
@@ -181,7 +187,7 @@ following form:
 
 
  #define EBUG_ALPHA
- #include "nobug.h"
+ #include <nobug.h>
 
 
 
@@ -202,7 +208,7 @@ However, for more flexibility in selecting a build-level, you might wish to
 define various targets in your makefile, one for each build-level.  In such
 cases, the -D flag in your makefile is most appropriate; so your link line for
 an ALPHA build with multi-threaded support would look like the following: 
+
 [source,sh]
 ----------------
 gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) mymodule1.o ... mymodulen.o  ..../libs/libnobugmt.a 
@@ -220,7 +226,7 @@ like the following:
 
 [source,sh]
 ----------------
-#include "nobug.h"   /* Include the NoBug API */
+#include <nobug.h>   /* Include the NoBug API */
 #define EBUG_ALPHA   /* If we have not used the -D Flag in our makefile */
 
 int main()
@@ -237,7 +243,7 @@ int main()
 
 
 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
-included. 
+included.
 
 A project using NoBug can use autoconf to check for execinfo and
 valgrind:
@@ -864,7 +870,7 @@ orthogonal through all macro definitions.
 `...`     printf-like format string followed by its arguments
 ---------------------------------------------------------------------------
 
-// src/nobug.h:627 //
+// src/nobug.h:632 //
 [[NOBUG_CONTEXT]]
 Source Contexts
 ~~~~~~~~~~~~~~~
@@ -951,7 +957,7 @@ otherwise optimized out.
 
  TODO: describe how to create invariant checks
 
-// src/nobug.h:361 //
+// src/nobug.h:366 //
 Logging Macros
 --------------
 
@@ -1070,16 +1076,18 @@ 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.
 
-// src/nobug.h:307 //
+// src/nobug.h:308 //
 [[DUMP]]
 .DUMP
- DUMP(flag, type, pointer, depth)
- DUMP_IF(when, flag, type, pointer, depth)
+ DUMP(flag, type, pointer, depth, extra)
+ DUMP_IF(when, flag, type, pointer, depth, extra)
 
 This macros call a datastructure dump of the object (`pointer`) in question.
 `DUMP` is only available in *ALPHA* and *BETA* builds, `DUMP_IF` is also
 enabled for the RELEASE builds.
 
+`extra` is a void* which is transparently passed around
+
 [[DUMP_LOG]]
 .DUMP_LOG
  DUMP_LOG(...)
@@ -1140,7 +1148,7 @@ example()
 }
 -------------------------------------------------------
 
-// src/nobug.h:647 //
+// src/nobug.h:652 //
 Source Annotations
 ------------------
 
@@ -1234,7 +1242,7 @@ not allowed.
 *CHECKED*   Preconditions, Postconditions             Preconditions
 ------------------------------------------------------------------------------------------------------
 
-// src/nobug.h:774 //
+// src/nobug.h:779 //
 Fault injection
 ---------------
 
@@ -1344,7 +1352,7 @@ The Resource Tracker relies on proper announce/forget and enter/leave
 are properly pairing. The programmer should ensure that this is done
 right, otherwise the results are unpredictable.
 
-// src/nobug.h:991 //
+// src/nobug.h:996 //
 Resource tracking macros
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1638,7 +1646,7 @@ and active in ALPHA builds and optimized out on any other build level.
 For details about the deadlock detection algorithm see
 xref:deadlock_detection[Appendix: Resource Tracking Alorithm].
 
-// src/nobug.h:2349 //
+// src/nobug.h:2354 //
 Callbacks
 ---------
 
@@ -1720,7 +1728,7 @@ IMPORTANT: Errors detected by NoBug are always fatal. If one handles and possibl
            throws an exception here, the application must shut down as soon as possible.
            Most causes for aborts are optimitzed out in `RELEASE` builds.
 
-// src/nobug.h:1578 //
+// src/nobug.h:1583 //
 Tool Macros
 -----------
 
@@ -1890,7 +1898,7 @@ NOTE: this section is very work in progress
 Appendix
 --------
 
-// src/nobug_resources.c:326 //
+// src/nobug_resources.c:333 //
 [[deadlock_detection]]
 The Resource Tracking Algorithm
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2094,7 +2102,7 @@ create new nodes.
                                   res_stack);
 
 ---------------------------------------------------------------------
-// src/nobug_resources.c:687 //
+// src/nobug_resources.c:694 //
 
 find the node pointing back to parent, create a new one if not found, rinse repeat