[py-svn] r24767 - py/dist/py/documentation

[pinard at codespeak.net]

Author: pinard
Date: Wed Mar 22 02:38:33 2006
New Revision: 24767

Modified:
   py/dist/py/documentation/log.txt
Log:
* documentation/log.txt: Corrections for reported typos, and also
a factual error about set_consumer.


Modified: py/dist/py/documentation/log.txt
==============================================================================
--- py/dist/py/documentation/log.txt	(original)
+++ py/dist/py/documentation/log.txt	Wed Mar 22 02:38:33 2006
@@ -30,14 +30,14 @@
 Logging organisation
 ====================
 
-Le :code:`py.log` module aims a niche comparable to the one of the
-`logging module`__ as found within standard Python distributions, yet
+The :code:`py.log` module aims a niche comparable to the one of the
+`logging module`__ found within the standard Python distributions, yet
 with much simpler paradigms for configuration and usage.
 
 __ http://www.python.org/doc/2.4.2/lib/module-logging.html
 
 Holger Krekel, the main :code:`py` library developer, introduced
-the idea of keyword-based logging and of logging *producers* and
+the idea of keyword-based logging and the idea of logging *producers* and
 *consumers*.  A log producer is an object used by the application code
 to send messages to various log consumers.  When you create a log
 producer, you define a set of keywords that are then used to both route
@@ -54,7 +54,7 @@
 Log is only future plans for now).  A log producer has never more than
 one consumer at a given time, but it is possible to dynamically switch
 a producer to use another consumer.  On the other hand, a single log
-consumer may be associated with really many producers.
+consumer may be associated with many producers.
 
 Note that creating and associating a producer and a consumer is done
 automatically when not otherwise overriden, so using :code:`py` logging
@@ -62,23 +62,22 @@
 the application programmer will likely design a hierarchy of producers,
 and will select keywords appropriately for marking the hierarchy tree.
 If a node of the hierarchical tree of producers has to be divided in
-sub-trees, all producers in the sub-trees have keywords which share,
-as a common prefix, the keywords of the node being divided.  In other
-words, we go further down in the hierarchy of producers merely by adding
-keywords.
+sub-trees, all producers in the sub-trees share, as a common prefix, the
+keywords of the node being divided.  In other words, we go further down
+in the hierarchy of producers merely by adding keywords.
 
 Using the :code:`py.log` library
 ================================
 
-For using the :code:`py.log` library, the user ought to import it into a
-Python application, have at least one log producer and one log consumer
-created, have producers and consumers associated, and finally call log
-producers as needed, giving them log messages.
+To use the :code:`py.log` library, the user must import it into a Python
+application, create at least one log producer and one log consumer, have
+producers and consumers associated, and finally call the log producers
+as needed, giving them log messages.
 
-Importing it
-------------
+Importing
+---------
 
-Once the :code:`py` library installed on your system, a mere::
+Once the :code:`py` library is installed on your system, a mere::
 
   import py
 
@@ -125,29 +124,27 @@
     hierarchy, and as such, is called whenever no other consumer is
     found.
 
-  + The notation ``log.STDOUT`` accesses a log consumer which writes log
-    messages on the Python standard output stream.
+  + The notation ``py.log.STDOUT`` accesses a log consumer which writes
+    log messages on the Python standard output stream.
 
-  + The notation ``log.STDERR`` accesses a log consumer which writes log
-    messages on the Python standard error stream.
+  + The notation ``py.log.STDERR`` accesses a log consumer which writes
+    log messages on the Python standard error stream.
 
-  + The ``log.File()`` constructor accepts, as argument, either a file
+  + The ``py.log.File()`` constructor accepts, as argument, either a file
     already opened in write mode or any similar file-like object, and
     creates a log consumer able to write log messages onto that file.
 
-  + The ``log.Path()`` constructor accepts a file name for its first
-    argument, and creates a log consumer able that will write log messages
-    into a file by that name, creating it as necessary.
-
-    The constructor call also accepts a few keyword parameters:
-
-      + ``append``, which is False by default, may be used for opening the
-        file in append mode instead of write mode.
-
-      + ``delayed_create``, which is False by default, maybe be used for
-        opening the file at the latest possible time.  Consequently, the
-        file will not be created if it did not exist, and no actual log
-        message gets written to it.
+  + The ``py.log.Path()`` constructor accepts a file name for its first
+    argument, and creates a log consumer able to write log messages into
+    that file.  The constructor call accepts a few keyword parameters:
+
+      + ``append``, which is ``False`` by default, may be used for
+        opening the file in append mode instead of write mode.
+
+      + ``delayed_create``, which is ``False`` by default, maybe be used
+        for opening the file at the latest possible time.  Consequently,
+        the file will not be created if it did not exist, and no actual
+        log message gets written to it.
 
       + ``buffering``, which is 1 by default, is used when opening the
         file.  Buffering can be turned off by specifying a 0 value.  The
@@ -167,11 +164,13 @@
 -----------------------------------
 
 Each log producer may have at most one log consumer associated with
-it.  A log producer gets associated with a log consumer through the
-``set_consumer()`` method of the log producer.  That method accepts
-a single argument, specifying the precise consumer to use for that
-producer.  Until this method is called for a producer, that producer
-does not have any explicit consumer associated with it.
+it.  A log producer gets associated with a log consumer through a
+``py.log.set_consumer()`` call.  That function accepts two arguments,
+the first identifying a producer (a tuple of keyword strings or a single
+space-separated string of keywords), the second specifying the precise
+consumer to use for that producer.  Until this function is called for a
+producer, that producer does not have any explicit consumer associated
+with it.
 
 Now, the hierarchy of log producers establishes which consumer gets used
 whenever a producer has not explicit consumer.  When a log producer
@@ -208,4 +207,4 @@
 
 + Should speak about pickle-ability of :code:`py.log`.
 
-+ What is :code:``log.get`` (in :file:`logger.py`)?
++ What is :code:`log.get` (in :file:`logger.py`)?