Merge remote branch 'mob/benny2' into devel
authorChristian Thaeter <ct@pipapo.org>
Sun, 15 Aug 2010 09:01:09 +0000 (11:01 +0200)
committerChristian Thaeter <ct@pipapo.org>
Sun, 15 Aug 2010 09:01:09 +0000 (11:01 +0200)
* mob/benny2:
  Text moved to nobug.h.
  Description of Source Code Annotations expanded.
  Improvements to text describing macros.
  Language and text improvements. No significant change to content.

doc/initialization.txt
doc/latex.conf
doc/logflags.txt
doc/logflagsenv.txt
doc/logformat.txt
doc/overview.txt
doc/using.txt
src/nobug.c

index 0c17e96..586183e 100644 (file)
@@ -2,20 +2,16 @@ HEAD- Initialization;;
 
 HEAD++ Global Initialization;;
 
-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:
-
-  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 is already using NoBug features from dynamic
-initialized properties in C++, one has to ensure that NoBug is first initialized
-possibly by pulling up a singleton as the very first thing.
+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.
 
 
 HEAD== Destroying NoBug;;
index f6b5491..e717ec9 100644 (file)
@@ -137,7 +137,7 @@ _=\_{}
 !..tilde..!=~
 !..bar..!=|
 !..doublequote..!="
-
+#"
 
 
 # Ruler is interpreted as a page break.
@@ -241,7 +241,7 @@ superscript=!..backslash..!textsuperscript!..braceleft..!|!..braceright..!
 subscript=!..backslash..!textsubscript!..braceleft..!|!..braceright..!
 singlequoted=``|''
 doublequoted=`|'
-
+#'
 
 
 # Quoted text.
@@ -336,10 +336,10 @@ template::[admonitionblock]
 # but inserting the same "[]" below doesn't.
 
 [listingblock]
-\minisec\{{caption=Listing: }{title}\}
+\minisec\{{caption=}{title}\}
 \label\{{id}\}\\hypertarget\{{id}\}\{\}
 \begin\{verbatim\}
-{newline}|{newline}
+|
 \end\{verbatim\}
 {newline}
 
index d30e35a..88766fe 100644 (file)
@@ -5,12 +5,12 @@ grained sections of the code. These are referred to as 'channels' in other
 logging libraries.
 
 Flags are generally used as follows:
+
     * Declare the flag.
     * Define the flag.
     * Initialise the flag.
 
-To declare a flag, it is suggested to do so in a header file: 
+To declare a flag, it is suggested to do so in a header file:
 
 INDEX DECLARE_FLAG; DECLARE_FLAG; declaring a flag
  NOBUG_DECLARE_FLAG(flagname)
@@ -40,7 +40,7 @@ INDEX DEFINE_FLAG_PARENT_LIMIT; DEFINE_FLAG_PARENT_LIMIT; defining a flag hierar
 This can be used to create hierachies of flags.
 
 
-PARA C\++ support, C++ logflags; Cplusplus_logflags; C\++ support for log flags
+HEAD^ C\++ support, C++ logflags; Cplusplus_logflags; C\++ support for log flags
 
 Additional macros are available for applications written in C++:
 
@@ -53,16 +53,16 @@ These macros statically initialize the flags when they are defined, there is no
 need to call `NOBUG_INIT_FLAG()` (see below).
 
 
-.Force declarations only
+HEAD^ Force declarations only; NOBUG_DECLARE_ONLY; force flag declarations
 
-When `INDEX DECLARE_ONLY` is defined to be `1` 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>
@@ -96,7 +96,7 @@ NOBUG_DEFINE_FLAG(example);
 ----
 
 
-.Logging Flag Initialization
+HEAD^ Logging Flag Initialization; INIT_FLAG; initialize log flags from environment
 
 After a flag has been declared and defined, it has to be initialised:
 
@@ -106,10 +106,12 @@ or
 
  NOBUG_INIT_FLAG_LIMIT(flagname, default)
 
-Use either of these macros once at the begining your prrogramme for each flag.
+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:logdefaults[table above], while
-`NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the
-default target (depending on build level) to `level`.
+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`.
 
index 7d29aac..0b4f1a6 100644 (file)
@@ -1,10 +1,9 @@
 HEAD~ Controlling what gets logged; NOBUG_ENV; environment variable for loging control
 
-The `NOBUG_INIT_FLAG...` series of macros parse an environment variable:
-'NOBUG_LOG'. This enviromnet variable iis thus used to configure what is
+The `NOBUG_INIT_FLAG...` series of macros parse the environment variable
+'$NOBUG_LOG'. This enviromnet variable iis thus used to configure what is
 logged at runtime. Its syntax is as following:
 
-.Formal Syntax for log control
 [source,prolog]
 ----
 logdecl_list --> logdecl, any( ',' logdecl_list).
@@ -29,7 +28,7 @@ declarations are optional and defaults are selected from the 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
+HEAD^ Targets and Options; logging options; configure what gets logged
 
 The Following options are available:
 
index 8a011d5..2c1c1fc 100644 (file)
@@ -17,7 +17,7 @@ The components are delimited by ": " or in one case by "! " are as following:
    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 some log lines, the
+   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.
index dd7cac2..3c24cea 100644 (file)
@@ -24,9 +24,12 @@ The following features are provided by NoBug:
   * 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 in the build level you choose NoBug features
+will be integral part of your application making it possible to gather
+debugging data for each stage of the application development, including
+collecting debugging infos for finally deployed applications.
 
 PARA What NoBug can not do;;
 
index 49503b2..8133666 100644 (file)
@@ -21,12 +21,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
index bedde33..1c4c19b 100644 (file)
@@ -61,7 +61,7 @@ struct nobug_flag nobug_flag_NOBUG_ANN =
 {NULL, NULL, 0, {LOG_DEBUG, LOG_DEBUG, LOG_DEBUG, -1, LOG_WARNING}, NULL, NULL, NULL};
 
 /*
-//predefflags PARA nobug (flag); nobug_flag; log flag used to show nobug actions
+//predefflags PARA nobug; nobug, flag; log flag used to show nobug actions
 //predefflags
 //predefflags Actions on NoBug itself will be logged under the `nobug` flag itself.
 //predefflags To see whats going on you can enable it with `NOBUG_LOG=nobug:TRACE`.