irkerd.xml: Cleanup syslog docs and shift 'os' import
authorW. Trevor King <wking@tremily.us>
Sat, 31 May 2014 16:40:03 +0000 (09:40 -0700)
committerEric S. Raymond <esr@thyrsus.com>
Sat, 31 May 2014 16:49:21 +0000 (12:49 -0400)
commit39722afaedcb568501d08ec69b657de4af95b14b
tree39ffe4d0e0c2de5983c77d04e6ed856dfad9d633
parent672240ab1bafa75503618a1e3993eda9c85a5fde
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>
irkerd
irkerd.xml