irkerd.xml: Cleanup syslog docs and shift 'os' import

This fixes some issues with 672240a (Use syslog facility when irkerd
is backgtrounded and no -l was given, 2014-05-31):

* Shift the 'os' import to keep the stdlib imports alphabetized.
* Move the syslog docs from a stand-alone paragraph into the
  -d/--log-level section.
* Add some text to the -d/--log-level docs explaining the distinction
  between the -l/--log-file traffic logs and the -d/--log-level
  program-tracing logs.
* StreamHandler logs to standard error (not standard output) by
  default [1].  Change "stndard output" to "standard error".
* Add articles to background and foreground ("the background").
* Fix a "packground" -> "background" typo.
* Explain our background-detection logic, and point out some of the
  assumptions made by the current implementation.  I still think that
  it's better to have an explicit --syslog setting, and to leave it to
  packagers/users to descide explicitly if they prefer logging to
  syslog or stderr.  But whatever the syslog-switching logic is, it
  should be clearly documented so folks don't have to read the source
  to understand it.

[1]: https://docs.python.org/3/library/logging.handlers.html#logging.StreamHandler

Signed-off-by: Eric S. Raymond <esr@thyrsus.com>

diff --git a/irkerd b/irkerd
index f7adadc414f047001b8c4d1c70ab2ae54d7a6e2d..2c66a1865af2ac9bbf00be586f00810e1ba93481 100755 (executable)
--- a/irkerd
+++ b/irkerd
@@ -42,11 +42,11 @@ CONNECTION_MAX = 200                # To avoid hitting a thread limit
 
 version = "2.8"
 
-import os
 import argparse
 import logging
 import logging.handlers
 import json
+import os
 try:  # Python 3
     import queue
 except ImportError:  # Python 2

diff --git a/irkerd.xml b/irkerd.xml
index d9de17fe418f6c8e0c12299898a6d9f368a0ffd9..00e7bc2ba4e6b86f7c9852258a4b7adc895adf91 100644 (file)
--- a/irkerd.xml
+++ b/irkerd.xml
@@ -108,10 +108,35 @@ joining a channel to log its traffic.</para>
 <variablelist>
 <varlistentry>
 <term>-d</term>
-<listitem><para>Takes a following value, setting the debugging level
-from it; possible values are 'critical', 'error', 'warning', 'info',
-'debug'. This option will generally only be of interest to developers;
-consult the source code for details.</para></listitem>
+<listitem>
+  <para>
+    Takes a following value, setting the debugging level from it;
+    possible values are 'critical', 'error', 'warning', 'info',
+    'debug'. This option will generally only be of interest to
+    developers, as the logs are designed to help trace
+    <application>irkerd</application>'s internal state.  These tracing
+    logs are independent of the traffic logs controlled by
+    <quote>-l</quote>.
+  </para>
+  <para>
+    Logging will be to standard error (if
+    <application>irkerd</application> is running in the foreground) or
+    to <quote>/dev/syslog</quote> with facility "daemon" (if
+    <application>irkerd</application> is running in the background).
+    The background-ness of <application>irkerd</application> is
+    determined by comparing the process group id with the process
+    group associated with the terminal attached to stdout (with
+    non-matches for background processes).  We assume you aren't
+    running <application>irkerd</application> in Windows or another OS
+    that doesn't support <quote>os.getpgrp</quote> or
+    <quote>tcgetpgrp</quote> or <quote>.  We also assume that you have
+    stdout attached to a TTY (and haven't closed or redirected it).
+    We also assume that if stdout is attached to a TTY associated with
+    the same process group as <application>irkerd</application>, you
+    do intend to log to stderr and not syslog.
+  </para>
+</refsect1>
+</listitem>
 </varlistentry>
 <varlistentry>
 <term>-l</term>
@@ -150,12 +175,6 @@ terminate.</para></listitem>
 </varlistentry>
 </variablelist>
 
-<para>If no <option>-l</option> is set, logging will be to stndard
-output (if <application>irkerd</application> is running in foreground)
-or to /dev/syslog with facility "daemon" (if
-<application>irkerd</application> is running in packground).</para>
-</refsect1>
-
 <refsect1 id='limitations'><title>LIMITATIONS</title>
 <para>Requests via UDP optimizes for lowest latency and network load
 by avoiding TCP connection setup time; the cost is that delivery is