[trac622] Additional changes to documentation

src/lib/log/README

@@ -59,7 +59,7 @@ The steps in using the system are:
 
 2. Run it through the message compiler to produce the .h and .cc files.  It
    is intended that this step be included in the build process.  However,
-   for not run the compiler (found in the "compiler" subdirectory) manually.
+   for now run the compiler (found in the "compiler" subdirectory) manually.
    The only argument is the name of the message file: it will produce as
    output two files, having the same name as the input file but with file
    types of ".h" and ".cc".
@@ -74,7 +74,7 @@ The steps in using the system are:
 4. Declare loggers in your code and use them to log messages.  This is
    described in more detail below.
 
-5. To set the debug level and run-time message file, call runTimeInit (declared
+5. To set the debug level and run-time message file, call initLogger (declared
    in logger_support.h) in the main program unit.  This is a temporary solution
    for Year 2, and will be replaced at a later date, the information coming
    from the configuration database.
@@ -106,7 +106,7 @@ UNKNOWN     unknown message
 
 Points to note:
 * Leading and trailing space are trimmed from the line.  Although the above
-  exampl,e has every line starting at column 1, the lines could be indented
+  example has every line starting at column 1, the lines could be indented
   if desired.
 
 * Blank lines are ignored.
@@ -120,10 +120,8 @@ Points to note:
   * $PREFIX, which has one argument: the string used to prefix symbols.  If
     absent, there is no prefix to the symbols. (Prefixes are explained below.)
   * $NAMESPACE, which has one argument: the namespace in which the symbols are
-    created.  (Specifying the argument as a double colon - i.e. "$NAMESPACE
-    ::" puts the symbol definitions in the unnamed namespace.  And not
-    including a $NAMESPACE directive will result in the symbols note being
-    put in any namespace.
+    created.  In the absence of a $NAMESPACE directive, symbols will be put
+    in the global namespace.
 
 * Lines starting + indicate an explanation for the preceding message.  These
   are intended to be processed by a separate program and used to generate
@@ -151,13 +149,11 @@ The message compiler processes the message file to produce two files:
 the form:
 
    namespace <namespace> {
-   isc::log::MessageID PREFIX_IDENTIFIER = "IDENTIFIER";
+   extern const isc::log::MessageID PREFIX_IDENTIFIER;
       :
    }
 
-The symbols define the keys in the global message dictionary.  At present
-they are defined as std::strings, but a future implementation could redefine
-them as numeric values.
+The symbols define the keys in the global message dictionary.
 
 The namespace enclosing the symbols is set by the $NAMESPACE directive.
 
@@ -167,14 +163,18 @@ ABC with "MSG_" to give the symbol MSG_ABC.  Similarly "$PREFIX E" would
 prefix it with "E" to give the symbol EABC.  If no $PREFIX is given, no
 prefix appears (so the symbol in this example would be ABC).
 
-The header file also includes a couple of lines to ensure that the message
-text is included in the final program image.
+2) A C++ source file (called <message-file-name>.cc) that holds the definitions
+of the global symbols and code to insert the symbols and messages into the map.
 
+Symbols are defined to be equal to strings holding the identifier, e.g.
 
-2) A C++ source file (called <message-file-name>.cc) that holds the code to
-insert the symbols and messages into the map.
+   extern const isc::log::MessageID MSG_DUPLNS = "DUPLNS";
 
-This file declares an array of identifiers/messages in the form:
+(The implementation allows symbols to be compared.  However, use of strings
+should not be assumed - a future implementation may change this.)
+
+iIn addition, the file declares an array of identifiers/messages and an object
+to add them to the global dictionary:
 
     namespace {
     const char* values[] = {
@@ -183,20 +183,9 @@ This file declares an array of identifiers/messages in the form:
         :
         NULL
     };
-    }
-
-(A more complex structure to group identifiers and their messages could be
-imposed, but as the array is generated by code and will be read by code,
-it is not needed.)
 
-It then declares an object that will add information to the global dictionary:
-
-    MessageInitializer <message-file-name>_<time>(values);
-
-(Declaring the object as "static" or in the anonymous namespace runs the risk
-of it being optimised away when the module is compiled with optimisation.
-But giving it a standard name would cause a clash when multiple files are
-used, hence an attempt at disambiguation.)
+    const isc::log::MessageInitializer initializer(values);
+    }
 
 The constructor of the MessageInitializer object retrieves the singleton
 global Dictionary object (created using standard methods to avoid the
@@ -236,7 +225,7 @@ To use the current version of the logging:
    (The argument is required to support a possible future implementation of
    logging.  Currently it has no effect.)
 
-3. The main program unit should include a call to isc::log::runTimeInit()
+3. The main program unit should include a call to isc::log::initLogger()
    (defined in logger_support.h) to set the logging severity, debug log level,
    and external message file.
 
@@ -250,13 +239,13 @@ To use the current version of the logging:
         isc::log::NONE
 
    b) The debug log level is only interpreted when the severity is DEBUG and
-      is an integer raning from 0 to 99.  0 should be used for the highest-level
-      debug messages and 99 for the lowest-level (and typically more verbose)
-      messages.
+      is an integer ranging from 0 to 99.  0 should be used for the
+      highest-level debug messages and 99 for the lowest-level (and typically
+      more verbose) messages.
 
    c) Name of an external message file.  This is the same as a standard message
-      file, although it should not include the $PREFIX directive. (A single
-      $PREFIX directive will be ignored; multiple directives will cause the
+      file, although it should not include any directives. (A single directive
+      of a particular type will be ignored; multiple directives will cause the
       read of the file to fail with an error.)  If a message is replaced, the
       message should include the same printf-format directives in the same order
       as the original message.
@@ -340,7 +329,7 @@ Logging Sources v Logging Severities
 When logging events, make a distinction between events related to the server
 and events related to DNS messages received.  Caution needs to be exercised
 with the latter as, if the logging is enabled in the normal course of events,
-such logging could be a denoial of service vector. For example, suppose that
+such logging could be a denial of service vector. For example, suppose that
 the main authoritiative service logger were to log both zone loading and
 unloading as INFO and a warning message if it received an invalid packet. An
 attacker could make the INFO messages unusable by flooding the server with
@@ -353,7 +342,7 @@ DEBUG is not enabled by default, so these events will not be recorded unless
 DEBUG is specifically chosen.
 
 b) Record system-related and packet-related messages via different loggers
-(e.g.  in the example given, sever events could be logged using the logger
+(e.g.  in the example given, server events could be logged using the logger
 "auth" and packet-related events at that level logged using the logger
 "pkt-auth".)  As the loggers are independent and the severity levels
 independent, fine-tuning of what and what is not recorded can be achieved.
@@ -380,7 +369,7 @@ Outstanding Issues
 log4cxx Issues
 ==============
 Some experimental code to utilise log4cxx as an underlying implementation
-is present in the source code directory, although it is not currently used.
+is present in the source code directory although it is not currently used.
 The files are:
 
    logger_impl_log4cxx.{cc,h}