-"""Utilities related to logging. To use it you must invoke
-:meth:`initialize_logging`. If you use the
-:meth:`bootstrap.initialize` decorator on your program's entry point,
-it will call this for you. See :meth:`python_modules.bootstrap.initialize`
-for more details. If you use this you get:
-
-* Ability to set logging level,
-* ability to define the logging format,
-* ability to tee all logging on stderr,
-* ability to tee all logging into a file,
-* ability to rotate said file as it grows,
-* ability to tee all logging into the system log (syslog) and
- define the facility and level used to do so,
-* easy automatic pid/tid stamp on logging for debugging threads,
-* ability to squelch repeated log messages,
-* ability to log probabilistically in code,
-* ability to only see log messages from a particular module or
- function,
-* ability to clear logging handlers added by earlier loaded modules.
-
-All of these are controlled via commandline arguments to your program,
-see the code below for details.
+"""
+This is a module that offers an opinionated take on how whole program
+logging should be initialized and controlled. It uses the standard
+Python :mod:`logging` but gives you control, via commandline config,
+to do things such as:
+
+ * Set the logging default level (debug, info, warning, error, critical)
+ of the whole program (see: :code:`--logging_level`)... and to override
+ the logging level for individual modules/functions based on their names
+ (see :code:`--lmodule`),
+ * define the logging message format (see :code:`--logging_format` and
+ :code:`--logging_date_format`) including easily adding a PID/TID
+ marker on all messages to help with multithreaded debugging
+ (:code:`--logging_debug_threads`) and force module names of code
+ that emits log messages to be included in the format
+ (:code:`--logging_debug_modules`),
+ * control the destination of logged messages:
+
+ - log to the console/stderr (:code:`--logging_console`) and/or
+ - log to a rotated file (:code:`--logging_filename`,
+ :code:`--logging_filename_maxsize` and :code:`--logging_filename_count`)
+ and/or
+ - log to the UNIX syslog (:code:`--logging_syslog` and
+ :code:`--logging_syslog_facility`)
+
+ * optionally squelch repeated messages (:code:`--logging_squelch_repeats`),
+ * optionally log probalistically (:code:`--logging_probabilistically`),
+ * capture printed messages into the info log (:code:`--logging_captures_prints`),
+ * and optionally clear unwanted logging handlers added by other imports
+ before this one (:code:`--logging_clear_preexisting_handlers`).
+
+To use this functionality, call :meth:`initialize_logging` early
+in your program entry point. If you use the
+:meth:`pyutils.bootstrap.initialize` decorator on your program's entry
+point, it will call this for you automatically.