Improve docs

diff --git a/examples/etc/pgwui.ini b/examples/etc/pgwui.ini
index bfe5a4ea9fe8efe0c6b5da2d73b9ce5fd293953d..5bf231c397b3e75004db6fb4f7bc2064c80dbcb5 100644 (file)
--- a/examples/etc/pgwui.ini
+++ b/examples/etc/pgwui.ini
@@ -180,12 +180,16 @@ port = 6543
 ###
 # logging configuration
 # http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+#
+# Configures logging via both syslog(3) and stderr, the latter being
+# suitable for a systemd service.
 ###
 
 [loggers]
 keys = root, pgwui_server, pgwui_upload
 
 [handlers]
+# Both syslog and stderr
 keys = syslog, console
 
 [formatters]
@@ -210,10 +214,11 @@ formatter = generic
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
 
-# These sections don't do anything as given.  They are provided so that
-# logging can be customized per pgwui package.  You may want to add
-# "propagate = False" lines to avoid duplicate logging if you customize
-# them to emit log messages.
+# These sections don't do anything as given.  Because they have no
+# handler they emit no messages.  They are provided so that logging
+# can be customized per pgwui package.  You may want to add
+# "propagate = False" lines to avoid duplicate logging if you
+# customize them to emit log messages.
 
 [logger_pgwui_server]
 level = INFO

diff --git a/examples/misc/development.ini b/examples/misc/development.ini
index c613b1b8ecffd1bad2880b78c2f3f22cd7bd50de..645de433e6583e8150d5fe9b8f4b35f9c0022729 100644 (file)
--- a/examples/misc/development.ini
+++ b/examples/misc/development.ini
@@ -89,7 +89,7 @@ pgwui.validate_hmac = False
 # PGWUI components in use.  The display value of the menu items can
 # be overridden using a "menu_label" setting for each component.
 # CAUTION: Do not uncomment the below, instead change the component's
-# "menu_label" setting.
+# "menu_label" setting.  E.g.:
 #pgwui.pgwui_upload =
 #    menu_label = upload -- Upload File Into Database
 
@@ -180,9 +180,14 @@ port = 6543
 ###
 # logging configuration
 # http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+#
+# Emit all logs, and stdout from the application, to stderr.
+# Configured so that logs are viewable from the terminal window used
+# to run pserve.
 ###
 
 [loggers]
+# See per-component loggers below
 keys = root, pgwui_server, pgwui_upload
 
 [handlers]
@@ -192,7 +197,7 @@ keys = console
 keys = generic
 
 [logger_root]
-level = INFO
+level = DEBUG
 handlers = console
 
 [handler_console]
@@ -204,10 +209,14 @@ formatter = generic
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
 
-# These sections don't do anything as given.  They are provided so that
-# logging can be customized per pgwui package.  You may want to add
-# "propagate = False" lines to avoid duplicate logging if you customize
-# them to emit log messages.
+#
+# Per-component logger configuration
+#
+# These sections don't do anything as given.  Because they have no
+# handler they emit no messages.  They are provided so that logging
+# can be customized per pgwui package.  You may want to add
+# "propagate = False" lines to avoid duplicate logging if you
+# customize them to emit log messages.
 
 [logger_pgwui_server]
 level = DEBUG