This is release 201008.1 201008.1 latest-release master_signature
authorChristian Thaeter <ct@pipapo.org>
Fri, 20 Aug 2010 18:43:33 +0000 (20:43 +0200)
committerChristian Thaeter <ct@pipapo.org>
Fri, 20 Aug 2010 18:43:33 +0000 (20:43 +0200)
ChangeLog
NEWS
README
VERSION
configure.ac

index 60493ef..4e26b6f 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
 
+2010-08-20 20:25:21 +0200 b5e4594
+Christian Thaeter <ct@pipapo.org>
+
+ignore pdftex errors
+
+doc generation isn't perfect yet, the missing graph conversion barfs out
+otherwise, nevertheless the generated manual is already useable.
+
+ M     Makefile.am
+
+
+2010-08-20 20:19:36 +0200 6c82e27
+Christian Thaeter <ct@pipapo.org>
+
+test_inc.conf produces the testsuite doc (temp)
+
+
+ A     doc/test_inc.conf
+
+
+2010-08-20 20:08:46 +0200 2e78d97
+Christian Thaeter <ct@pipapo.org>
+
+remove 'volatile' they're wrong, we need barriers/locks there someday
+
+
+ M     src/nobug.c
+ M     src/nobug.h
+
+
+2010-08-20 19:31:20 +0200 ecf40d7
+Christian Thaeter <ct@pipapo.org>
+
+Release preparation, bump library version, makefile update for README
+
+
+ M     Makefile.am
+ M     doc/latex.conf
+
+
+2010-08-19 19:29:07 +0200 75dc579
+Christian Thaeter <ct@pipapo.org>
+
+Final Documentation makeover, fix plenty bugs
+
+
+ M     doc/buildinstall.txt
+ M     doc/coverageintro.txt
+ M     doc/dumping.txt
+ M     doc/logconfiguration.txt
+ M     doc/logflags.txt
+ M     doc/logflagsenv.txt
+ M     doc/logformat.txt
+ M     doc/logging.txt
+ M     doc/macros.txt
+ M     doc/multithreading.txt
+ M     doc/nobug_manual.conf
+ M     doc/overview.txt
+ M     doc/parametertable.txt
+ M     doc/resourcedeadlock.txt
+ M     doc/resourcetracking.txt
+ M     doc/scopechecks.txt
+ M     doc/using.txt
+ M     doc/whichlibrary.txt
+ M     src/nobug.c
+ M     src/nobug.h
+ M     src/nobug_rbdump.c
+ M     src/nobug_resources.c
+ M     tests/test.sh
+
+
+2010-08-19 03:15:43 +0200 15464fd
+Andreas Hermann Braml <andreas@braml.org>
+
+Fix typos
+
+
+ M     doc/bestpractices.txt
+ M     doc/buildinstall.txt
+ M     doc/buildlevels.txt
+ M     doc/coverageintro.txt
+
+
+2010-08-18 22:07:03 +0200 fd4fd1c
+Christian Thaeter <ct@pipapo.org>
+
+cosmetic in sourcecode docs
+
+
+ M     src/nobug_resources.c
+
+
+2010-08-18 22:06:40 +0200 dd2476d
+Christian Thaeter <ct@pipapo.org>
+
+fix tables
+
+
+ M     doc/annotationtable.txt
+ M     doc/assertiontable.txt
+ M     doc/latex.conf
+
+
+2010-08-18 15:42:42 +0200 222109d
+Christian Thaeter <ct@pipapo.org>
+
+include the test.sh doc into the nobug book
+
+temporary disables the standalone doc generation
+
+ M     Makefile.am
+ M     doc/nobug_manual.conf
+ M     tests/test.sh
+
+
+2010-08-18 15:41:11 +0200 2007b0c
+Christian Thaeter <ct@pipapo.org>
+
+cosmetics and copyright years updates
+
+
+ M     doc/license.txt
+ M     src/nobug.h
+
+
+2010-08-18 15:40:14 +0200 af0dece
+Christian Thaeter <ct@pipapo.org>
+
+improve the 'literate' source docs for the resource tracker
+
+
+ M     doc/resourcedeadlock.txt
+ M     src/nobug_resources.c
+
+
+2010-08-18 15:39:03 +0200 213c5a8
+Christian Thaeter <ct@pipapo.org>
+
+add functionality to verbatim.pawk to strip leading spaces
+
+
+ M     doc/verbatim.pawk
+
+
+2010-08-18 01:22:12 +0200 51ab313
+Christian Thaeter <ct@pipapo.org>
+
+More documentation fixes, formatting, cosmetic, wording
+
+
+ M     doc/annotationtable.txt
+ M     doc/buildinstall.txt
+ M     doc/dumpexample.txt
+ M     doc/dumping.txt
+ M     doc/initialization.txt
+ M     doc/logconfiguration.txt
+ M     doc/logflags.txt
+ M     doc/logflagsenv.txt
+ M     doc/macros.txt
+ M     doc/multithreading.txt
+ M     doc/resourceexample.txt
+ M     src/nobug.h
+
+
+2010-08-17 22:42:29 +0200 f150bfc
+Christian Thaeter <ct@pipapo.org>
+
+improve index generation and pagerefs
+
+
+ M     doc/latex.conf
+ M     doc/nobug_manual.conf
+
+
+2010-08-17 20:22:46 +0200 d3c484a
+Christian Thaeter <ct@pipapo.org>
+
+add a 'dotted' list style for the index, include pageref in xrefs
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 20:03:31 +0200 9321100
+Christian Thaeter <ct@pipapo.org>
+
+some formatting fixes, missing empty lines, literal passthoughs
+
+
+ M     doc/multithreading.txt
+ M     doc/using.txt
+
+
+2010-08-17 20:00:11 +0200 e175397
+Christian Thaeter <ct@pipapo.org>
+
+rewrite the labeled lists using latex descriptions
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 19:56:46 +0200 2db9860
+Christian Thaeter <ct@pipapo.org>
+
+Another asciidoc.pawk change
+
+
+ M     doc/asciidoc.pawk
+
+
+2010-08-17 17:53:03 +0200 b861817
+Andreas Hermann Braml <andreas@braml.org>
+
+doc: Fix typos; update LaTeX depencies; rephrase some overly complex sentences
+
+
+ M     doc/buildinstall.txt
+ M     doc/overview.txt
+
+
+2010-08-17 17:21:53 +0200 dcbe122
+Andreas Hermann Braml <andreas@braml.org>
+
+Fix typo
+
+
+ M     doc/nobug_manual.conf
+
+
+2010-08-17 17:16:56 +0200 bcf7a4c
+Christian Thaeter <ct@pipapo.org>
+
+change link coolors
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 17:15:02 +0200 206d794
+Christian Thaeter <ct@pipapo.org>
+
+convert table-legend to footnotes in the annotations table
+
+
+ M     doc/annotationtable.txt
+
+
+2010-08-17 16:26:52 +0200 efe6277
+Christian Thaeter <ct@pipapo.org>
+
+we don't want colons generated by latex.conf
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 16:20:07 +0200 46e62c5
+Christian Thaeter <ct@pipapo.org>
+
+add empty lines before literal paragraphs
+
+
+ M     src/nobug.h
+
+
+2010-08-17 16:05:58 +0200 4ac2736
+Andreas Hermann Braml <andreas@braml.org>
+
+AsciiDoc/LaTeX: use package microtype to make typeset output prettier
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 16:00:37 +0200 3dc93c5
+Andreas Hermann Braml <andreas@braml.org>
+
+AsciiDoc/LaTeX: set link colors in PDF to cyan
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 15:57:46 +0200 d6414c7
+Christian Thaeter <ct@pipapo.org>
+
+fix INDEX syntax glitches with empty lines
+
+
+ M     doc/logflags.txt
+ M     doc/scopechecks.txt
+ M     src/nobug.h
+
+
+2010-08-17 15:56:55 +0200 7ed91d9
+Christian Thaeter <ct@pipapo.org>
+
+WIP: remove the text from a hypertarget
+
+maybe we have to fix this later, in cases where the text is needed
+but falling back to a default was bad for invisible anchors
+
+ M     doc/latex.conf
+
+
+2010-08-17 15:55:14 +0200 f65256b
+Christian Thaeter <ct@pipapo.org>
+
+another try on asciidoc.pawk, generating an explicit id
+
+we may factor id generation into a function later, possibly
+invent a encoding scheme which preserves sort order
+
+ M     doc/asciidoc.pawk
+
+
+2010-08-17 15:22:49 +0200 6e68eab
+Christian Thaeter <ct@pipapo.org>
+
+dont make 'Index' a specialsection because we will generat our own index
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 01:48:47 +0200 46d84ac
+Christian Thaeter <ct@pipapo.org>
+
+some pending cosmetics
+
+
+ M     doc/buildlevels.txt
+ M     src/nobug.h
+
+
+2010-08-17 01:48:23 +0200 4c7e90c
+Christian Thaeter <ct@pipapo.org>
+
+remove spaces from hyperref identifiers instead using __
+
+
+ M     doc/asciidoc.pawk
+
+
+2010-08-17 01:47:51 +0200 b856540
+Christian Thaeter <ct@pipapo.org>
+
+colspec fix, new asciidoc table syntax
+
+
+ M     doc/latex.conf
+
+
+2010-08-17 01:47:08 +0200 17f6cb1
+Christian Thaeter <ct@pipapo.org>
+
+Remove .idx generation we create a custom index later
+
+
+ M     Makefile.am
+
+
+2010-08-16 22:53:53 +0200 735f95a
+Andreas Hermann Braml <andreas@braml.org>
+
+AsciiDoC/LaTeX: add package cmap to fix search in generated PDF
+
+
+ M     doc/latex.conf
+
+
+2010-08-16 22:50:16 +0200 d4b6f83
+Christian Thaeter <ct@pipapo.org>
+
+makefile targets for toc and index generation (incomplete)
+
+
+ M     Makefile.am
+
+
+2010-08-16 22:01:26 +0200 c4a2b64
+Andreas Hermann Braml <andreas@braml.org>
+
+AsciiDoc/LaTeX: Fix escapes
+
+
+ M     doc/latex.conf
+
+
+2010-08-16 21:49:30 +0200 02e5678
+Andreas Hermann Braml <andreas@braml.org>
+
+AsciiDoc/LaTeX: Use thempfootnote counter in tables
+
+
+ M     doc/latex.conf
+
+
+2010-08-16 21:46:16 +0200 8efe4e6
+Christian Thaeter <ct@pipapo.org>
+
+fix index/anchor generation, anchors must be after the target header
+
+
+ M     doc/asciidoc.pawk
+
+
+2010-08-16 21:19:09 +0200 65e7e1f
+Christian Thaeter <ct@pipapo.org>
+
+move abstact, motto and toc to the manual config file
+
+
+ M     doc/nobug_manual.conf
+ M     doc/overview.txt
+
+
+2010-08-16 21:18:16 +0200 59a7826
+Christian Thaeter <ct@pipapo.org>
+
+Work on latex tables, allowing footnotes
+
+still ugly aligned, but it works basically
+
+ M     doc/buildinstall.txt
+ M     doc/latex.conf
+
+
+2010-08-16 16:59:44 +0200 34c10ec
+Christian Thaeter <ct@pipapo.org>
+
+fix passthrough for __foo__ texts
+
+
+ M     doc/macros.txt
+
+
+2010-08-16 14:21:04 +0200 916880b
+Christian Thaeter <ct@pipapo.org>
+
+FIX: pipadoc index generation, replace non alnum chars with '__'
+
+
+ M     doc/asciidoc.pawk
+
+
+2010-08-15 22:29:20 +0200 115fdef
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor language chages.
+
+
+ M     doc/resourcetracking.txt
+
+
+2010-08-15 22:13:23 +0200 85d24c8
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor corrections to language: Coverage Macros.
+
+
+ M     src/nobug.h
+
+
+2010-08-15 22:07:56 +0200 1b7abe1
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor changes to language.
+
+
+ M     doc/coverageintro.txt
+
+
+2010-08-15 21:59:12 +0200 12742b3
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor language corrections.
+
+
+ M     src/nobug.h
+
+
+2010-08-15 21:53:26 +0200 c971b21
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor corrections to language.
+
+
+ M     doc/coverageintro.txt
+
+
+2010-08-15 21:35:27 +0200 c9a02d5
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor language corrections: Macros on Fauslt Injection.
+
+
+ M     src/nobug.h
+
+
+2010-08-15 18:13:45 +0200 e497b63
+Christian Thaeter <ct@pipapo.org>
+
+make the generated .tex file precious for easier debugging
+
+
+ M     Makefile.am
+
+
+2010-08-15 17:52:53 +0200 4375a70
+Christian Thaeter <ct@pipapo.org>
+
+fixing backslash escaping in tables, refine the compatibility table
+
+
+ M     doc/buildinstall.txt
+ M     doc/latex.conf
+
+
+2010-08-15 17:46:50 +0200 336781c
+Christian Thaeter <ct@pipapo.org>
+
+Arrgs, accidentally dropped what was already commited
+
+add .conf files to dependencies in Makefiles
+
+ M     Makefile.am
+
+
+2010-08-15 17:35:25 +0200 8ba07b4
+Andreas Hermann Braml <andreas@braml.org>
+
+upgrade listingblock in latex.conf to fancyvrb (has more features that come in handy)
+
+
+ M     doc/latex.conf
+
+
+2010-08-15 04:50:09 +0200 7bac410
+Andreas Hermann Braml <andreas@braml.org>
+
+doc: Convert tables to new AsciiDoc post-8.3.0 syntax
+
+
+ M     doc/annotationtable.txt
+ M     doc/assertiontable.txt
+ M     doc/buildinstall.txt
+ M     doc/logconfiguration.txt
+ M     doc/parametertable.txt
+
+
+2010-08-12 18:54:47 +0200 2c6a5c6
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Text moved to nobug.h.
+
+
+ M     doc/annotationtable.txt
+
+
+2010-08-12 18:50:42 +0200 9026a04
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Description of Source Code Annotations expanded.
+
+The description of the macros for annotating source code increased.
+Possible reasons to use these macros given.
+
+ M     src/nobug.h
+
+
+2010-08-11 18:10:16 +0200 dfefd6c
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Improvements to text describing macros.
+
+Description of many macros improved. A more consistent description of
+all macros used, which, hopefully, should make it easier and quicker
+to read.
+
+TODO: Text on many macros still need to be improved.
+
+ M     src/nobug.h
+
+
+2010-08-11 18:05:14 +0200 463b642
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Language and text improvements. No significant change to content.
+
+Language corrected and some text additions, but no new information.
+
+ M     doc/annotationtable.txt
+ M     doc/buildinstall.txt
+ M     doc/dumpexample.txt
+ M     doc/dumping.txt
+
+
+2010-08-10 05:29:01 +0200 8df033b
+Christian Thaeter <ct@pipapo.org>
+
+some doc cosmetics and improvements
+
+
+ M     Makefile.am
+ M     doc/logflags.txt
+ M     doc/logflagsenv.txt
+ M     doc/logformat.txt
+ M     doc/overview.txt
+ M     doc/using.txt
+ M     src/nobug.c
+
+
+2010-08-10 05:27:11 +0200 41c607b
+Christian Thaeter <ct@pipapo.org>
+
+fix listing titles
+
+we don't need captions, they didn't worked anyways
+
+some comments to improve emacs source highlighting
+
+ M     doc/latex.conf
+
+
+2010-08-10 05:25:34 +0200 d1afb5b
+Christian Thaeter <ct@pipapo.org>
+
+include .conf files in the Makefile dependencies
+
+
+ M     Makefile.am
+ M     doc/logflags.txt
+
+
+2010-08-09 22:45:32 +0200 f4287c9
+Christian Thaeter <ct@pipapo.org>
+
+Revert "Minor language improvements."
+
+Only revert the documentation about NOBUG_INIT(), currently the
+INIT_FLAG*() will call NOBUG_INIT(), but this is mainly meant as
+undocumented compatibility feature. calling NOBUG_INIT() should be
+mandatory for the time being.
+
+This reverts commit a3f52ec12331395f39da9bc6f1ca9ce0fcae49b2.
+
+ M     doc/initialization.txt
+
+
+2010-08-09 18:15:46 +0200 a3f52ec
+Benny Lyons <Benny.Lyons@gmx.net>
+
+Minor language improvements.
+
+
+ M     doc/buildlevels.txt
+ M     doc/initialization.txt
+ M     doc/logflags.txt
+ M     doc/logflagsenv.txt
+ M     doc/logging.txt
+ M     doc/macros.txt
+
+
+2010-08-09 10:01:14 +0200 388da6f
+Christian Thaeter <ct@pipapo.org>
+
+formatting improvments on the resourcetracker doc
+
+
+ M     src/nobug.h
+
+
+2010-08-09 09:41:13 +0200 d553b67
+Christian Thaeter <ct@pipapo.org>
+
+fix resourcetracking formatting
+
+
+ M     doc/resourcetracking.txt
+
+
+2010-08-09 09:40:52 +0200 643520d
+Christian Thaeter <ct@pipapo.org>
+
+authors and license formatting
+
+
+ M     AUTHORS
+ M     doc/license.txt
+
+
+2010-08-09 09:40:28 +0200 1161521
+Christian Thaeter <ct@pipapo.org>
+
+fix admonition paragaphs
+
+
+ M     doc/latex.conf
+
+
+2010-08-09 08:12:46 +0200 cfabbe8
+Christian Thaeter <ct@pipapo.org>
+
+starting chapters at any page will safe some trees
+
+
+ M     doc/latex.conf
+
+
+2010-08-09 08:12:10 +0200 29c1be4
+Christian Thaeter <ct@pipapo.org>
+
+improve the annotations doc
+
+
+ M     src/nobug.h
+
+
+2010-08-09 07:54:47 +0200 53e9dae
+Christian Thaeter <ct@pipapo.org>
+
+add 'credits' as symlink to AUTHORS
+
+
+ M     AUTHORS
+ A     doc/credits.txt
+ M     doc/nobug_manual.conf
+
+
+2010-08-09 07:52:25 +0200 42aed41
+Christian Thaeter <ct@pipapo.org>
+
+fixing and rewraping the macros chapter
+
+
+ M     doc/macros.txt
+
+
+2010-08-09 07:51:44 +0200 391df78
+Christian Thaeter <ct@pipapo.org>
+
+another newline for verbatim sections
+
+
+ M     doc/latex.conf
+
+
+2010-08-09 07:18:21 +0200 9252fe6
+Christian Thaeter <ct@pipapo.org>
+
+reviewd, reworded and fixed some documentation
+
+
+ M     doc/additional.txt
+ M     doc/buildinstall.txt
+ M     doc/buildlevels.txt
+ M     doc/initialization.txt
+ M     doc/logconfiguration.txt
+ M     doc/logflags.txt
+ M     doc/logflagsenv.txt
+ A     doc/logflagsexample.txt
+ A     doc/logformat.txt
+ M     doc/logging.txt
+ M     doc/nobug_manual.conf
+ M     doc/using.txt
+ M     src/nobug.c
+
+
+2010-08-09 07:16:40 +0200 1e6f687
+Christian Thaeter <ct@pipapo.org>
+
+plenty improvements for latex.conf
+
+
+ M     doc/latex.conf
+
+
+2010-08-08 22:31:23 +0200 2cd42f6
+Christian Thaeter <ct@pipapo.org>
+
+doc: small documentation fixes, new title
+
+
+ M     doc/buildinstall.txt
+ M     doc/nobug_manual.conf
+ M     doc/overview.txt
+
+
+2010-08-08 22:27:51 +0200 d47611f
+Christian Thaeter <ct@pipapo.org>
+
+pdf: fixing link generation
+
+the {0} parameter seems to be set when a attrlist for a macro is empty
+so we test on {1}, looks rather like a bug or some other problem to me
+but fixes the link generation for me.
+
+ M     doc/latex.conf
+
+
+2010-08-08 20:20:41 +0200 b5602d8
+Christian Thaeter <ct@pipapo.org>
+
+PDF: style fixes
+
+ * use 'book' document type for pdf
+ * renumber sections, Document title is not section 0
+ * few small fixes
+
+ M     Makefile.am
+ M     doc/latex.conf
+
+
+2010-08-08 18:08:21 +0200 4b350db
+Christian Thaeter <ct@pipapo.org>
+
+start new PDF generation through plain latex
+
+ * merged latex.conf from andreas
+ * simple Make rules (no index generation yet)
+
+ M     Makefile.am
+ A     doc/latex.conf
+
+
+2010-08-07 10:14:05 +0200 56892c0
+Christian Thaeter <ct@pipapo.org>
+
+let README generation grep asciidoc comments out
+
+also include updated README
+
+ M     Makefile.am
+ M     README
+
+
+2010-08-03 05:13:24 +0200 8ada8ad
+Christian Thaeter <ct@pipapo.org>
+
+FIX: some gotchas in test.sh
+
+
+ M     tests/test.sh
+
+
+2010-08-03 05:12:43 +0200 23b1d34
+Christian Thaeter <ct@pipapo.org>
+
+cosmetics, fault coverage checker
+
+
+ M     src/nobug_coverage.c
+ M     tests/test_nobug_coverage.c
+
+
+2010-08-03 05:11:16 +0200 deed5a0
+Christian Thaeter <ct@pipapo.org>
+
+document the fault-coverage checker
+
+
+ A     doc/coverageintro.txt
+ M     doc/nobug_manual.conf
+ M     src/nobug.h
+
+
+2010-07-20 01:55:08 +0200 b76a56c
+Christian Thaeter <ct@pipapo.org>
+
+add bug-report address to AC_INIT
+
+
+ M     configure.ac
+
+
+2010-07-16 03:19:20 +0200 8231dee
+Christian Thaeter <ct@pipapo.org>
+
+tests for resource resetting
+
+
+ M     tests/35resourcethreaded.tests
+ M     tests/test_nobug_resources_threaded.c
+
+
+2010-07-16 03:18:13 +0200 217664c
+Christian Thaeter <ct@pipapo.org>
+
+FIX: copy'n'paste brainfart in RESETALL
+
+
+ M     src/nobug.h
+
+
+2010-07-14 04:18:09 +0200 893001b
+Christian Thaeter <ct@pipapo.org>
+
+RESOURCE_RESET and RESOURCE_RESETALL
+
+brings resources back into a pristine state forgetting anything
+learned so far.
+
+ M     src/nobug.h
+ M     src/nobug_resources.c
+
+
+2010-07-14 03:50:50 +0200 8b8a80b
+Christian Thaeter <ct@pipapo.org>
+
+ass some sanity checks for COVERAGE_DISABLE/ENABLE
+
+
+ M     src/nobug.h
+
+
+2010-07-13 16:54:12 +0200 389c0fa
+Christian Thaeter <ct@pipapo.org>
+
+add COVERAGE_DISABLE/COVERAGE_ENABLE
+
+These let one temporary (and nested) disable and enable fault injection on
+coverage checks to suppress false positives.
+
+ M     Makefile.am
+ M     src/nobug.c
+ M     src/nobug.h
+ M     src/nobug_coverage.c
+ A     src/nobug_nothread.c
+ M     src/nobug_thread.c
+ M     tests/coverage.sh
+ M     tests/test_nobug_coverage.c
+
+
+2010-07-12 23:05:09 +0200 aa621b1
+Christian Thaeter <ct@pipapo.org>
+
+fault coverage testing, first implementation (EXPERIMENTAL)
+
+This creates a facility to permute over instrumented faults. This is done
+by hashing backtraces, every path reaching a failure point is recorded.
+
+Programs using this fault coverage checking first parsing all logfiles
+provided in the env var NOBUG_COVERAGE to learn about the previous state.
+
+Then running the program will log at every instrumented fault and initially
+fail at any newly discovered failure point and pass at the last known
+failure point. Running a program multiple times always feeding back the
+logs from the previous run will eventually permute through all possible way
+calling errors and handling them.
+
+ M     Makefile.am
+ M     src/nobug.c
+ M     src/nobug.h
+ A     src/nobug_coverage.c
+ M     tests/Makefile.am
+ A     tests/coverage.sh
+ A     tests/test_nobug_coverage.c
+
+
+2010-06-09 08:10:00 +0200 69c89f6
+Christian Thaeter <ct@pipapo.org>
+
+add the _IF variant to INVARIANT_ASSERT
+
+turned out to be useful in edge cases
+
+ M     src/nobug.h
+
+
+2010-06-06 01:17:04 +0200 9b1163d
+Christian Thaeter <ct@pipapo.org>
+
+FIX: ENSURE_IF_CTX called the non _CTX version
+
+
+ M     src/nobug.h
+
+
+2010-06-09 08:10:00 +0200 095c813
+Christian Thaeter <ct@pipapo.org>
+
+add the _IF variant to INVARIANT_ASSERT
+
+turned out to be useful in edge cases
+
+ M     src/nobug.h
+
+
+2010-06-06 01:17:04 +0200 bb18f93
+Christian Thaeter <ct@pipapo.org>
+
+FIX: ENSURE_IF_CTX called the non _CTX version
+
+
+ M     src/nobug.h
+
+
 2010-06-01 23:48:44 +0200 8eab85a
 Christian Thaeter <ct@pipapo.org>
 
diff --git a/NEWS b/NEWS
index 22697fa..157489a 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,13 @@
+201008.1
+--------
+20 Aug 2010
+
+Major Documentation improvements, a PDF for hardcopy can now be generated.
+Some small bugfixes. A new experimental Fault-Coverage-Checking facility which
+allows one to find out if all possible error-paths are sufficiently handled.
+Add functionality to reset the Resource-tracker to a pristine state.
+
+
 201006.1
 --------
 01 Jun 2010
diff --git a/README b/README
index 56e4906..263fa4e 100644 (file)
--- a/README
+++ b/README
@@ -1,13 +1,20 @@
-NoBug
-=====
+NoBug Reference Manual
+======================
 Christian_Thäter,_Benny_Lyons
 
-____
+[abstract]
+*****************************************************************
+NoBug is a debugging library for instrumenting C and C++ programs
+inspired by ideas originating from Design-by-Contract.
+*****************************************************************
+
+[quote]
+__________________________________________________________________
 Everyone makes mistakes, but with NoBug you won't make them twice!
-____
+__________________________________________________________________
 
-Nobug is a debugging library for instrumenting C and C++ programs
-inspired by ideas originating from Design-by-Contract.
+Contents
+--------
 
 Overview
 --------
@@ -26,57 +33,73 @@ The following features are provided by NoBug:
     detecting misuse
   * Detecting potential deadlocks
   * Simulate errors by injecting faults
+  * Coverage checking to find out if all (instrumentated) errors are properly handled
   * Additionally, the NoBug project is used to maintain a script and
     some tools to setup testsuites
 
-In contrast to traditional debuggers, NoBug is a non-interactive debugger which
-is linked to your application doing hard-coded tests in an efficient,
-low-overhead way.
+In contrast to traditional debuggers, NoBug is a non-interactive debugger that
+is linked to your application doing hard-coded tests in an efficient way
+without much overhead. Depending on the build level you choose, NoBug features
+will be an integral part of your application making it possible to gather
+debugging data for each stage of the application development, including
+collecting debugging info for finally deployed applications.
+
 
-.What NoBug can not do
+.What NoBug can't do
 
 NoBug is a (macro-)library, it is not a C/C++ language extension. This
 means that code must be called at runtime to benefit from the set up
-contracts. Whats not tested is likely slipping through the net. Being
-part of the program itself it is affected by memory corruption,
-certain kinds of misuse may introduce new bugs (test expressions with
+contracts. What's not tested is likely slipping through the net. Being
+part of the program itself, it is affected by memory corruption.
+Certain kinds of misuse may introduce new bugs (assert expressions with
 side effects for example).
 
+
+Support
+~~~~~~~
+
+When you need help with NoBug, have some ideas about potential features or
+think you found a bug, then you can contact the NoBug community and developers
+by sending mail to the NoBug mailinglist. Subscription is available at
+http://lists.pipapo.org/cgi-bin/mailman/listinfo/nobug[].
+
 Building and Installing
 -----------------------
 
 Supported Platforms
 ~~~~~~~~~~~~~~~~~~~
 
-NoBug has been developed on linux, using gcc. It should be possible to port
+NoBug has been developed on Linux, using GCC. It should be possible to port
 it to any other POSIX compliant operating system. Platform/compiler
-specific things are kept optional. Currently Linux with a gcc that conforms to
-C99 is supported for both 32 and 64 bit architectures.
-
-[grid="all"]
-`-------`---------------`---------------`--------------------------------------
-CPU     OS              State           Notes
--------------------------------------------------------------------------------
-x86_64  Debian          supported       Reference Platform
-x86     other Linux     supported       Please report distro specific problems
-armel   maemo5          supported       check fails in SDK (emulator bug)
-x86*    MacOS X         supported
-x86     OpenSolaris     mostly          Builds, but target check fails
-        *BSD            planned         Need volunteer for testing
--------------------------------------------------------------------------------
+specific things are kept optional. Currently Linux with a GCC that conforms to
+C99 is supported for both 32 and 64 bit architectures. For non-GCC compilers,
+some features are not available or degraded.
+
+[frame="topbot",options="header", cols="<,<,<,<"]
+|=================================================================================
+|CPU    |OS          |Compiler    |State
+|x86_64 |Debian      |gcc4        |supported footnote:[Reference Platform]
+|x86    |other Linux |gcc4        |supported footnote:[Please report distro specific problems]
+|armel  |maemo5      |gcc4        |supported footnote:[check fails in SDK (emulator bug)]
+|x86*   |Mac OS X    |gcc4        |supported
+|x86    |OpenSolaris |gcc4        |supported
+|x86    |OpenSolaris |suncc       |mostly    footnote:[some features are not
+available, needs more testing]
+|       |*BSD        |            |planned   footnote:[Need volunteer for testing]
+|=================================================================================
 
 NoBug has few mandatory dependencies on other software and libraries,
-some things such as valgrind support are optional and should be automatially
-detected during the build, i.e., when ./configure is called. Nevertheless it
-requires 'pkg-config' to be installed, you get some weird errors already at
-bootstrapping (autoreconf) when this is not available.
+some things such as valgrind support are optional and should be automatically
+detected by `./configure`. Nevertheless it
+requires 'pkg-config' to be installed or you'll get some weird errors at
+bootstrapping (`autoreconf`) already.
 
 
 Release Tarballs
 ~~~~~~~~~~~~~~~~
 
-Releases are available on:
-  http://www.pipapo.org/nobug-releases/
+Releases are available at:
+ http://www.pipapo.org/nobug-releases/[]
 
 Gpg signed tarballs are being used for distribution. The first step involves
 checking the signature:
@@ -86,7 +109,7 @@ checking the signature:
 This will produce a nobug-VERSION.tar.gz and report if the signature could be
 validated.
 
-Since they are built with gnu autotools, the usual build and install procedure
+Since they are built with GNU Autotools, the usual build and install procedure
 will work:
 
  $ tar xzvf nobug-VERSION.tar.gz
@@ -95,28 +118,35 @@ will work:
  $ cd build
  $ ../configure
  $ make
- $ make check           # optional, run the testsuite
- $ make install         # depending on distribution and setup, do this as root
+ $ make check           # optional, runs the testsuite
+ $ make install         # to be done as root,
+                        # depending on distribution and setup
 
 
-Development Version via git
+Development Version via Git
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can obtain a development version by using git.  The git repository can be
-cloned via:
-`git://git.pipapo.org/nobug` or mirrored at repo.or.cz
-`git://repo.or.cz/nobug.git`.
 
-Clone the git repository by:
+You can obtain a development version using Git.  The Git repository can be
+cloned from `git://git.pipapo.org/nobug`.
+
+Clone the Git repository with:
 
  $ git clone git://git.pipapo.org/nobug
 
-After cloning the repository, then bootstrap the autotools:
+After cloning the repository, then bootstrap the Autotools:
 
  $ cd nobug
  $ autoreconf -i               # creates the configure file
 
-Then the usual `cd build && ../configure && make && make install` (as above) will work.
-Careful users may run `make check` to run a testsuite before installing.
+Then the usual
+
+ $ cd build && ../configure && make && make install
+
+(as above) will work. Careful users may run
+
+ $ make check
+
+to run a testsuite before installing.
 
 
 Keeping Git Up To Date
@@ -126,9 +156,19 @@ To update to any new revision, just enter the nobug dir and
 
  $ git pull
 
-After that you can build as above (cd build && ../configure && make && make install).
-This default pull will update from the 'master' branch which is meant to be an on-going
-stable version (latest release + bugfixes).
+After that you can build as above
+
+ $ cd build && ../configure && make && make install
+
+This default pull will update from the 'master' branch which is meant to be an
+on-going stable version (latest release and bugfixes).
+
+Major new releases are assembled in the 'devel' branch, generally this is not
+considered production ready.
+
+All other branches are volatile and may be deleted or rebased anytime without
+further notice.
+
 
 What Is Installed
 ~~~~~~~~~~~~~~~~~
@@ -149,35 +189,36 @@ Currently, NoBug installs the following:
   * The `nobug_rbdump` utility to inspect NoBug ringbuffers.
 
 
-.Generating This Documentation
+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
-doc or the shipped 'README' which is actually this full nobug manual.
-Generating the documentation requires: gawk, asciidoc, graphviz and some
-toolchains to further process docbook (dblatex, ...).
+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 LaTeX. Check the `[header]` section of doc/latex.conf for required
+packages.
 
 Using NoBug
 -----------
 
 Your application will have to include the header file 'nobug.h' before NoBug
-can be used:
-
- #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.,
-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
-this phase; whereas the released phase of an application will usually only require
-sparse information, for which the RELEASE build-level has been conceived.
+can be used. Prior including this, a Build-level has to be choosen,
+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 this phase; whereas the
+released phase of an application will usually only require sparse information,
+for which the RELEASE build-level has been conceived.
 
 A build-level must always be specified, otherwise the compiler will complain
 while attempting to compile your application.  You can specifiy a build level in
@@ -186,12 +227,9 @@ build-level using the -D flag to your compiler.  Assuming we'd like to select
 the ALPHA build-level in your application, then your module would assume the
 following form:
 
-
  #define EBUG_ALPHA
  #include <nobug.h>
 
-
-
 Subsequently you'll have to link the appropriate library to your application.
 
 A number of different libraries are available to link depending on whether you
@@ -202,33 +240,34 @@ single-threaded applications:
 
 [source,sh]
 ----------------
-gcc -o mybinary $(WHATEVER_FLAGS) mymodule1.o ... mymodulen.o  ..../libs/libnobug.a 
+gcc -o mybinary  $(WHATEVER_FLAGS) \
+       mymodules.o ... -lnobug
 ----------------
 
 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: 
+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 
+gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
+       mymodules.o -lnobugmt
 ----------------
 
-Both libraries must be initialised  before they can be used.  There are a number
-of different ways to initialise the NoBug libraries.  One of the easiest ways
-to initialise the NoBug libraries is to use the `NOBUG_INIT` macro, which must
-be used before any features can be used or any thread is created. This is
-discussed in more detail in the xref:multithreading[multithreading] chapter.  
+The NoBug libraries must be initialised before they can be used. To initialise
+it call the `NOBUG_INIT` macro, which must be used before any NoBug features
+can be used or any thread is created. This is discussed in more detail in the
+xref:multithreading[multithreading] chapter.
 
 So putting all this together, our application using NoBug might look something
 like the following:
 
 
-[source,sh]
+[source,C]
 ----------------
+#define EBUG_ALPHA   /* If we don't use the -D Flag to cc */
 #include <nobug.h>   /* Include the NoBug API */
-#define EBUG_ALPHA   /* If we have not used the -D Flag in our makefile */
 
 int main()
 {
@@ -240,52 +279,95 @@ int main()
 
 
 
-
-
-
 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
 included.
 
+
+Autotools Support
+~~~~~~~~~~~~~~~~~
+
 A project using NoBug can use autoconf to check for execinfo and
 valgrind:
 
- AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
- PKG_HAVE_DEFINE_WITH_MODULES(VALGRIND, [valgrind])
+[source,sh]
+----------------
+AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
+PKG_CHECK_MODULES(VALGRIND, [valgrind],
+                            [AC_DEFINE(HAVE_VALGRIND_H)])
+----------------
 
 For Multithreaded programs, you should also check for the availability of pthreads
-and flavour
+and flavour with the `ACX_PTHREAD` maxro, see:
 
- ACX_PTHREAD
++http://ac-archive.sourceforge.net/ac-archive/acx_pthread.html[]+
 
 When the resulting `HAVE_PTHREAD`, `HAVE_EXECINFO_H` and
 `HAVE_VALGRIND_H` are defined by the configure script, the
 relevant features become available.
 
-NoBug then defines `NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and
-`NOBUG_USE_EXECINFO` to 1. If you do not want to use any of these features in
-NoBug, you can override these macros by setting to 0 before including nobug.h.
+`NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and `NOBUG_USE_EXECINFO` will be
+defined depeding on the information gathered by configuration. If you do not
+want to use any of these features in NoBug, you can override these macros by
+setting them to `0` before including 'nobug.h'.
 
 If `NVALGRIND` is defined, there will be no support for valgrind.
 
-
-
 There are many other macros which can be set and overridden by the user to
 control behavior. Your help would be appreciated in expanding this documentation
 if you find some features useful; or simply contact any of the authors.
 
 
+.Using Nobug from a Project using autoconf/automake
+
+Here is a rather elaborate snippet how to put this all together into a
+`configure.ac` file:
 
-.Using Nobug from a Project using autoconf
 [source,sh]
 ----------------
-PKG_CHECK_MODULES(NOBUGMT_LUMIERA, [nobugmt >= 0.3rc1],
-                                 AC_DEFINE(HAVE_NOBUGMT_H),
-                                 AC_MSG_ERROR([NoBug pkg-config metadata missing])
+# define autoheader templates for the config macros
+AH_TEMPLATE(EBUG_ALPHA,
+        [Define to 1 for selecting NoBug ALPHA build level])
+AH_TEMPLATE(EBUG_BETA,
+        [Define to 1 for selecting NoBug BETA build level])
+AH_TEMPLATE(NDEBUG,
+        [Define to 1 for selecting NoBug RELEASE build level])
+
+# set configure options up
+AC_ARG_ENABLE(alpha, AC_HELP_STRING([--enable-alpha],
+                [select NoBug ALPHA build level]),
+        nobug_level=alpha
+        AC_DEFINE(EBUG_ALPHA),
+[
+AC_ARG_ENABLE(beta, AC_HELP_STRING([--enable-beta],
+                [select NoBug BETA build level]),
+        nobug_level=beta
+        AC_DEFINE(EBUG_BETA),
+[
+AC_ARG_ENABLE(release, AC_HELP_STRING([--enable-release],
+                [select NoBug RELEASE build level]),
+        nobug_level=release
+        AC_DEFINE(NDEBUG),
+
+# default to ALPHA
+        nobug_level=alpha
+        AC_DEFINE(EBUG_ALPHA)
+)])])
+
+# check for required and optional packages
+ACX_PTHREAD
+AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
+PKG_CHECK_MODULES(VALGRIND, [valgrind],
+        AC_DEFINE(HAVE_VALGRIND_H))
+
+# finally check for nobug itself, multithreaded here
+PKG_CHECK_MODULES(NOBUGMT_EXAMPLE, [nobugmt >= 201006.1],
+        AC_DEFINE(HAVE_NOBUGMT_H),
+        AC_MSG_ERROR([NoBug pkg-config metadata missing])
 )
 ----------------
 
-Checking for Additional Tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Additional Tools
+~~~~~~~~~~~~~~~~
 
 Various peripheral tools can be used by NoBug depending on the requirements
 of the application and the detail desired by the user.  Such tools can provide
@@ -297,32 +379,7 @@ excluding such tools.
 At the moment NoBug supports the optional inclusion of gdb, valgrind and support
 for multi-threaded applications and the information that can be provided by
 these tools.  However, support for other tools may be supplied in the future,
-e.g. the dbx debugger on OpenSolaris. 
-
-Such tools can be easily queried on the system and if they are available on a
-particular system, they can be used by NoBug to provide even more information on
-the application using NoBug.  If such tools are not available or are not
-required by the user for one reason or other, then NoBug will happily function
-as usual, just without the extra information.
-
-Testing the availability of such tools on a particular system can be achieved
-using autoconf, as illustrated in the following:
-
-`*NOBUG_USE_VALGRIND*`::
-   `1`:: Use valgrind
-   `0`:: Do not use valgrind
-
-`*NOBUG_USE_PTHREAD*`::
-   `1`:: Support for multi-thread applications
-   `0`:: Single-threaded applications
-
-`*NOBUG_USE_EXECINFO*`::
-   `1`:: Backtrace information
-   `0`:: No backtrace information
-
-These macros are then automatically defined when the configuration system
-provides the associated `HAVE_*` macros, but can then be overridden by the user,
-depending on the user's requirements.
+e.g. the dbx debugger on OpenSolaris.
 
 
 Link Appropriate Library
@@ -339,44 +396,44 @@ uses multiple dynamic libraries which use NoBug or you build a dynamic
 library, then you have to link against the dynamic library.
 
 You can use the `pkg-config` tool to gather information about NoBug in
-your build system.
+your build system. For example you can query the NoBug version which is
+installed on your system:
 
-Release builds remove all assertions, but logging is still kept. We
-make the assumption that bugs which were not covered in alpha and beta
-builds will not easily show up in releases because the assertions
-there were not sufficient. Furthermore, end users are not test bunnies
-and will not provide good bug reports anyway. If there is a problem in
-a release build, try to track down the cause using a beta build from
-the same source.
+ $ pkg-config --modversion nobug
+ 201006.1
 
 Initialization
 --------------
 
-Global init
-~~~~~~~~~~~
-
-Before anything from NoBug can be used, NoBug must be initialised.  This is
-performed by calling one of the `NOBUG_INIT_` macros.
-
-The simpliest such macro among the initialising set is the following:
+Global Initialization
+~~~~~~~~~~~~~~~~~~~~~
 
-  NOBUG_INIT()
+Before anything from NoBug can be used, NoBug must be initialised. This
+is archived by calling the `NOBUG_INIT()` macro before using any other of the
+NoBug facilities.
 
 `NOBUG_INIT` can be called more than once, subsequent calls will be a no-op,
 thus initialising in main and in libraries won't interfere with one another.
 
-In other words, `NOBUG_INIT` is usually the first call to NoBug.
+Care must be taken when one already using NoBug features from dynamic
+initialized things in C++, one has to ensure that NoBug gets initialized first
+possibly by pulling up a singleton at very first.
+
+
+Destroying NoBug
+~~~~~~~~~~~~~~~~
 
-.Destroying NoBug
 Since NoBug is intended to be available throughout its whole lifetime,
 destroying it is not to be advised. Nevertheless, there is a destroy function
- void nobug_destroy (void)
+
+ void nobug_destroy (void);
 
 to shutdown NoBug, and this frees all resources associated with it.
 This is mostly used in the NoBug testsuite itself to check for leaks,
 and it might be useful for other programs which employ some kind of
 leak checker.
 
+
 Init logging Flags
 ~~~~~~~~~~~~~~~~~~
 
@@ -393,27 +450,32 @@ or one of the C++ compatibility macros.
 
 This is documented later in the xref:logconfig[logging configuration] chapter.
 
+
 Threads
 ~~~~~~~
 
 In Multithreaded programs you should assign an identifier to each
 thread. A thread identifier is a string which will be automatically
-appended with an underscore and a incrementing integer. It is is created with:
+appended with an underscore and an incrementing integer. It is is
+created using the following:
 
   NOBUG_THREAD_ID_SET(name)
 
-Calling `NOBUG_THREAD_ID_SET("worker")` will yield in a thread
-identifier 'worker_1' for example.
+For example, calling `NOBUG_THREAD_ID_SET("worker")` will result in a thread
+identifier 'worker_1'.
 
-If you don't set an identifier, then NoBug will assign an automatic one.
-This is further documented in the xref:multithreading[multi threading]
+If you don't set an identifier, then NoBug will automatically assign
+one.  This is further documented in the xref:multithreading[multi threading]
 section of this manual.
 
-[[initexample]]
-.Initialization
-[source,c]
+
+.Initialization example
+
+Thus the boilerplate code to pulling up NoBug in a multithreaded program looks
+like (omit `NOBUG_THREAD_ID_SET()` in single threaded programs):
+[source,C]
 -------------------------------------------------------
-#include "nobug.h"
+#include <nobug.h>
 NOBUG_DEFINE_FLAG(example);
 
 ...
@@ -428,9 +490,8 @@ int main()
 }
 -------------------------------------------------------
 
-[[buildlevel]]
-Debugging Information Granuality: The Build Levels
---------------------------------------------------
+Debugging Information Granularity: The Build Levels
+---------------------------------------------------
 
 There are three different levels of debugging information available: alpha, beta
 and release.  One of these levels must be specified before compiling, otherwise
@@ -439,37 +500,43 @@ an error while compiling will occur.
 
   *ALPHA*::
        This debugging level is envisaged for the development phase of a project
-       where exhaustive testing and logging are required.
+       where exhaustive testing and logging are required. All NoBug features
+        are enabled.
   *BETA*::
         This debugging level is more appropriate for projects beyond the
-       development phase and ready for trials in the field and users willing to
-       test the software.
+       development phase and ready for field-testing with users willing to
+       test the software. The most expensive debugging features are disabled
+       at this level.
   *RELEASE*::
-       This level is for final, end-users.
+       This level is for final, end-users. Logging is mostly retained but
+       assertions and other checking is disabled.
 
 .Select a Build Level
-A logging level can be selected by either using a define in one of the
-applications' modules, or by passing the appropriate level using the -D switch
+A logging level can be selected by either using a define before including
+`nobug.h`, or by passing the appropriate level using the -D switch
 to the compiler:
 
-    *ALPHA*::   -DEBUG_ALPHA (`#define EBUG_ALPHA`)
+    *ALPHA*::
+       `-DEBUG_ALPHA` / `#define EBUG_ALPHA`
 
-    *BETA*::    -DEBUG_BETA (`#define EBUG_BETA`)
+    *BETA*::
+       `-DEBUG_BETA` / `#define EBUG_BETA`
 
-    *RELEASE*:: -DNDEBUG (`#define NDEBUG`)
+    *RELEASE*::
+       `-DNDEBUG` / `#define NDEBUG`
 
-If none of the above switches has been set, NoBug will abort the
+If a log level has not been selected, NoBug will abort the
 compilation with an error.
 
-Logging
--------
+Logging Concepts
+----------------
 
-Nearly all NoBug Macros emit some log message. NoBug gives the user fine
-grained control over these log messages to display only interesting information
-without loosing details.
+Nearly all NoBug Macros emit some xref:logformat[log message]. NoBug gives
+the user fine grained control over these log messages to display only
+interesting information without loosing details.
 
 Log messages can be routed to various destinations.  The following destintaions
-are available: 
+are available:
 
   *RINGBUFFER*::
         The underlying storage backend. Messages are appended to the
@@ -493,17 +560,18 @@ are available:
         There are hooks which allow the programmer to catch logmessages and
         display them in an application which are defined by the application.
 
-Each logmessage has a priority describing its severity in the same way as
+Each log message has a priority describing its severity in the same way as
 syslog messages do.
 
-All non-fatal messages are associated with a programmer defined flag describing
-the source of the message (subsystem, module, ...).
+All non-fatal messages are associated with a programmer defined flag
+describing the source of the message (subsystem, module, ...). This is
+referred to as 'channels' in other logging systems. xref:logflags[Flags] make
+it possible to configure logging in much detail at runtime.
 
 Putting this all together: A user can define which source/flag will be logged at
 what priority level and to which destination. To make this all easier, NoBug
 tries to provide reasonable defaults.
 
-[[logconfig]]
 Configuration
 ~~~~~~~~~~~~~
 
@@ -513,84 +581,82 @@ Each log macro has an explicit or implicit log-level which
 correspondends to syslog levels. Logging is only emitted when the
 message is more severe or the same as a defined limit.
 
-[[logdefaults]]
-.Default levels for logging
-[grid="all"]
-`````~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-             , ALPHA, BETA   , RELEASE,
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*ringbuffer* , TRACE, INFO   , NOTICE , ringbuffer must always be most verbose
-*console*    , INFO , NOTICE , -1     , no log to console in release
-*file*       , TRACE, NOTICE , WARNING,
-*syslog*     , -1   , NOTICE , WARNING, no syslog for test runs
-*application*, INFO , WARNING, ERROR  ,
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+INDEX Default levels for logging;loggingleveldefaults; table showing defaults log levels
+[frame="topbot",options="header"]
+|===============================================================================
+|            |ALPHA    |BETA    |RELEASE
+|ringbuffer footnote:[ringbuffer must always be most verbose] |TRACE    |INFO    |NOTICE
+|console     |INFO     |NOTICE  |-1 footnote:[no log to console in release]
+|file        |TRACE    |NOTICE  |WARNING
+|syslog      |-1 footnote:[no syslog for test runs]      |NOTICE  |WARNING
+|application |INFO     |WARNING |ERROR
+|===============================================================================
 
 Depending on the build level, there is a default logging target and a default
 limit which is selected when the user doesn't specify one.
 
-The following default limits are available:
+.The following default limits are
 
-  * In *ALPHA* builds, `NOBUG_LOG_LIMIT_ALPHA` is used which defaults to `LOG_INFO`
-  * In *BETA* builds, `NOBUG_LOG_LIMIT_BETA` is used and defaults to `LOG_WARNING`
-  * In *RELEASE* builds, `NOBUG_LOG_LIMIT_RELEASE` is used and defaults to `LOG_CRIT`
+  In *ALPHA* builds::
+     `NOBUG_LOG_LIMIT_ALPHA` is used which defaults to `LOG_INFO`
+  In *BETA* builds::
+     `NOBUG_LOG_LIMIT_BETA` is used and defaults to `LOG_WARNING`
+  In *RELEASE* builds::
+     `NOBUG_LOG_LIMIT_RELEASE` is used and defaults to `LOG_CRIT`
 
-The default targets are:
+.The default targets are
 
-  * In *ALPHA* builds, `NOBUG_LOG_TARGET_ALPHA` is used which defaults to
-    `NOBUG_TARGET_CONSOLE`
-  * In *BETA* builds, `NOBUG_LOG_TARGET_BETA` is used and defaults to
-    `NOBUG_TARGET_FILE`
-  * In *RELEASE* builds, `NOBUG_LOG_TARGET_RELEASE` is used and defaults to
-    `NOBUG_TARGET_SYSLOG`
+  In *ALPHA* builds::
+    `NOBUG_LOG_TARGET_ALPHA` defaulting to `NOBUG_TARGET_CONSOLE`
+  In *BETA* builds::
+     `NOBUG_LOG_TARGET_BETA` defaulting to `NOBUG_TARGET_FILE`
+  In *RELEASE* builds::
+     `NOBUG_LOG_TARGET_RELEASE` defaulting to `NOBUG_TARGET_SYSLOG`
 
+You can override all these values with other limits or targets before
+including 'nobug.h'. As an alternative, `NOBUG_LOG_LIMIT` and
+`NOBUG_LOG_TARGET` can be defined to override all defaults at once.
 
-You can override all these values with your own values. As an alternative,
-`NOBUG_LOG_LIMIT` and `NOBUG_LOG_TARGET` can be defined before
-including "nobug.h" to override all defaults.
-
-[[logflags]]
 Log Flags
 ~~~~~~~~~
 
 Flags are used to inform NoBug about subsystems/modules or even finer
-grained sections of the code. These are referred to as 'channels' in other 
+grained sections of the code. These are referred to as 'channels' in other
 logging libraries.
 
-A flag should be declared in a headerfile using the following mechanism:
+Flags are generally used as follows:
 
-[[DECLARE_FLAG]]
- NOBUG_DECLARE_FLAG(flagname)
+    . Declare the flag.
+    . Define the flag.
+    . Initialise the flag.
 
-It is advisable to do so in one of your header files.
+To declare a flag, it is suggested to do so in a header file:
+
+ NOBUG_DECLARE_FLAG(flagname)
 
-Furthermore, the flag must be defined in some implementation file by using one
-of the following schemes:
+The flag should then be defined most appropriately in some implementation file
+by using one of the following macros:
 
-[[DEFINE_FLAG]]
  NOBUG_DEFINE_FLAG(flagname)
 
 or:
 
-[[DEFINE_FLAG_LIMIT]]
  NOBUG_DEFINE_FLAG_LIMIT(flagname, limit)
 
 Moreover, macros are available that accept a 'parent' flag as a parameter, which is then
 used to initialize the defaults from another flag:
 
-[[DEFINE_FLAG_PARENT]]
  NOBUG_DEFINE_FLAG_PARENT(flagname, parent)
 
 or
 
-[[DEFINE_FLAG_PARENT_LIMIT]]
  NOBUG_DEFINE_FLAG_PARENT_LIMIT(flagname, parent, limit)
 
-This can be used to create hierachies of flags
+This can be used to create hierarchies of flags.
 
 
-[[Cplusplus_logflags]]
-.C++ support, C++ logflags
+C\++ support, C++ logflags
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Additional macros are available for applications written in C++:
 
@@ -603,21 +669,38 @@ These macros statically initialize the flags when they are defined, there is no
 need to call `NOBUG_INIT_FLAG()` (see below).
 
 
-.Force declarations only
+Logging Flag Initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When the the following preprocessor constant is defined to be `1`:
+After a flag has been declared and defined, it has to be initialised:
 
-[[DECLARE_ONLY]]
- NOBUG_DECLARE_ONLY
+ NOBUG_INIT_FLAG(flagname)
+
+or
+
+ NOBUG_INIT_FLAG_LIMIT(flagname, default)
+
+Use either of these macros once at the begining your program for each flag.
+This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
+initializing the given flag dynamically.
+
+For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
+initialized as in the xref:loggingleveldefaults[table above], while
+`NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
+target (depending on build level) to `level`.
+
+
+Force declarations only
+^^^^^^^^^^^^^^^^^^^^^^^
 
-then *all* definitions here (`NOBUG_DEFINE_*`)
-become declarations only.  When this is defined to be `0` (which is the
-default) then all definitions behave as described.
-This can be used to construct a headerfile which only contains
-definitions, but, by default, yield only declarations. This provides one
-convenient single point to maintain flag configurations.
+When `NOBUG_DECLARE_ONLY` defined to be `1` then all flag definitions here become
+declarations only. When this is defined to be `0` (which is the default) then
+all definitions behave as described. This can be used to construct a
+headerfile which only contains definitions, but, by default, yield only
+declarations. This provides one convenient single point to maintain flag
+configurations.
 
-.Maintaining flags in a single header 'flags.h'
+.flags.h
 [source,c]
 ----
 #include <nobug.h>
@@ -643,93 +726,97 @@ NOBUG_DEFINE_FLAG(example);
 ----
 
 .flags.c
-[source,c]
+[source,C]
 ----
 #define FLAGS_C
 #include "flags.h"
 ...
 ----
 
+Controlling what gets logged
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.Logging Flag Initialization
-
-Next you should call
-
- NOBUG_INIT_FLAG(flagname)
-
-or
-
- NOBUG_INIT_FLAG_LIMIT(flagname, default)
-
-once at the start of your program for each flag.
+The `NOBUG_INIT_FLAG...` series of macros parse the environment variable
+'$NOBUG_LOG'. This enviromnet variable is thus used to configure what is
+logged at runtime. Its syntax is as following:
 
-For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are initialized
-as in the xref:logdefaults[table above], while
-`NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the
-default target (depending on build level) to `level`.
-
-[[NOBUG_ENV]]
-Control what gets logged
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The `NOBUG_INIT_FLAG...` calls parsing the environment variable
-'NOBUG_LOG' to configure what gets logged at runtime. The syntax is as
-following:
-
-.Formal Syntax for log control
 [source,prolog]
 ----
- logdecl_list --> logdecl, any( ',' logdecl_list).
+logdecl_list --> logdecl, any( ',' logdecl_list).
 
- logdecl --> flag, opt(limitdecl, any(targetdecl)).
+logdecl --> flag, opt(limitdecl, any(targetdecl)).
 
- flag --> "identifier of a flag".
+flag --> "identifier of a flag".
 
- limitdecl --> ':', "LIMITNAME".
+limitdecl --> ':', "LIMITNAME".
 
- targetdecl --> '@', "targetname", opt(targetopts).
+targetdecl --> '@', "targetname", opt(targetopts).
 
- targetopts --> '(', "options for target", ')', opt(targetopts).
+targetopts --> '(', "options for target", ')', opt(targetopts).
 ----
 
-Roughly speaking, 'NOBUG_LOG' contains a comma separated list of declarations for
-flags which are the name of the flag followed by a limit which is written in
-all uppercase letters and preceeded by a colon, followed by target declarations
-which are names of the targets, introduced by a at sign. Target declarations
-can have option, described in the next section. Limit and target
-declarations are optional and then choosen from the defaults table above. These
-defaults are currently just an guess what should be useable and might be
-redefined in future.
+Roughly speaking, '$NOBUG_LOG' contains a comma separated list of declarations
+for flags, which is the name of the flag followed by a limit which is all
+written in uppercase letters and preceeded by a colon, followed by target
+declarations which are the names of targets, introduced by an at sign. Target
+declarations can have options, which are described in the next section. Limit
+and target declarations are optional and defaults are selected from the
+xref:loggingleveldefaults[table above]. The defaults presented here are
+currently an approximation of what might be viable. The default values used
+here may be redefined in a future release.
 
-.Targets and Options
+Targets and Options
+^^^^^^^^^^^^^^^^^^^
 
 The Following options are available:
 
- `@ringbuffer`::
-   `(file=_filename_)`:: set filename backing the ringbuffer
-   `(size=_nnn_)`::      set size of the ringbuffer
-   `(append)`::          don't erase existing ringbuffer
-   `(keep)`::            keep file after application end
-   `(temp)`::            unlink file instantly at creation
-
- `@console`::
-   `(fd=n)`::            redirect console output to fd n
-
- `@file`::
-   `(name=_filename_)`:: log to filename
-   `(append)`::          append to (existing) log
-
- `@syslog`::
-   `(ident=_name_)`::    global prefix for syslog
-   `(cons)`::            log to system console if syslog is down
-   `(pid)`::             include pid in log
-   `(perror)`::          log to stderr as well
-
-
-.How the NOBUG_LOG is used
+`@ringbuffer`::
+  `(file=`'filename'`)`:::
+    set 'filename' for the backing ringbuffer
+  `(size=`'nnn'`)`:::
+    set size of the ringbuffer to 'nnn' bytes, rounded-off up to the next page
+    boudary
+  `(append)`:::
+    don't erase existing ringbuffer, start where it left off
+  `(keep)`:::
+    keep file after application ends
+  `(temp)`:::
+    unlink file instantly at creation
+
+The default ringbuffer is a temporary file in '/tmp' with the `temp` option.
+This means it will not be available and accessible for inspection, but it also
+won't leave any stale data behind when the application ends.
+
+
+`@console`::
+  `(fd=`'n'`)`:::
+    redirect console output to fd 'n'
+
+When running under a debugger, NoBug tries to use debugger facilities
+to print console messages.
+
+`@file`::
+  `(name=`'filename'`)`:::
+    log to 'filename'
+  `(append)`:::
+    append to (existing) logfile
+
+`@syslog`::
+  `(ident=`'name'`)`:::
+    global prefix for syslog
+  `(cons)`:::
+    log to system console if syslog is down
+  `(pid)`:::
+    include the process identifier in the log
+  `(perror)`:::
+    log to stderr as well (Not available on all systems)
+
+
+.How $NOBUG_LOG is used
 [source,sh]
 ----
-# set the limit of the default target a default limit (see table above)
+# set limit to the default target and default limit
+# (see table above)
 NOBUG_LOG='flag,other'
 
 # set the limit of the default target to DEBUG
@@ -739,23 +826,48 @@ NOBUG_LOG='flag:DEBUG'
 NOBUG_LOG='flag:DEBUG@console@syslog'
 
 # trace 'other' to a persistent ringbuffer
-NOBUG_LOG='other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
+NOBUG_LOG=\
+ 'other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
 ----
+Predefined Flags
+~~~~~~~~~~~~~~~~
+
+There are some debugging flags which are predefined by NoBug.
+
+.NOBUG_ON
+
+The flag `NOBUG_ON` is always enabled at LOG_DEBUG level. This is
+static and can not be changed.
+
+.NOBUG_ANN
+
+The flag `NOBUG_ANN` is used for the source annotations. This is
+static and can not be changed. It differs from `NOBUG_ON` as in
+never logging to syslog and only define a LOG_WARNING limit for the
+application callback.
+
+.nobug
+
+Actions on NoBug itself will be logged under the `nobug` flag itself.
+To see whats going on you can enable it with `NOBUG_LOG=nobug:TRACE`.
+This is particulary useful to check if `NOBUG_INIT_FLAG()` is called on all flags.
+
 
 .Using log flags (example.c)
 [source,c]
 ----
-#include "nobug.h"
+#include <nobug.h>
 
 NOBUG_DEFINE_FLAG (test);
 
 int main()
 {
-   /* NOBUG_INIT;  // not needed because of NOBUG_INIT_FLAG */
+   NOBUG_INIT;
    NOBUG_INIT_FLAG (test);
 
    TRACE (test, "Logging enabled");
    TRACE (NOBUG_ON, "Always on");
+   return 0;
 }
 ----
 
@@ -764,58 +876,92 @@ int main()
 ----
 $ cc -DEBUG_ALPHA -lnobug example.c
 $ ./a.out
-0000000002: TRACE: example.c:11: main: Always on
+0000000003: TRACE: example.c:11: -: main: Always on
 
 $ NOBUG_LOG=test:TRACE ./a.out
-0000000001: TRACE: example.c:10: main: Logging enabled
-0000000002: TRACE: example.c:11: main: Always on
+0000000003: TRACE: example.c:10: -: main: Logging enabled
+0000000004: TRACE: example.c:11: -: main: Always on
 ----
 
-Predefined Flags
-~~~~~~~~~~~~~~~~
-
-There are some debugging flags which are predefined by NoBug.
-
-[[NOBUG_ON]]
-.NOBUG_ON
-
-The flag `NOBUG_ON` is always enabled at LOG_DEBUG level. This is
-static and can not be changed.
-
-[[NOBUG_ANN]]
-.NOBUG_ANN
-
-The flag `NOBUG_ANN` is used for the source annotations. This is
-static and can not be changed. It differs from `NOBUG_ON` as in
-never logging to syslog and only define a LOG_WARNING limit for the
-application callback.
-
-[[nobug_flag]]
-.nobug (flag)
-
-Actions on NoBug itself will be logged under the `nobug` flag itself.
-When you want to see whats going on (useful to check if you call
-`NOBUG_INIT_FLAG()` on all flags) you can enable it with `NOBUG_LOG=nobug:TRACE`.
+Log Line Format
+~~~~~~~~~~~~~~~
 
-Macros
-------
+Logging follows a rather rigid format and is not configurable. This is
+intentional to make it easier to compare and process logs afterwards. NoBug is
+designed with the goal to effectively do very fine grained logging and then
+analyze this logs later, either manually or with further tools.
+
+A typical log looks like:
+
+ 0000000003: TRACE: test.c:10: thread_1: main: message
+ 0000000003! TRACE: test.c:10: thread_1: main: continued
+ 0000000005: NOTICE: test.c:15: thread_1: main: next
+
+The components are delimited by ": " or in one case by "! " are as following:
+
+ . *Sequence Number* +
+   Each logging event increments a counter, for preformance (and privacy)
+   reasons we do not use timestamps here. The sequence number is represented by
+   ten decimal digits, overflows are not specially handled. There is a special
+   case that when the final message (see below) spans more log lines, then the
+   delimiter after the sequence number is a "! " and not ": ". The sequence
+   numbers in a log can be sparse because not every event is send to the log,
+   the left out lines are still available in the ringbuffer.
+
+ . *NoBug Facility* +
+   Describes what NoBug macro produced the output. This can be a simple
+   annotation or logging as well as assertions or one of the more complex
+   NoBug facilities.
+
+ . *File and Linenumber* +
+   The filename is only printed without it's path. This is important for some
+   reasons. First it makes the log vastly more readable and second depending
+   on source location and build system and configuration thereof paths are not
+   easily reproducible, this makes it hard to use simple tools like grep or
+   diff on logs generated on different systems. For some messages the filename
+   and/or the linenumber is not available or meaningless, a "-" is used then.
+
+ . *Thread Identifier* +
+   Shows which thread generated this message. The single threaded version of
+   NoBug uses always "-".
+
+ . *Function Name* +
+   Gives the function in which the logging occured. For a lot macros it is
+   possible to pass a context (file, line and function name) around to make it
+   possible to delegate validation and logging to some special functions while
+   still being able to present the context where the call originated. NoBug
+   only uses the function name as identifier here no pretty printed prototype
+   or demangled C++ method. The reason for this is that neither is well
+   specified an may yield to non unique results which may even interfere with
+   the logging format syntax and thus make it very unreliable to write tools
+   to process logs. Some contexts dont provide a function name, a "-" is used
+   then.
+
+ . *Message* +
+   The rest of the log line is the user-defined and optional message part.
+   There are no constraints on the format and one should constrain himself to
+   print only meaningful textual information. Embedded newlines will always be
+   translated into a new logging line as shown in the example above.
+
+Macros Overview
+---------------
 
 The NoBug interface is almost completely implemented using
 preprocessor macros. This is required because NoBug uses the
-`+++__FILE__+++`, `+++__LINE__+++` and `+++__func__+++` macros to
++$$__FILE__$$+, +$$__LINE__$$+ and +$$__func__$$+ macros to
 log information on the current file, line number and function.
-Moreover, all the flat namespace uppercase identifiers make it ease
+Moreover, all the flat namespace uppercase identifiers make it easy
 to recognise the macros in source code.
 
-All macros are available without condition with a `NOBUG_...` prefix.
-Many macros (the common cases) are also available without this prefix
-as a convenience, however macros without this prefix must not have
-been previously defined. When `NOBUG_DISABLE_SHORTNAMES` is defined
-before including 'nobug.h', then only the `NOBUG_` prefixed macros
-are available and the short forms will never be defined.
+All macros are available without condition with a `NOBUG_...` prefix. Many
+macros (the common cases) are also available without this prefix as a
+convenience, however macros without this prefix must not have been previously
+defined. When `NOBUG_DISABLE_SHORTNAMES` is defined before including
+'nobug.h', then only the `NOBUG_` prefixed macros are available and the short
+forms will never be defined.
 
-A set of macros are provided by NoBug that are postfixed by `..._IF`.
-These macros have the following form:
+A set of macros are provided by NoBug that are postfixed by `..._IF`. These
+macros have the following form:
 
   * `..._IF(when, ...)`
 
@@ -825,12 +971,12 @@ They perform the desired action only if `when` is true. For example:
 
 The assertion will only be performed if `foo` is non `NULL`.
 
-NoBug also also contains a facility to pass the source context (file,
-line, function) around, this can be used to write functions which
-handle things where one is more interested in the context of the caller
-than the location where the macros appears.
+NoBug also contains a facility to pass the xref:NOBUGCONTEXT[source context]
+(file, line, function) around, this can be used to write functions which
+handle things where one is more interested in the context of the caller rather
+than the location where the macro appears.
 
-This macros are postfixed with `..._CTX` and take an extra context
+These macros are postfixed with `..._CTX` and take an extra context
 parameter (usually at last but before the logging format specifier and
 any variable argument list). The context parameter must be of type
 `const struct nobug_context`.
@@ -838,7 +984,7 @@ any variable argument list). The context parameter must be of type
 When the `_CTX` context form is used together with the conditional `_IF`
 form then the suffix of the macros is always `..._IF_CTX`.
 
-The macros which take a context have no short form and must always be
+Macros that can accept a context have no short form and must always be
 prefixed with `NOBUG_...`.
 
 Parameters types
@@ -847,22 +993,22 @@ Parameters types
 We use names for parameters which describe their type. These names are
 orthogonal through all macro definitions.
 
-[grid="all"]
-`---------`------------------------------------------------------------------
-`when`    Assertion is only performed if expression `when` is true at runtime
-`expr`    Test without side effects
-`flag`    Flag to enable custom logging groups
-`type`    Data type to be checked as a single identifier name
-`pointer` Pointer to type
-`lvl`     Log level
-`depth`   Depth for invariants and dumps
-`context` Source context of type `struct nobug_context`
-`...`     printf-like format string followed by its arguments
----------------------------------------------------------------------------
-
-[[NOBUG_CONTEXT]]
+[cols="1,5",frame="topbot"]
+|==============================================================================
+|`when`    |Assertion is only performed if expression `when` is true at runtime
+|`expr`    |Test without side effects
+|`flag`    |Destination flag for control logging at runtime
+|`type`    |Data type to be checked as a single identifier name
+|`pointer` |Pointer to type
+|`lvl`     |Log level
+|`depth`   |Depth for invariants and dumps
+|`context` |Source context of type `struct nobug_context`
+|`...`     |printf-like format string followed by its arguments
+|==============================================================================
+
 Source Contexts
 ~~~~~~~~~~~~~~~
+
  NOBUG_CONTEXT
  NOBUG_CONTEXT_NOFUNC
 
@@ -872,30 +1018,36 @@ NoBug passes information about the source location of a given statement in
 function name and must be used when the function context is not available
 like in static initialization etc..
 
-Assertions
-----------
+Macros for Assertions
+---------------------
+
+The assertion set of macros provide a convenient status check on whether
+to continue running, or abort execution as some condition was not fulfilled.
+Assertion failures are fatal and must abort the application immediately by
+calling the xref:ABORT[NOBUG_ABORT] macro which in turn may call a user defined
+xref:abortcallback[abort hook].
 
-[[CHECK]]
 .CHECK
+
  CHECK(expr, ...)
  CHECK_IF(when, expr, ...)
 
-This assertion is never optimized out. Its main purpose is for implementing
-testsuites where one want to assert tests independent of the build level
+This assertion is never optimized out. Its main purpose is in implementing
+test suites where one would like to assert tests independent of the build level.
 
-[[REQUIRE]]
 .REQUIRE
+
  REQUIRE(expr, ...)
  REQUIRE_IF(when, expr, ...)
  NOBUG_REQUIRE_CTX(expr, context,...)
  NOBUG_REQUIRE_IF_CTX(when, expr, context, ...)
 
-Precondition (input) check. Use these macros to validate input a
-function receives. The checks are enabled in *ALPHA* and *BETA* builds and
-optimized out in *RELEASE* builds.
+Precondition (input) check. Use these macros to validate the input a
+function receives. The checks are enabled in *ALPHA* and *BETA* builds,
+but have not effect in *RELEASE* builds.
 
-[[ENSURE]]
 .ENSURE
+
  ENSURE(expr, ...)
  ENSURE_IF(when, expr, ...)
  NOBUG_ENSURE_CTX(expr, context, ...)
@@ -903,37 +1055,34 @@ optimized out in *RELEASE* builds.
 
 Postcondition (progress/output) check. Use these macros to validate the
 data a function produces (example: return value). `ENSURE` is enabled
-unconditionally in *ALPHA* builds and optimized out in *BETA* builds for
+unconditionally in *ALPHA* builds and have no effect in *BETA* builds for
 scopes which are tagged as `CHECKED`.
 
 The `ENSURE_IF` variants are enabled in *ALPHA* and *BETA* builds.
 
-In *RELEASE* builds this checks are
-always optimized out, scopes tagged as `UNCHECKED` are not permitted.
+In *RELEASE* builds these checks are optimized out.
 
-[[ASSERT]]
 .ASSERT
+
  ASSERT(expr, ...)
  ASSERT_IF(when, expr, ...)
  NOBUG_ASSERT_CTX(expr, context, ...)
  NOBUG_ASSERT_IF_CTX(when, expr, context, ...)
 
 Generic check. Use these macros when you want to validate something
-which doesn't fall into one of the above categories. A example is when
-a library function can return a unexpected result (scanf with syntax
-error in the formatstring, when a constant/literal formatstring is
-expected). The checks are enabled in *ALPHA* and *BETA* builds and
-optimized out in *RELEASE* builds.
+which doesn't fall into one of the above categories. Generally to be
+avoided! The checks are enabled in *ALPHA* and *BETA* builds and
+have no effect in *RELEASE* builds.
 
-[[assert]]
 .assert
+
  assert(expr)
 
 NoBug overrides the standard `assert` macro, using `NOBUG_ASSERT`.
 This is just a compatibility feature, its use is not suggested.
 
-[[INVARIANT]]
 .INVARIANT
+
  INVARIANT(type, pointer, depth)
  INVARIANT_IF(when,type, pointer, depth)
  INVARIANT_ASSERT(expr, ...)
@@ -945,32 +1094,32 @@ otherwise optimized out.
 
  TODO: describe how to create invariant checks
 
-Logging Macros
---------------
-
-Logging targets a flag (except for `ECHO`) and is done at a log-level relating to syslog levels.
+Macros That Log Information
+---------------------------
 
-NOTE: there is no logging macro for `LOG_EMERG`, this is only used by the assertions as fatal message
+Logging targets a flag (except for `ECHO`) and is done at a log-level related to syslog levels.
 
-[[ECHO]]
 .ECHO
+
  ECHO(...)
 
 Never optimized out, logs at LOG_NOTICE level. Its main purpose is for implementing
-testsuites where one want to print and log messages independent of the build level
+testsuites where one would like to print and log messages independent of the build level
 
-[[ALERT]]
 .ALERT
+
  ALERT(flag, ...)
  ALERT_IF(when, flag, ...)
  NOBUG_ALERT_CTX(flag, context, ...)
  NOBUG_ALERT_IF_CTX(when, flag, context, ...)
 
-This is the most critical condition an application might log. This might be used
-if an error occurs which can not be handled except a safe shutdown for example.
+This is the most critical condition that might be registered by
+an application. Situations might arise when the application
+encounters such a serious error that can only be adequately treated
+by, for example, safely shutting down the application.
 
-[[CRITICAL]]
 .CRITICAL
+
  CRITICAL(flag, ...)
  CRITICAL_IF(when, flag, ...)
  NOBUG_CRITICAL_CTX(flag, context, ...)
@@ -979,88 +1128,94 @@ if an error occurs which can not be handled except a safe shutdown for example.
 An error which can not be handled occured but the application does not need to be
 shutdowen, perhaps waiting for an operator to fix the cause.
 
-[[ERROR]]
 .ERROR
+
  ERROR(flag, ...)
  ERROR_IF(when, flag, ...)
  NOBUG_ERROR_CTX(flag, context, ...)
  NOBUG_ERROR_IF_CTX(when, flag, context, ...)
 
-Application takes a error handling brach
+This is used when an application registers an error
+and appropriate action will have to be taken.
 
-[[WARN]]
 .WARN
+
  WARN(flag, ...)
  WARN_IF(when, flag, ...)
  NOBUG_WARN_CTX(flag, context, ...)
  NOBUG_WARN_IF_CTX(when, flag, context, ...)
 
-Rare, handled but unexpected branch
+When an application encounters a rare and unexpected
+situation, these macros can be used.
 
-[[INFO]]
 .INFO
+
  INFO(flag, ...)
  INFO_IF(when, flag, ...)
  NOBUG_INFO_CTX(flag, context, ...)
  NOBUG_INFO_IF_CTX(when, flag, context, ...)
 
-Message about program progress
+It may be benificial to output information at various
+locations throughout the code, e.g., messages on programm
+progress.
 
-[[NOTICE]]
 .NOTICE
+
  NOTICE(flag, ...)
  NOTICE_IF(when, flag, ...)
  NOBUG_NOTICE_CTX(flag, context, ...)
  NOBUG_NOTICE_IF_CTX(when, flag, context, ...)
 
-More detailed progress message
+Same as the INFO() macros, except more verbose.
 
-[[TRACE]]
 .TRACE
+
  TRACE(flag, ...)
  TRACE_IF(when, flag, ...)
  NOBUG_TRACE_CTX(flag, context, ...)
  NOBUG_TRACE_IF_CTX(when, flag, context, ...)
 
-Very fine grained messages
+The same as the NOTICE() macros, except very fine-grained information.
+a common use case is to put just `TRACE(debugflag)` just at the begin of every
+non-trivial function. This allows to watch fine grained application progress in the log.
 
-NOTE: that `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
+NOTE: `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
 
-[[LOG]]
 .LOG
+
  NOBUG_LOG_CTX(flag, lvl, context, ...)
  NOBUG_LOG_IF_CTX(when, flag, lvl, context, ...)
 
-Generic logging macro which takes the level explicitly,
-avoid this, unless you implement your own logging facilities.
+Generic logging macro which takes the level explicitly.
+Avoid this, unless you implement your own logging facilities.
+
+
+NOTE: there is no logging macro for `LOG_EMERG`, this is only used by the assertions as a fatal message
 
-[[LOG_BASELIMIT]]
 .LOG_BASELIMIT
+
  NOBUG_LOG_BASELIMIT_ALPHA
  NOBUG_LOG_BASELIMIT_BETA
  NOBUG_LOG_BASELIMIT_RELEASE
  NOBUG_LOG_BASELIMIT
 
-anything more detailed than this base limits will be optimized out.
+Anything more detailed than this base limits will be optimized out.
 This is used to reduce the logging overhead for *RELEASE* builds.
 By default the limit is set to `LOG_DEBUG` for *ALPHA* and *BETA*
 builds, so all logging is retained and `LOG_NOTICE` in *RELEASE*
-builds to log the application progress only coarsely then.
+builds to log the application progress only coarsely.
 
-This macros can be defined before including 'nobug.h' to some other
+These macros can be defined before including 'nobug.h' to some other
 log level (as defined in 'syslog.h').
 
-[[dumping]]
-Dumping Datastructures
-----------------------
-
-TODO How to write DUMP handlers
+Dumping Data Structures
+-----------------------
 
-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:
 
@@ -1069,37 +1224,43 @@ A dump function has the prototype:
 void
 nobug_NAME_dump (const struct NAME* POINTER,
                  const int DEPTH,
-                 const struct nobug_context CONTEXT,
+                 const struct nobug_context context,
                  void* EXTRA);
 -------------------------------------------------------
 
-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
-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.
-[[DUMP]]
+where 'NAME' is the identifier for what you want to dump, 'POINTER' is a pointer
+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
+that you can use to store some additional state. The 'context' variable must
+be named `context` because the `DUMP_LOG()` macro relies on this.
+
 .DUMP
+
  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.
+These macros call a data structure dump of the object (`pointer`) in question.
+`DUMP` has only effect in *ALPHA* and *BETA* builds, `DUMP_IF` is also
+enabled for RELEASE builds.
 
 `extra` is a void* which is transparently passed around and can be used to
-pass some state around. NoBug does not touch it.
+pass a particular state around. NoBug does not alter this.
 
-[[DUMP_LOG]]
 .DUMP_LOG
+
  DUMP_LOG(...)
  DUMP_LOG_IF(when, ...)
 
 Any output from `DUMP` handlers should be done by these macros.
 
-Dumping is by default done on level `LOG_DEBUG`, this can be overridden by
-defining `NOBUG_DUMP_LEVEL` to some other level.
+.DUMP_LEVEL
+
+ #define NOBUG_DUMP_LEVEL ...
+
+Dumping is by default done at `LOG_DEBUG` level, this can be overridden by
+defining `NOBUG_DUMP_LEVEL` to some other logging level.
 
 .How to use the DUMP facilities
 
@@ -1113,7 +1274,7 @@ struct STRUCTNAME
 }
 -------------------------------------------------------
 
-then you define a function like:
+Thereafter, define a funcion as follows:
 
 [source,c]
 -------------------------------------------------------
@@ -1123,26 +1284,30 @@ nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
                        const struct nobug_context context,
                        void* extra)
 {
-  // check for self != NULL and that the depth
-  // limit did not exceed in recursive datastructures
+  /* check for self != NULL and that the depth limit
+     was not exceeded in recursive data structures */
   if (self && depth)
   {
-    // you may or may not do something with the extra parameter here
-    // extra is transparently passed around
+    /* you may or may not do something with the extra
+       parameter here, extra is transparently
+       passed around */
     (void) extra;
 
-    // use DUMP_LOG not LOG to print the data
+    /* use DUMP_LOG not LOG to print the data */
     DUMP_LOG("STRUCTNAME %p: int is %d, string is %s", self,
                              self->INTEGER_MEMBER,
                              self->STRING_MEMBER);
 
-    // now recurse with decremented depth
-    nobug_STRUCTNAME_dump (self->next, depth-1, context, extra);
+    /* now recurse while decrementing depth */
+    nobug_STRUCTNAME_dump (self->next,
+                           depth-1,
+                           context,
+                           extra);
   }
 }
 -------------------------------------------------------
 
-now you can use the DUMP() macros within the code
+Now you can use the DUMP() macros within the code
 
 [source,c]
 -------------------------------------------------------
@@ -1151,206 +1316,238 @@ example()
   struct STRUCTNAME foo;
   init(&foo);
 
-  // extra can be anything, NULL is suggested when you don't use it
+  /* extra can be anything,
+     NULL is suggested when you don't use it */
   DUMP (my_flag, STRUCTNAME, &foo, 2, NULL);
 }
 -------------------------------------------------------
 
-Source Annotations
-------------------
+Source Code Annotations
+-----------------------
+
+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. NoBug
+provides macros to tag code with such annotations. This 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 dubious code due to runtime messages.
 
-One can tag features as:
 
-[[DEPRECATED]]
 .DEPRECATED
+
  DEPRECATED(...)
 
-Something which shouldn't be used in future
+Use this macro to identify code that is depreciated
+and should not be used in future or productive code.
 
-[[UNIMPLEMENTED]]
 .UNIMPLEMENTED
+
  UNIMPLEMENTED(...)
 
-not yet finished feature
+Use this macro to identify code that is functionally
+not yet complete and should not be used. This is convenient
+for code under development or being reviewed.
 
-[[FIXME]]
 .FIXME
+
  FIXME(...)
 
-known bug to be fixed later
+Use this macro to mark a known and unfixed bug.
 
-[[TODO]]
 .TODO
+
  TODO(...)
 
-enhancement to be done soon
+Enhancement or non-critical bug to be done soon.
 
-[[PLANNED]]
 .PLANNED
+
  PLANNED(...)
 
-future enhancement
+Future enhancement, optimization to similar which has no side effect on the current program.
 
-[[NOTREACHED]]
 .NOTREACHED
+
  NOTREACHED(...)
 
-used to tag code-path which shall be never executed.
+Code which must never be reached.
 
-[[ELSE_NOTREACHED]]
 .ELSE_NOTREACHED
+
  ELSE_NOTREACHED(...)
 
-same as `else NOTREACHED()`, but wholly optimized out in release builds.
+This macro is the same as `else NOTREACHED()`, but completely
+optimized out in release builds.
 
 
-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:
+Annotation Semantics
+~~~~~~~~~~~~~~~~~~~~
 
-the action to be taken when such a macro is hit depends on the build level:
+The action that should be taken when an annotated source line is reached
+depends on the build level.
 
-[grid="all"]
-`-------------`-----`------------`-----------------------------------------
-              ALPHA BETA         RELEASE
----------------------------------------------------------------------------
-DEPRECATED    log   nothing      wont compile
-UNIMPLEMENTED abort abort        wont compile
-FIXME         log   wont compile wont compile
-TODO          log   log          wont compile
-PLANNED       log   nothing      nothing
-NOTREACHED    abort abort        removed
----------------------------------------------------------------------------
+[frame="topbot",options="header"]
+|================================================
+|              |ALPHA |BETA         |RELEASE
+|DEPRECATED    |
+log footnote:[will only log once for each source line (not on each hit)] |
+nothing footnote:[optimized out, irrelevant] |
+won't compile footnote:[aborts compilation with an error message]
 
-Legend:
+|UNIMPLEMENTED |abort footnote:[spew a log message, then abort the program] |
+abort |won't compile
 
-  * 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
-  * nothing optimized out, sane way
-  * removed optimized out for performance reasons
+|FIXME         |log   |won't compile |won't compile
+|TODO          |log   |log          |won't compile
+|PLANNED       |log   |nothing      |nothing
+|NOTREACHED    |abort |abort        |removed footnote:[optmized out, size]
+|================================================
 
-[[CHECKED]]
 Scope Checks
 ------------
-[[UNCHECKED]]
 
 The programmer can tag any scope as `UNCHECKED` or `CHECKED`. In *ALPHA* and *BETA*
 builds, a global `UNCHECKED` is implied. In *RELEASE* builds, `UNCHECKED` scopes are
 not allowed.
 
+[source,C]
+-------
+int
+myfunc()
+{
+   /* the outer scope of this function is not validated yet*/
+   UNCHECKED;
+
+   if (...)
+   {
+      /* everything in this scope is considered ok */
+      CHECKED;
+      ...
+   }
+   return ...;
+}
+-------
+
 .Assertions active depending on Build level and Scope
-[grid="all"]
-`-----------`-----------------------------------------`-----------------------------`-------------------
-            *ALPHA*                                   *BETA*                        *RELEASE*
-*UNCHECKED* Preconditions, Postconditions, Invariants Preconditions, Postconditions compiling will abort
-*CHECKED*   Preconditions, Postconditions             Preconditions
-------------------------------------------------------------------------------------------------------
+
+[cols="2h,3*3",frame="topbot",options="header",autowidth="something"]
+|============================================================================================
+|          |ALPHA                                     |BETA                          |RELEASE
+|UNCHECKED |Preconditions, Postconditions, Invariants |Preconditions, Postconditions |compiling will abort
+|CHECKED   |Preconditions, Postconditions             |Preconditions                 |
+|============================================================================================
 
 Fault injection
 ---------------
 
-NoBug has some macros which can be used to simulate errorneous behaviour:
+NoBug has some macros which can be used to simulate erroneous behaviour,
+in other words, we can inject errors, or faults, into the code
+using NoBug.
 
-[[INJECT_GOODBAD]]
 .INJECT_GOODBAD
+
  INJECT_GOODBAD(expr, good, bad)
 
-substitutes to an expression and returns good when expr is false and
-bad when expr is true. In BETA and RELEASE builds 'good' is always returned.
+Substitutes to an expression and returns 'good' when expr is false and
+'bad' when expr is true. In BETA and RELEASE builds 'good' is always returned.
 
-[[INJECT_FAULT]]
 .INJECT_FAULT
+
  INJECT_FAULT(expr, bad)
 
-substitutes to a statement which executes 'bad'
-when expr is true. Optimitzed out in BETA and RELEASE builds.
+Substitutes to a statement which executes 'bad'
+when expr is true. This is only available in ALPHA builds and
+is optimitsed out in BETA and RELEASE builds.
 
-[[INJECT_LEVEL]]
-.INJECT_LEVEL
-In both cases, when a fault is injected it will be logged at
+.Setting the logging level for fault injections
+In both cases, when a fault is injected, it will be logged at
 `NOBUG_INJECT_LEVEL` (default: `LOG_NOTICE`). This can be defined
 before including 'nobug.h' to override it.
 
 Fault coverage checking
 -----------------------
 
-CAUTION: Fault coverage checking is a experimental feature!
+CAUTION: Fault coverage checking is an experimental feature!
 
-Nobug can automatically inject faults at instrumented points and permute
+NoBug can automatically inject faults at instrumented points and permute
 through all potential error paths of an application by restarting it with the
-state from the former run. It can be used to give answers to the question if
-any possible error is sufficiently handled in the application. Fault coverage
-checking is only available in ALPHA builds and optimized out otherwise.
+state from a former run. It can be used to provide information on whether a
+particular error is adequately treated in an application. Fault coverage
+checking is only available in ALPHA builds; it is optimized out in all other
+builds.
 
-NOTE: This kind of testing is very expensive.
+NOTE: This kind of testing is very expensive on performance.
 
-How does automatic fault injection work
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How Does Automatic Fault Injection Work?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-First NoBug checks if the environment variable `NOBUG_COVERAGE` is set, if yes
-it must contain a space, comma or semicolon separated list of filename which
-are the logs from the previous run. This logs are then parsed for the states
-of the previous run, storing these in a lookup tree.
+First, NoBug checks if the `NOBUG_COVERAGE` environment variable is set. If it
+is set, it must contain a space, comma or a semicolon separated list of
+filenames which are the logs from a previous run. These logs are then parsed
+storing the old state in a lookup tree.
 
-After that the application proceeds as usual, when it then hits an
-instrumented coverage point it is checked against the already recorded states.
-Any so far unseen failure point injects a fault, the last seen but previously
-failed point will be pass now, all other fault injection points act like on
-their previous run. This ensures that each successive run of the application
-changes only one injection point and thus permutes through all possible code
-paths.
+The application will then proceed to run as usual. When an instrumented
+coverage point is hit, its status is checked against all states that have been
+recorded previously. Any failure point that is encountered for a first time
+causes a fault to be injected; the last seen but previously failed point will
+now be passed, all other fault injection points behave as in their previous
+run. This ensures that each successive run of the application changes only one
+injection point and, thus, permutes through all possible code paths.
 
 Fault injection points are identified by a 64bit hash over the backtrace
 (return addresses on the stack) leading to it. This means each unique way to
-reach a injection point is recorded. Parameters and threads are intentionally
+reach an injection point is recorded. Parameters and threads are intentionally
 not considered in this calculation.
 
 
-How to invoke fault-coverage checking
+How to Invoke Fault-Coverage Checking
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Each fault-injection point emits a logging message about its identity and
-state, this logging uses the normal NoBug logging facilities. Thus one can
-control the logging with the `NOBUG_LOG` environment variable. Additionally
-fault coverage checking is only active when the `NOBUG_COVERAGE` environment
-variable was set to point some log files which are the results from the
+state, this logging uses the normal NoBug logging facilities. Thus, one can
+control logging with the `NOBUG_LOG` environment variable. Furthermore, fault
+coverage checking is only active when the `NOBUG_COVERAGE` environment
+variable has been set to point to log files which are the results from a
 previous run. NoBug comes with a `tests/coverage.sh` example script which
 permutes through all possible error paths.
 
 Coverage checking Macros
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-[[COVERAGE_FAULT]]
 .COVERAGE_FAULT
+
  COVERAGE_FAULT(flag, ...)
 
-Injects the statement at `...` when simulating an failure. Only active in
+Injects the statement at `...` when simulating a failure. Only active in
 ALPHA builds.
 
-[[COVERAGE_GOODBAD]]
 .COVERAGE_GOODBAD
+
  COVERAGE_GOODBAD(flag, good, bad)
 
-Substitutes to an expression and injects `bad` when simulating an failure and `good`
+Substitutes to an expression and injects `bad` when simulating a failure and `good`
 otherwise. Only active in ALPHA builds.
 
-[[COVERAGE_LEVEL]]
 .COVERAGE_LEVEL
+
  #define NOBUG_COVERAGE_LEVEL ...
 
-Logging level at what fault-coverage logging is emitted.
+Define the logging level in which fault-coverage logging is emitted.
 
 NOTE: Supressing log output with this level will not supress fault injection,
-      actually the opposite is true since every new seen failure path gets injected.
+      actually the opposite is true since every newly seen failure path gets injected.
       This might be changed in future releases.
 
-[[COVERAGE_DISABLE]]
 .Disabling and enabling fault-coverage checks
+
  NOBUG_COVERAGE_DISABLE
  NOBUG_COVERAGE_ENABLE
 
 Sometimes fault injection yields false positives, errors which may never happen in real life
-(and are possibly enforced with a ENSURE afterwards). For this cases coverage fault injection can be
+(and are possibly enforced with an ENSURE afterwards). For this cases coverage fault injection can be
 disabled temporarly and reenabled later. Disabling/enabling may nest and must properly match.
 
 Resource Tracking
@@ -1367,38 +1564,36 @@ ALPHA builds.
 Concepts
 ~~~~~~~~
 
-Resources are abstracted, NoBug has little knowledge about the semantics of a
-resource, it only keeps records of resources and the code using it and ensures
-basic constraints. Detailed usage checks of resource have to be done with other
-NoBug facilities.
+Resources are an abstract entity for NoBug, which has little knowledge about the
+kinds of resources; it only keeps records of resources and the code using
+these resources and ensures basic constraints. More detailed checks on resource
+usage have to be done with other NoBug facilities.
 
-Resources are identified by a arbitrary identifier which is just a
+Resources are identified by an arbitrary identifier which is just a
 pointer. Additionally a name, the type and the source locations which
-announced the resource are stored.
+registered the resource are stored.
 
-Code which wants to use a resource calls a enter macro with its own identifier
-and state, then might alter the state and finally a leave macro when finished
-with it.
+Code which requiring to use a resource, calls an 'ENTER' macro, supplying
+an identifier and state. The state can be altered. Thereafter a 'LEAVE' macro is
+used when the the code is finished with the resources.
 
-When a resource is used one has to pass one of this states:
+When a resource is used, one has to pass one of these states:
 
-  * NOBUG_RESOURCE_WAITING
-      + For resources where acquisition could block (locks) you enter it with a
-        WAITING state first and as soon you acquired it you change the state to one
-        of the following.
-  * NOBUG_RESOURCE_EXCLUSIVE
-      + Acquired the resource exclusively. It must not be acquired
+  `NOBUG_RESOURCE_WAITING`::
+        For resources which might need to be blocked (locks),  enter with a
+        WAITING state first, as soon at the resource is acquired, change the
+        state to one of the following.
+  `NOBUG_RESOURCE_EXCLUSIVE`::
+        Acquired the resource exclusively. The resource must not be acquired
         again, not even from the same thread.
-  * NOBUG_RESOURCE_RECURSIVE
-      + The resource might be entered multiple times from the same
+  `NOBUG_RESOURCE_RECURSIVE`::
+        The resource might be entered multiple times from the same
         thread with this state.
-  * NOBUG_RESOURCE_SHARED
-      + The resource might be entered multiple times from any thread
+  `NOBUG_RESOURCE_SHARED`::
+        The resource might be entered multiple times from any thread
         with this state.
 
-Possible state transitions:
-
-["graphviz", "resource-transistinons.png"]
+["graphviz", "resource-transitions.eps"]
 ---------------------------------------------------------------------
 strict digraph G
 {
@@ -1428,26 +1623,19 @@ strict digraph G
 Notes
 ~~~~~
 
-There are small race conditions between logging and checking resource tracking
-and the actual call to the resource using function. This is a design decision
-there is no way to account for this exactly when the function call may block.
-
 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.
+are properly paired. The programmer should ensure that this is correctly 
+done, otherwise the results are unpredictable.
 
 Resource tracking macros
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-[[RESOURCE_LOGGING]]
-[[RESOURCE_LOG_LEVEL]]
-
 Unless the user defines `NOBUG_RESOURCE_LOGGING` to 0 each of the above macros
 will emit a log message at `NOBUG_RESOURCE_LOG_LEVEL` which defaults to
 `LOG_DEBUG`.
 
-[[RESOURCE_HANDLE]]
 .RESOURCE_HANDLE
+
  RESOURCE_HANDLE(name)
  RESOURCE_HANDLE_INIT(name)
  RESOURCE_USER(name)
@@ -1458,20 +1646,21 @@ Define and initialize handles for to track resources.
  `name`::
      identifer to be used for the handle
 
-There are two kinds of handles, each resource itself is abstracted with a
-`RESOURCE_HANDLE` and every access to this resources is tracked through a
-`RESOURCE_USER` handle. These macros takes care that the declaration is optimized
-out in the same manner as the rest of the resource tracker would be disabled.
+There are two kinds of handles. Resource themself are abstracted with a
+`RESOURCE_HANDLE` while uses of a resources are tracked by `RESOURCE_USER`
+handle. These macros takes care that the declaration is optimized out
+in the same manner as the rest of the resource tracker would be disabled.
 You can still instantiate handles as `struct nobug_resource_record*` or
 `struct nobug_resource_user*` in structures which must have a constant size
 unconditional of the build level. The two `*_INIT` macros can be used to initialize
 resource handles and are optimized out when the resource tracker gets disabled.
 
-[[RESOURCE_ANNOUNCE]]
 .RESOURCE_ANNOUNCE
- RESOURCE_ANNOUNCE(flag, type, name, identifier, handle)
- NOBUG_RESOURCE_ANNOUNCE_RAW(flagptr, type, name, ptr, handle)
- NOBUG_RESOURCE_ANNOUNCE_RAW_CTX(flagptr, type, name, ptr, handle, context)
+
+ RESOURCE_ANNOUNCE(flag, type, name, identifier, handle){}
+ NOBUG_RESOURCE_ANNOUNCE_RAW(flagptr, type, name, ptr, handle){}
+ NOBUG_RESOURCE_ANNOUNCE_RAW_CTX(flagptr, type, name,
+                                 ptr, handle, context){}
 
 Publishes resources.
 
@@ -1481,12 +1670,11 @@ Publishes resources.
      a string which should denote the domain of the resource,
      examples are "file", "mutex", "lock", "database" and so on
  `name`::
-     the actual name of a named resource this as string which
-     together with type forms a unique identifier of the resource. `type` and
+     the actual name of a named resource this as string. `type` and
      `name` must be available through the entire lifetime of the resource, using
      literal strings is recommended
  `identifier`::
-     a pointer which should be unique for this resource, any
+     a pointer which must be unique for this resource, any
      kind of pointer will suffice, it is only used for identification. In
      multithreaded applications the thread identifier becomes an additional
      identifier
@@ -1497,15 +1685,15 @@ Publishes resources.
 Resources must be unique, it is a fatal error when a resource it tried to be
 announced more than one time.
 
-'RESOURCE_ANNOUNCE()' acts like the head of a C loop statement, it ties to the following
-(block-) statement. Leaving and the user defined following statement are atomic.
+`RESOURCE_ANNOUNCE()` acts like the head of a C loop statement, it ties to the following
+(block-) statement which will be handled atomic.
 This statement must not be left by break, return or any other kind of jump.
 
-[[RESOURCE_FORGET]]
 .RESOURCE_FORGET
- RESOURCE_FORGET(flag, handle)
- NOBUG_RESOURCE_FORGET_RAW(flagptr, handle)
- NOBUG_RESOURCE_FORGET_RAW_CTX(flagptr, handle, context)
+
+ RESOURCE_FORGET(flag, handle){}
+ NOBUG_RESOURCE_FORGET_RAW(flagptr, handle){}
+ NOBUG_RESOURCE_FORGET_RAW_CTX(flagptr, handle, context){}
 
 Removes resources that have become unavailable from the registry.
 
@@ -1517,12 +1705,12 @@ Removes resources that have become unavailable from the registry.
 The resource must still exist and no users must be attached to it, else a fatal
 error is raised.
 
-'RESOURCE_FORGET()' acts like the head of a C loop statement, it ties to the following
-(block-) statement. Leaving and the user defined following statement are atomic.
+`RESOURCE_FORGET()` acts like the head of a C loop statement, it ties to the following
+(block-) statement which will be handled atomic.
 This statement must not be left by break, return or any other kind of jump.
 
-[[RESOURCE_RESETALL]]
 .RESOURCE_RESETALL
+
  RESOURCE_RESETALL(flag)
  NOBUG_RESOURCE_RESETALL_RAW(flagptr)
  NOBUG_RESOURCE_RESETALL_RAW_CTX(flagptr, context)
@@ -1535,11 +1723,11 @@ to reset all whats learnt about all resources and start over.
 `flag`::
     the NoBug flag which turns logging on for this macro
 
-[[RESOURCE_RESET]]
 .RESOURCE_RESET
+
  RESOURCE_RESET(flag, handle)
- NOBUG_RESOURCE_RESETALL_RAW(flagptr, handle)
- NOBUG_RESOURCE_RESETALL_RAW_CTX(flagptr, handle, context)
+ NOBUG_RESOURCE_RESET_RAW(flagptr, handle)
+ NOBUG_RESOURCE_RESET_RAW_CTX(flagptr, handle, context)
 
 Sometimes the resource tracker can give false positives when it finds a locking order violation
 while the programmer knows that this will never happen in the real program, because for example
@@ -1551,10 +1739,11 @@ to reset all whats learnt about a single resources and start over.
 `handle`::
     the `NOBUG_RESOURCE_HANDLE` used to track this resource
 
-[[RESOURCE_ENTER]]
 .RESOURCE_ENTER
- RESOURCE_ENTER(flag, announced, user, state, handle)
- NOBUG_RESOURCE_ENTER_CTX(flag, resource, user, state, handle, context)
+
+ RESOURCE_ENTER(flag, announced, user, state, handle){}
+ NOBUG_RESOURCE_ENTER_CTX(flag, resource, user, state,
+                          handle, context){}
 
 Acquire a resource.
 
@@ -1563,24 +1752,26 @@ Acquire a resource.
 `announced`::
     the handle set by `RESOURCE_ANNOUNCE`
 `user`::
-    a free-form identifier
+    a literal string defining the purpose
 `state`::
-    the initial state, one of `NOBUG_RESOURCE_WAITING`, `NOBUG_RESOURCE_TRYING`,
-    `NOBUG_RESOURCE_EXCLUSIVE`, `NOBUG_RESOURCE_RECURSIVE` or `NOBUG_RESOURCE_SHARED`
+    the state to enter
 `handle`::
     a `NOBUG_RESOURCE_HANDLE` which will be initialized to the
     entering node
 
-'RESOURCE_ENTER()' acts like the head of a C loop statement, it ties to the following
-(block-) statement. Leaving and the user defined following statement are atomic.
+`RESOURCE_ENTER()` acts like the head of a C loop statement, it ties to the following
+(block-) statement which will be handled atomic.
 This statement must not be left by break, return or any other kind of jump.
 
-[[RESOURCE_WAIT]]
 .RESOURCE_WAIT
- RESOURCE_WAIT(flag, resource, user, handle)
- NOBUG_RESOURCE_WAIT_CTX(flag, resource, user, handle, context)
 
-This is just an alias for RESOURCE_ENTER(flag, resource, user, NOBUG_RESOURCE_WAITING, handle)
+ RESOURCE_WAIT(flag, resource, user, handle){}
+ NOBUG_RESOURCE_WAIT_CTX(flag, resource, user, handle, context){}
+
+This is just an alias for
+
+ RESOURCE_ENTER(flag, resource, user,
+                NOBUG_RESOURCE_WAITING, handle)
 
 .How to use it
 [source,c]
@@ -1592,21 +1783,25 @@ else
   RESOURCE_STATE(flag, NOBUG_RESOURCE_EXCLUSIVE, handle);
 ----
 
-[[RESOURCE_TRY]]
 .RESOURCE_TRY
- RESOURCE_TRY(flag, resource, user, handle)
- NOBUG_RESOURCE_TRY_CTX(flag, resource, user, handle, context)
 
-This is just an alias for RESOURCE_ENTER(flag, resource, user, NOBUG_RESOURCE_TRYING, handle).
+ RESOURCE_TRY(flag, resource, user, handle){}
+ NOBUG_RESOURCE_TRY_CTX(flag, resource, user, handle, context){}
+
+This is just an alias for
+
+ RESOURCE_ENTER(flag, resource, user,
+                NOBUG_RESOURCE_TRYING, handle)
+
 Trying on a resource is similar to waiting but will not trigger a deadlock check. This can be used
 when a deadlock is expected at runtime and one handles this otherwise (by a timed wait or something like that).
 
-[[RESOURCE_STATE]]
 .RESOURCE_STATE
- RESOURCE_STATE(flag, entered, state)
- NOBUG_RESOURCE_STATE_CTX(flag, state, entered, context)
- NOBUG_RESOURCE_STATE_RAW(flagptr, state, entered)
- NOBUG_RESOURCE_STATE_RAW_CTX(flagptr, nstate, entered, context)
+
+ RESOURCE_STATE(flag, entered, state){}
+ NOBUG_RESOURCE_STATE_CTX(flag, state, entered, context){}
+ NOBUG_RESOURCE_STATE_RAW(flagptr, state, entered){}
+ NOBUG_RESOURCE_STATE_RAW_CTX(flagptr, state, entered, context){}
 
 Changes resource's state.
 
@@ -1618,12 +1813,12 @@ Changes resource's state.
 `entered`::
     the handle set by `RESOURCE_ENTER`
 
-'RESOURCE_STATE()' acts like the head of a C loop statement, it ties to the following
-(block-) statement. Leaving and the user defined following statement are atomic.
+`RESOURCE_STATE()` acts like the head of a C loop statement, it ties to the following
+(block-) statement which will be handled atomic.
 This statement must not be left by break, return or any other kind of jump.
 
-[[RESOURCE_LEAVE]]
 .RESOURCE_LEAVE
+
  RESOURCE_LEAVE(flag, handle){}
  NOBUG_RESOURCE_LEAVE_RAW(flagptr, handle){}
  NOBUG_RESOURCE_LEAVE_RAW_CTX(flagptr, handle, context){}
@@ -1635,8 +1830,8 @@ Disconnect from a resource identified with its handle.
 `handle`::
     the handle you got while entering the resource
 
-'RESOURCE_LEAVE()' acts like the head of a C loop statement, it ties to the following
-(block-) statement. Leaving and the user defined following statement are atomic.
+`RESOURCE_LEAVE()` acts like the head of a C loop statement, it ties to the following
+(block-) statement which will be handled atomic.
 This statement must not be left by break, return or any other kind of jump.
 
 .How to use it
@@ -1648,12 +1843,13 @@ NOBUG_RESOURCE_LEAVE(flag, handle)
   }
 ----
 
-[[RESOURCE_ASSERT_STATE]]
 .RESOURCE_ASSERT_STATE
+
  RESOURCE_ASSERT_STATE(resource, state)
  RESOURCE_ASSERT_STATE_IF(when, resource, state)
  NOBUG_RESOURCE_ASSERT_STATE_CTX(resource, state, context)
- NOBUG_RESOURCE_ASSERT_STATE_IF_CTX(when, resource, state, context)
+ NOBUG_RESOURCE_ASSERT_STATE_IF_CTX(when, resource,
+                                    state, context)
 
 Assert that we have a resource in a given state. For multithreaded programms the topmost
 state of the calling thread is checked, for non threadeded programs the most recent state on
@@ -1666,8 +1862,8 @@ resource is used.
 `state`::
     The expected state
 
-[[RESOURCE_DUMP]]
 .RESOURCE_DUMP
+
  NOBUG_RESOURCE_DUMP(flag, handle)
  NOBUG_RESOURCE_DUMP_IF(when, flag, handle)
 
@@ -1680,8 +1876,8 @@ Dump the state of a single resource.
 `handle`::
     handle of the resource to be dumped
 
-[[RESOURCE_DUMPALL]]
 .RESOURCE_DUMPALL
+
  NOBUG_RESOURCE_DUMPALL(flag)
  NOBUG_RESOURCE_DUMPALL_IF(when, flag)
 
@@ -1692,8 +1888,8 @@ Dump the state of all resources.
 `flag`::
     Nobug flag for the log channel
 
-[[RESOURCE_LIST]]
 .RESOURCE_LIST
+
  NOBUG_RESOURCE_LIST(flag)
  NOBUG_RESOURCE_LIST_IF(when, flag)
 
@@ -1711,37 +1907,44 @@ NOBUG_DEFINE_FLAG_LIMIT(test, LOG_DEBUG);
 
 void example()
 {
-  // define a mutex and announce it
+  /* define a mutex and announce it */
   pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
   RESOURCE_HANDLE(resource);
 
-  // 'example' is just a pointer to this function which suffices as unique id
-  RESOURCE_ANNOUNCE(test, "mutex", "my_mutex", example, resource);
+  /* 'example' is just a pointer to this function
+     which suffices as unique identifier */
+  RESOURCE_ANNOUNCE(test, "mutex", "my_mutex",
+                    example, resource);
 
-  // the following would be done in a different thread in a real program
-  // define a handle
+  /* the following would be done in a
+     different thread in a real program */
+
+  /* define a handle */
   RESOURCE_HANDLE(enter);
 
-  // announce that we want to use the resource
-  // &enter also suffices as unique pointer, which is all we need as identifer here
+  /* announce that we want to use the resource
+     &enter also suffices as unique pointer,
+     which is all we need as identifer here */
   RESOURCE_WAIT(flag, resource, &enter, enter)
     {
-      // lock() might block
+      /* lock() might block */
       pthread_mutex_lock (&my_mutex);
-      // assume no errors, got it, change the state
+      /* assume no errors, got it, change the state */
       RESOURCE_STATE(test, NOBUG_RESOURCE_EXCLUSIVE, enter);
     }
 
-  ////////////////////////////////////////
-  // program does something useful here //
-  ////////////////////////////////////////
+  /***************************************
+  ** program does something useful here **
+  ***************************************/
 
-  // we don't need it anymore
-  RESOURCE_LEAVE(test, enter)  // << no semicolon
+  /* we don't need it anymore */
+  RESOURCE_LEAVE(test, enter)  /* << no semicolon! */
     pthread_mutex_unlock (&my_mutex);
 
-  // back in the main thread
-  RESOURCE_FORGET(test, resource);                         // remove the resource from the public registry
+  /* back in the main thread */
+
+  /* remove the resource from the public registry */
+  RESOURCE_FORGET(test, resource);
 }
 ----
 
@@ -1749,30 +1952,33 @@ Deadlock Detection
 ~~~~~~~~~~~~~~~~~~
 
 The Resource Tracker is able to detect potential deadlocks. This is done by
-learning the relations between locks (precedence). A possible deadlock results
-in a log message and a fatal abort. Note that only waiting on resources can
-lead to a deadlock. Deadlock detection is implemented in the Resource Tracker
-and active in ALPHA builds and optimized out on any other build level.
+learning the relations between locks (precedence) and watching the order in
+which resources are acquired. It has some heuristics to detect certain
+patterns which are deadlock free. A possible deadlock results in a log message
+and a fatal abort. Note that only waiting on resources can lead to a deadlock.
+Deadlock detection is implemented in the Resource Tracker 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].
+xref:deadlockdetection[Appendix: Resource Tracking Alorithm].
 
 Callbacks
 ---------
 
 NoBug provides callbacks, applications can use these
 to present logging information in some custom way or hook some special processing in.
-The callbacks are initialized to NULL and never modified by NoBug, its the solve responsibility
+The callbacks are initialized to NULL and never modified by NoBug, it is the sole responsibility
 of the user to manage them.
 
 CAUTION: There are certain constraints what and what not can be done in callbacks
          documented below which must be followed.
 
-[[logging_cb]]
-.type of logging callbacks
- typedef void (*nobug_logging_cb)(const struct nobug_flag* flag, int priority, const char *log, void* data)
+.logging callback prototype
 
-used for the logging callbacks
+ typedef void (*nobug_logging_cb)(const struct nobug_flag* flag,
+                                  int priority,
+                                  const char *log,
+                                  void* data)
 
  `flag`::
     Flag structure which defines the logging configuration for this event
@@ -1783,24 +1989,22 @@ used for the logging callbacks
  `data`::
     Global pointer defined by the user, passed arround (see below)
 
-[[abort_cb]]
-.type of abort callback
- typedef void (*nobug_abort_cb)(void* data)
+.abort callback prototype
 
-used for the abort callback
+ typedef void (*nobug_abort_cb)(void* data)
 
  `data`::
     Global data defined by the user, passed arround (see below)
 
-[[callback_data]]
 .passing data to callbacks
+
  void* nobug_callback_data
 
 This global variable is initialized to `NULL` and will never be touched by NoBug. One can use it
 to pass extra data to the callback functions.
 
-[[logging_callback]]
 .callback when logging
+
  nobug_logging_cb nobug_logging_callback
 
 This callback gets called when something gets logged.
@@ -1812,22 +2016,22 @@ in the flag but called unconditionally. The callback should implement its own li
 
 When one wants to do complex calls which may include recursion into logging and resource tracking
 functions, the intended way is to pass contextual information possibly including a __copy__ of the
-`log` parameter in xref:THREAD_DATA[NOBUG_THREAD_DATA] to the postlogging callback (see below).
+`log` parameter in xref:THREADDATA[NOBUG_THREAD_DATA] to the postlogging callback (see below).
 Other internal NoBug facilties, like the ringbuffer etc, are protected by the mutexes and may be accessed
 from this function.
 
-[[postlogging_callback]]
 .callback after logging
+
  nobug_logging_cb nobug_postlogging_callback
 
 This callback gets called after something got logged. The `log` parameter is always NULL and all
 NoBug mutexes are released. This means that this function may call any complex things, including
 calling logging and resource tracking, but may not call internal NoBug facilities.
-Contextual created in the `nobug_logging_callback` and stored in xref:THREAD_DATA[NOBUG_THREAD_DATA] can be
+Contextual created in the `nobug_logging_callback` and stored in xref:THREADDATA[NOBUG_THREAD_DATA] can be
 retrieved here and may need to be cleaned up here.
 
-[[abort_callback]]
 .callback for aborting
+
  nobug_abort_cb nobug_abort_callback
 
 This callback gets called when the application shall be terminated due an error.
@@ -1841,8 +2045,8 @@ IMPORTANT: Errors detected by NoBug are always fatal. If one handles and possibl
 Tool Macros
 -----------
 
-[[NOBUG_FLAG_RAW]]
 .NOBUG_FLAG_RAW
+
  NOBUG_FLAG_RAW(ptr)
 
 Using this macro one can pass a direct pointer to a flag where a name would
@@ -1857,8 +2061,8 @@ struct nobug_flag* ptr = &NOBUG_FLAG(myflag);
 TRACE(NOBUG_FLAG_RAW(ptr), "Passed flag by pointer")
 ----
 
-[[BACKTRACE]]
 .Backtraces
+
  BACKTRACE
  NOBUG_BACKTRACE_CTX(context)
 
@@ -1866,8 +2070,8 @@ The backtrace macro logs a stacktrace using the NoBug facilities.
 This is automatically called when NoBug finds an error and is due
 to abort. But one might call it manually too.
 
-[[ABORT]]
 .Aborting
+
  NOBUG_ABORT_
 
 This is the default implementation for aborting the program, it first syncs all ringbuffers to disk, then
@@ -1878,18 +2082,38 @@ calls the abort callback if defined and then `abort()`.
 If not overridden, evaluates to `NOBUG_ABORT_`. One can override this before including
 `nobug.h` to customize abortion behaviour. This will be local to the translation unit then.
 
-[[NOBUG_ALPHA_COMMA]]
 .NOBUG_ALPHA_COMMA
+
  NOBUG_ALPHA_COMMA(something)
  NOBUG_ALPHA_COMMA_NULL
 
 Sometimes it is useful to have initializer code only in *ALPHA* builds, for example when you
 conditionally include resource handles only in *ALPHA* versions. An initializer can then
-use this macros to append a comman and something else only in *ALPHA* builds as in:
- struct foo = {"foo", "bar" NOBUG_ALPHA_COMMA_NULL };
+use this macros to append a comma and something else only in *ALPHA* builds as in:
+
+[source,C]
+----
+struct foo = {"foo", "bar" NOBUG_ALPHA_COMMA_NULL };
+----
+
+Becomes the following in *ALPHA* builds
+
+[source,C]
+----
+struct foo = {"foo", "bar", NULL};
+----
+
+and
+
+[source,C]
+----
+struct foo = {"foo", "bar"};
+----
+
+in *BETA* and *RELEASE* builds.
 
-[[NOBUG_IF]]
 .NOBUG_IF_*
+
  NOBUG_IF_ALPHA(...)
  NOBUG_IF_NOT_ALPHA(...)
  NOBUG_IF_BETA(...)
@@ -1901,7 +2125,6 @@ This macros allow one to conditionally include the code in '(...)' only if the
 criteria on the build level is met. If not, nothing gets substituted. Mostly used
 internally, but can also be used for custom things.
 
-[[multithreading]]
 Multithreading
 --------------
 
@@ -1915,8 +2138,8 @@ programs.
 When Multithreading is used, log messages contain a identifier of the
 originating thread. This identifier should be set by
 
-[[THREAD_ID_SET]]
 .NOBUG_THREAD_ID_SET
+
  NOBUG_THREAD_ID_SET(name)
 
 `name`::
@@ -1924,23 +2147,23 @@ originating thread. This identifier should be set by
 
 Nobug will assemble a unique identifier by appending a underscore and a
 number to name, for example `NOBUG_THREAD_ID_SET("gui")` will result in a
-identifier like "gui_5". When you don't set a thread identifier, then NoBug
+identifier like 'gui_5'. When you don't set a thread identifier, then NoBug
 assigns one automatically with the name 'thread' preprended if needed. Thread
 identifiers may be reset with a new call to this macro.
 
-[[THREAD_ID_GET]]
 .NOBUG_THREAD_ID_GET
+
  NOBUG_THREAD_ID_GET
 
 Will return a const char* of the thread id in multithreaded programs and
 a pointer to a literal empty string in singlethreaded programs.
 
-[[THREAD_DATA]]
 .NOBUG_THREAD_DATA
+
  NOBUG_THREAD_DATA
 
 Evaluates to a variable of type `void*` which can be used to store
-thread local information. This is useable for xref:_callbacks[callbacks] which may
+thread local information. This is useable for xref:callbacks[callbacks] which may
 prepare context information to be reused later.
 
 This macro is also available in singlethreaded programs, refering to a
@@ -1948,7 +2171,6 @@ single global variable.
 
 Nobug initializes this variable to `NULL` and then touches it never again.
 
-[[rbdump]]
 Dumping Persistent Ringbuffers
 ------------------------------
 
@@ -1956,13 +2178,11 @@ NoBug installs the `nobug_rbdump` tool for dumping the content of a persistent
 ringbuffer. It is invoked with the filename of the ringbuffer, the content is then
 printed to stdout.
 
-Testsuite
----------
-
- TODO Documentation to be written, use the source Luke!
-
-NoBug maintains a `test.sh` script which drives extensive testsuites.
-Look at into the 'tests/' folder about how to apply this.
+ $ NOBUG_LOG='test:TRACE@ringbuffer(file=test.rb)(keep)' ./a.out
+ 0000000004: TRACE: example.c:11: -: main: Always on
+ $ nobug_rbdump test.rb
+ 0000000003: TRACE: example.c:10: -: main: Logging
+ 0000000003! TRACE: example.c:10: -: main:  enabled
 
 Best Practices
 --------------
@@ -1973,7 +2193,7 @@ NOTE: this section is very work in progress
 
  1. Development
       * Write a testsuite, build your program with -O0 -g -DEBUG_ALPHA and run
-        the testsuite under valgrind control. Hack until the program mets the
+        the testsuite under valgrind control. Hack until the program meets the
         specifications defined by the testsuite.
  2. Beta Test
       * Build with desired optimization level and -g -DEBUG_BETA and give the
@@ -1984,7 +2204,7 @@ NOTE: this section is very work in progress
 .What and when to check
 
   * Add REQUIRE checks on your interfaces (incoming parameters). Especially if
-    a argument might not cover the whole range of the underlying type.
+    an argument might not cover the whole range of the underlying type.
   * Don't waste your and your CPU's time with unnecessary checks. The testsuite
     should validate your program. NoBug aids in debugging. You can add
     Postconditions (ENSURE) and Invariants when you have a bug somewhere and
@@ -2003,24 +2223,22 @@ NOTE: this section is very work in progress
 Appendix
 --------
 
-[[deadlock_detection]]
 The Resource Tracking Algorithm
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Each resource registers a global 'resource_record'.
 
 Every new locking path discovered is stored as 'resource_node' structures which refer to the associated
 'resource_record'.
 
-Threads keep a trail of 'resource_user' strcutures for each resource entered. This 'resource_user' struct
+Threads keep a trail of 'resource_user' structures for each resource entered. This 'resource_user' struct
 refer to the 'resource_nodes' and thus indirectly to the associated 'resource_record'.
 
 The deadlock checker uses this information to test if the acqusition of a new resource would yield a
 potential deadlock.
 
-[[nobug_resource_enter]]
 Entering Resources
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 In multithreaded programs, whenever a thread wants to wait for a 'resource_record'
 the deadlock checker jumps in.
@@ -2053,29 +2271,29 @@ the topmost node of the current threads user stack.
 
 [source,c]
 ---------------------------------------------------------------------
-  struct nobug_resource_user* user = NULL;
-  struct nobug_resource_node* node = NULL;
+struct nobug_resource_user* user = NULL;
+struct nobug_resource_node* node = NULL;
 
-  if (!llist_is_empty (&tls->res_stack))
   {
-      user = LLIST_TO_STRUCTP (llist_tail (&tls->res_stack),
-                               struct nobug_resource_user,
-                               res_stack);
-
-      struct nobug_resource_node templ =
-        {
-         ...
-          user->current->resource,
-         ...
-        };
-
-      node = (struct nobug_resource_node*)
-        llist_ufind (&resource->nodes,
-                     &templ.node,
-                     nobug_resource_node_resource_cmpfn,
-                     NULL);
   }
-  ...
+if (!llist_is_empty (&tls->res_stack))
+ {
+  user = LLIST_TO_STRUCTP (llist_tail (&tls->res_stack),
+                           struct nobug_resource_user,
+                           res_stack);
+
+  struct nobug_resource_node templ =
+   {
+    ...
+    user->current->resource,
+    ...
+   };
+
+  node = (struct nobug_resource_node*)
+   llist_ufind (&resource->nodes,
+                &templ.node,
+                nobug_resource_node_resource_cmpfn,
+                NULL);
+ }
+...
 ---------------------------------------------------------------------
 
 Deadlock checking is only done when the node is entered in `WAITING` state and only
@@ -2083,10 +2301,10 @@ available in multithreaded programs.
 
 [source,c]
 ---------------------------------------------------------------------
-  if (state == NOBUG_RESOURCE_WAITING)
   {
+if (state == NOBUG_RESOURCE_WAITING)
+ {
 #if NOBUG_USE_PTHREAD
-      ...
+  ...
 ---------------------------------------------------------------------
 
 If node was found above, then this locking path is already validated and no deadlock can happen,
@@ -2094,9 +2312,9 @@ else, if this stack already holds a resource (user is set) we have to go on with
 
 [source,c]
 ---------------------------------------------------------------------
-      if (!node && user)
       {
-          ...
+if (!node && user)
+ {
+  ...
 ---------------------------------------------------------------------
 
 If not then its checked that the resource to be entered is not on any parent trail of the current topmost resource,
@@ -2104,16 +2322,16 @@ if it is then this could be a deadlock which needs to be further investigated.
 
 [source,c]
 ---------------------------------------------------------------------
-          LLIST_FOREACH (&user->current->resource->nodes, n)
           {
-              for (struct nobug_resource_node* itr =
-                     ((struct nobug_resource_node*)n)->parent;
-                   itr;
-                   itr = itr->parent)
-                {
-                  if (itr->resource == resource)
-                    {
-                      ...
+LLIST_FOREACH (&user->current->resource->nodes, n)
+ {
+  for (struct nobug_resource_node* itr =
+         ((struct nobug_resource_node*)n)->parent;
+       itr;
+       itr = itr->parent)
+   {
+    if (itr->resource == resource)
+     {
+       ...
 ---------------------------------------------------------------------
 
 if the resource was on the trail, we search if there is a common ancestor before the resource
@@ -2122,48 +2340,48 @@ if yes then this ancestor protects against deadlocks and we can continue.
 
 [source,c]
 ---------------------------------------------------------------------
-                      for (struct nobug_resource_node* itr2 = itr->parent;
-                           itr2;
-                           itr2 = itr2->parent)
-                        {
-                          LLIST_FOREACH_REV (&tls->res_stack, p)
-                            {
-                              struct nobug_resource_user* user =
-                                LLIST_TO_STRUCTP (p,
-                                                  struct nobug_resource_user,
-                                                  res_stack);
-                              if (user->current->resource == itr2->resource)
-                                goto done;
-                            }
+for (struct nobug_resource_node* itr2 = itr->parent;
+     itr2;
+     itr2 = itr2->parent)
+ {
+  LLIST_FOREACH_REV (&tls->res_stack, p)
+   {
+    struct nobug_resource_user* user =
+     LLIST_TO_STRUCTP (p,
+                       struct nobug_resource_user,
+                       res_stack);
+    if (user->current->resource == itr2->resource)
+     goto done;
+   }
+  ...
 ---------------------------------------------------------------------
 
 If no ancestor found, we finally abort with a potential deadlock condition.
 
 [source,c]
 ---------------------------------------------------------------------
-                          nobug_resource_error = "possible deadlock detected";
-                          return NULL;
-                          ...
+nobug_resource_error = "possible deadlock detected";
+return NULL;
 ---------------------------------------------------------------------
 
 
-[[nobug_resource_leave]]
 Leaving Resources
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 store the tail and next aside, we need it later
 
 [source,c]
 ---------------------------------------------------------------------
 #if NOBUG_USE_PTHREAD
-      struct nobug_resource_user* tail =
-        LLIST_TO_STRUCTP (llist_tail (&user->thread->res_stack),
-                          struct nobug_resource_user,
-                          res_stack);
-      struct nobug_resource_user* next =
-        LLIST_TO_STRUCTP (llist_next (&user->res_stack),
-                          struct nobug_resource_user,
-                          res_stack);
+struct nobug_resource_user* tail =
+ LLIST_TO_STRUCTP (llist_tail (&user->thread->res_stack),
+                   struct nobug_resource_user,
+                   res_stack);
+struct nobug_resource_user* next =
+ LLIST_TO_STRUCTP (llist_next (&user->res_stack),
+                   struct nobug_resource_user,
+                   res_stack);
+...
 ---------------------------------------------------------------------
 
 remove user struct from thread stack
@@ -2172,7 +2390,8 @@ We now need to fix the node tree up to match this list.
 
 [source,c]
 ---------------------------------------------------------------------
-      llist_unlink_fast_ (&user->res_stack);
+llist_unlink_fast_ (&user->res_stack);
+...
 ---------------------------------------------------------------------
 
 When the the user node was not the tail or only node of the thread stack, we have to check
@@ -2181,16 +2400,17 @@ since it was already validated when entering the resources first.
 
 [source,c]
 ---------------------------------------------------------------------
-      if (user != tail && !llist_is_empty (&user->thread->res_stack))
-        {
-          struct nobug_resource_user* parent = NULL;
-          if (llist_head (&user->thread->res_stack) != &next->res_stack)
-            {
-              parent =
-                LLIST_TO_STRUCTP (llist_prev (&next->res_stack),
-                                  struct nobug_resource_user,
-                                  res_stack);
-            }
+if (user != tail && !llist_is_empty (&user->thread->res_stack))
+ {
+  struct nobug_resource_user* parent = NULL;
+  if (llist_head (&user->thread->res_stack)!= &next->res_stack)
+   {
+    parent =
+     LLIST_TO_STRUCTP (llist_prev (&next->res_stack),
+                       struct nobug_resource_user,
+                       res_stack);
+   }
+  ...
 ---------------------------------------------------------------------
 
 iterate over all users following the removed node, finding nodes pointing to this users or
@@ -2198,155 +2418,77 @@ create new nodes.
 
 [source,c]
 ---------------------------------------------------------------------
-          LLIST_FORRANGE (&next->res_stack, &user->thread->res_stack, n)
-            {
-              struct nobug_resource_user* cur =
-                LLIST_TO_STRUCTP (n,
-                                  struct nobug_resource_user,
-                                  res_stack);
-
+LLIST_FORRANGE (&next->res_stack, &user->thread->res_stack, n)
+ {
+  struct nobug_resource_user* cur =
+   LLIST_TO_STRUCTP (n,
+                     struct nobug_resource_user,
+                     res_stack);
+
+  struct nobug_resource_record* resource =
+   cur->current->resource;
+  ...
 ---------------------------------------------------------------------
 
 find the node pointing back to parent, create a new one if not found, rinse repeat
 
 [source,c]
 ---------------------------------------------------------------------
-              struct nobug_resource_node templ =
-                {
-                  ...
-                  NULL,
-                  ...
-                };
-
-              struct nobug_resource_node* node = (struct nobug_resource_node*)
-                llist_ufind (&resource->nodes,
-                             &templ.node,
-                             nobug_resource_node_parent_cmpfn,
-                             NULL);
-
-              if (!node)
-                {
-                  node = nobug_resource_node_new (resource,
-                                                  parent?parent->current:NULL);
-                  if (!node)
-                    {
-                      nobug_resource_error = "internal allocation error";
-                      return 0;
-                    }
-                }
-
-              parent = cur;
-            }
-        }
+struct nobug_resource_node templ =
+ {
+  ...
+  parent?parent->current:NULL,
+  ...
+ };
+
+struct nobug_resource_node* node =
+ (struct nobug_resource_node*)
+ llist_ufind (&resource->nodes,
+              &templ.node,
+              nobug_resource_node_parent_cmpfn,
+              NULL);
+
+if (!node)
+ {
+  node = nobug_resource_node_new (resource,
+                                  parent?parent->current:NULL);
+  if (!node)
+   {
+    nobug_resource_error = "internal allocation error";
+    return 0;
+   }
+ }
+
+parent = cur;
 ---------------------------------------------------------------------
 
 
-Index
------
-
-xref:ABORT[Aborting]:: abort the program
-xref:abort_callback[callback for aborting]:: hook to handle a termination
-xref:abort_cb[type of abort callback]:: type of a abort callback function
-xref:ALERT[ALERT]:: about to die
-xref:ASSERT[ASSERT]:: generic assertion
-xref:assert[assert]:: C standard assertion
-xref:BACKTRACE[Backtraces]:: generate a backtrace
-xref:buildlevel[Build Levels]:: selecting the build level
-xref:callback_data[passing data to callbacks]:: data to be passed to callbacks
-xref:CHECK[CHECK]:: unnconditional assertion for testsuites
-xref:CHECKED[CHECKED, Scope]:: tag scope as reviewed
-xref:COVERAGE_DISABLE[Disabling and enabling fault-coverage checks]:: handle false positives
-xref:COVERAGE_FAULT[COVERAGE_FAULT]:: coverage fault injection, statement
-xref:COVERAGE_GOODBAD[COVERAGE_GOODBAD]:: coverage fault injection, expression
-xref:COVERAGE_LEVEL[COVERAGE_LEVEL]:: coverage fault injection log level
-xref:Cplusplus_logflags[C++ support, C++ logflags]:: C++ support for log flags
-xref:CRITICAL[CRITICAL]:: can not continue
-xref:deadlock_detection[The Resource Tracking Algorithm]:: how resources are tracked
-xref:DECLARE_FLAG[DECLARE_FLAG]:: declaring a flag
-xref:DECLARE_ONLY[DECLARE_ONLY]:: force flag declarations only
-xref:DEFINE_FLAG[DEFINE_FLAG]:: defining a flag
-xref:DEFINE_FLAG_LIMIT[DEFINE_FLAG_LIMIT]:: defining a flag w/ log limit
-xref:DEFINE_FLAG_PARENT[DEFINE_FLAG_PARENT]:: defining a flag hierarchy
-xref:DEFINE_FLAG_PARENT_LIMIT[DEFINE_FLAG_PARENT_LIMIT]:: defining a flag hierarchy, w/ log limit
-xref:DEPRECATED[DEPRECATED]:: to be discarded in future
-xref:DUMP[DUMP]:: dumping datastructures
-xref:DUMP_LOG[DUMP_LOG]:: logging helper for dumping
-xref:ECHO[ECHO]:: unconditional logging for tests
-xref:ELSE_NOTREACHED[ELSE_NOTREACHED]:: alternative never taken
-xref:ENSURE[ENSURE]:: postconditions (computation outcomes)
-xref:ERROR[ERROR]:: something gone wrong
-xref:FIXME[FIXME]:: known bug
-xref:INFO[INFO]:: progress message
-xref:INJECT_FAULT[INJECT_FAULT]:: fault injection statement
-xref:INJECT_GOODBAD[INJECT_GOODBAD]:: fault injection expression
-xref:INJECT_LEVEL[INJECT_LEVEL]:: log level for fault injection
-xref:INVARIANT[INVARIANT]:: validate invariant state
-xref:LOG[LOG]:: generic logging
-xref:LOG_BASELIMIT[LOG_BASELIMIT]:: minimum compliled-in logging limit
-xref:logflags[Log Flags]:: define hierarchies for logging output
-xref:logging_callback[callback when logging]:: hook when something get logged
-xref:logging_cb[type of logging callbacks]:: type of a logging callback function
-xref:multithreading[Multithreading]:: using NoBug in multithreaded programs
-xref:NOBUG_ALPHA_COMMA[NOBUG_ALPHA_COMMA]:: append something after a comma in *ALPHA* builds
-xref:NOBUG_ANN[NOBUG_ANN]:: log flag for annotations
-xref:NOBUG_CONTEXT[Source Contexts]:: pass information about the source location
-xref:NOBUG_ENV[Control what gets logged]:: environment variable for loging control
-xref:nobug_flag[nobug (flag)]:: log flag used to show nobug actions
-xref:NOBUG_FLAG_RAW[NOBUG_FLAG_RAW]:: pass direct flag pointer
-xref:NOBUG_IF[NOBUG_IF_*]:: include code conditionally on build level
-xref:NOBUG_ON[NOBUG_ON]:: log flag which is always enabled
-xref:nobug_resource_enter[Entering Resources]:: deadlock check on enter
-xref:nobug_resource_leave[Leaving Resources]:: fix resource lists
-xref:NOTICE[NOTICE]:: detailed progress message
-xref:NOTREACHED[NOTREACHED]:: code path never taken
-xref:PLANNED[PLANNED]:: ideas for future
-xref:postlogging_callback[callback after logging]:: hook after something get logged
-xref:rbdump[Dumping Persistent Ringbuffers]:: dumping persistent ringbuffers
-xref:REQUIRE[REQUIRE]:: preconditions (input parameters)
-xref:RESOURCE_ANNOUNCE[RESOURCE_ANNOUNCE]:: publish new resources
-xref:RESOURCE_ASSERT_STATE[RESOURCE_ASSERT_STATE]:: assert the state of a resource
-xref:RESOURCE_DUMP[RESOURCE_DUMP]:: dump the state of a single resource
-xref:RESOURCE_DUMPALL[RESOURCE_DUMPALL]:: dump the state of all resources
-xref:RESOURCE_ENTER[RESOURCE_ENTER]:: claim a resource
-xref:RESOURCE_FORGET[RESOURCE_FORGET]:: remove resources
-xref:RESOURCE_HANDLE[RESOURCE_HANDLE]:: define resource handles
-xref:RESOURCE_LEAVE[RESOURCE_LEAVE]:: relinquish a claimed resource
-xref:RESOURCE_LIST[RESOURCE_LIST]:: enumerate all registered resources
-xref:RESOURCE_LOG_LEVEL[RESOURCE_LOG_LEVEL]:: select the log level for resource logging
-xref:RESOURCE_LOGGING[RESOURCE_LOGGING]:: switch resource logging on and off
-xref:RESOURCE_RESET[RESOURCE_RESET]:: reset a single resource to a pristine state
-xref:RESOURCE_RESETALL[RESOURCE_RESETALL]:: reset the resource tracker to a pristine state
-xref:RESOURCE_STATE[RESOURCE_STATE]:: change the state of a resource
-xref:RESOURCE_TRY[RESOURCE_TRY]:: wait for a resource to become available
-xref:RESOURCE_WAIT[RESOURCE_WAIT]:: wait for a resource to become available
-xref:THREAD_DATA[NOBUG_THREAD_DATA]:: thread local data for application use
-xref:THREAD_ID_GET[NOBUG_THREAD_ID_GET]:: query thread id
-xref:THREAD_ID_SET[NOBUG_THREAD_ID_SET]:: set or reset thread id
-xref:TODO[TODO]:: things to be done
-xref:TRACE[TRACE]:: debugging level message
-xref:UNCHECKED[UNCHECKED, Scope]:: tag scope as unreviewed
-xref:UNIMPLEMENTED[UNIMPLEMENTED]:: not yet implemented
-xref:WARN[WARN]:: unexpected fixable error
+Reference Index
+---------------
+
+[dotted]
 
 License
 -------
 
-    NoBug
-    Copyright (C) 2009          Christian Thäter <ct@pipapo.org>
+ NoBug
+ Copyright (C)
+ 2006, 2007, 2008, 2009, 2010   Christian Thäter <ct@pipapo.org>
 
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
 
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
 
-    You should have received a copy of the GNU General Public License along
-    with this program; if not, write to the Free Software Foundation, Inc.,
-    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ You should have received a copy of the GNU General Public
+ License along with this program; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301 USA.
 
 .License Rationale
 
@@ -2366,19 +2508,18 @@ linking, then NoBug isn't used anymore and you may apply BSD license
 terms for resulting binaries.
 
 
-Contributor Agreement
-~~~~~~~~~~~~~~~~~~~~~
+.Contributor Agreement
 
 Improvements and patches must be licensed as "GPL v2 or any later" to
 be acceptable. Further a contributor must either assign his copyright
 to the main NoBug author or agree with the possibility that NoBug can
 be relicensed for propietary use:
 
- Independent of the GPL license as stated above, The main author of
- NoBug explicitly reserve the right to relicense NoBug under
- different, even propietary terms. Any contributor agrees to such
- a possiblility by sending his contribution to be included into
- the official releases.
+ Independent of the GPL license as stated above, The main author
of NoBug explicitly reserve the right to relicense NoBug under
+ different, even propietary terms. Any contributor agrees to
+ such a possiblility by sending his contribution to be included
into the official releases.
 
  This agreement is bilateral, every contributor who worked on a
  substantial part of NoBug has the right to relicense it after
@@ -2401,3 +2542,30 @@ author (or any other main contributor).
 If anyone feels he is not credited in the 'AUTHORS' file or in any
 copyright notice, please contact the main author for inclusion.
 
+Credits
+-------
+
+Design, implementation::
+ Christian Thaeter $$<ct@pipapo.org>$$ +
+
+Testsuite::
+ Christian Thaeter $$<ct@pipapo.org>$$ +
+
+Documentation::
+ Christian Thaeter $$<ct@pipapo.org>$$ +
+ Benny Lyons $$<benny.lyons@uniserv.com>$$ +
+ François KUBLER $$<ih8tehuman@free.fr>$$ +
+ Andreas Hermann Braml $$<andreas@braml.org>$$ +
+
+Autoconf build system improvements::
+ Peter Simons $$<simons@cryp.to>$$ +
+ Luca Barbato $$<lu_zero@gentoo.org>$$ +
+ Michael Ploujnikov $$<ploujj@gmail.com>$$ +
+
+Ringbuffer dump tool::
+ Simeon Voelkel $$<simeon_voelkel@arcor.de>$$ +
+
+Logo::
+ Pablo Lizardo $$<pablo_lizardo@yahoo.com.ar>$$ +
+
+
diff --git a/VERSION b/VERSION
index dbb48b5..84e3ef1 100644 (file)
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-201006.1
+201008.1
index 393fa35..7beb9fe 100644 (file)
@@ -1,4 +1,4 @@
-AC_INIT([nobug], [201006.1], [nobug@lists.pipapo.org])
+AC_INIT([nobug], [201008.1])
 AC_CONFIG_SRCDIR([src/nobug.h])
 AC_CONFIG_AUX_DIR([scripts])
 AC_CONFIG_MACRO_DIR([m4])