Finish updating the manpage; make the example config file match.

diff --git a/doc/htsnrc.example b/doc/htsnrc.example
index f82e19586853272c02e3dfc91288a48a96d8a889..6ddcebeeafda540e27589a12deb9f1fc1cc539cc 100644 (file)
--- a/doc/htsnrc.example
+++ b/doc/htsnrc.example
@@ -57,21 +57,28 @@
 # password = "whatever"
 
 
-# (Daemon mode only) Create a PID file in the given location.
+# (Daemon mode only) Create a PID file in the given location. This is
+# used by the init system on Unix to keep track of the running daemon.
 #
 # Default: /run/htsn.pid
 #
 # pidfile = /var/run/htsn.pid
 
 
-# (Daemon mode only) Run htsn as the specified system grup.
+# (Daemon mode only) Run htsn as the specified system grup. The PID
+# file is written before privileges are dropped, so the only
+# privileges needed by htsn are those necessary to write the XML files
+# and (optionally) the log file.
 #
 # Default: the current group
 #
 # run-as-group = htsn
 
 
-# (Daemon mode only) Run htsn as the specified system user.
+# (Daemon mode only) Run htsn as the specified system user. The PID
+# file is written before privileges are dropped, so the only
+# privileges needed by htsn are those necessary to write the XML files
+# and (optionally) the log file.
 #
 # Default: the current user
 #

diff --git a/doc/man1/htsn.1 b/doc/man1/htsn.1
index ed2d0db7cbb88123dc2d16de1f906ea0d1a2d225..db20cac4b14769a1709c853b5e5056414f40d9fe 100644 (file)
--- a/doc/man1/htsn.1
+++ b/doc/man1/htsn.1
@@ -14,6 +14,20 @@ The Sports Network <http://www.sportsnetwork.com> offers an XML feed
 containing various sports news and statistics. The goal of \fBhtsn\fR
 is to watch the XML feed and parse the individual XML documents into
 files.
+.P
+Once started, we will choose an XML feed host to connect to. The
+choice is made from a list in a round-robin fashion, and by default,
+the list contains all known TSN feed hosts. Once we have a connection,
+your username and password are sent. If they are accepted, we begin to
+parse the feed saving all XML files to the configured output directory
+(see \fI\-\-output\-directory\fR).
+.P
+If we encounter an error (say, the connection is dropped), then we
+will attempt to connect to the next host in the list after waiting
+five seconds. This process continues indefinitely.
+.P
+The program can run either interactively (i.e. outputting to the
+console), or as a daemon with the \fI\-\-daemonize\fR flag.
 
 .SH INPUT
 
@@ -24,9 +38,11 @@ on the command-line or in a configuration file.
 .SH OUTPUT
 
 .P
-Standard out and standard error are fairly noisy. All traffic between
-htsn and the feed server is displayed on stdout. Status messages are
-interspersed when they are generated.
+Output is not generated when running as a daemon; otherwise, standard
+out and standard error are fairly noisy. All traffic between htsn and
+the feed server is displayed on stdout. Status messages are
+interspersed when they are generated with warnings and errors going to
+stderr. The following can be expected:
 .IP \[bu] 2
 The only data we send to the feed are the username and password. These
 will be highlighted in green on stdout.
@@ -43,12 +59,19 @@ Errors will be highlighted in red and sent to stderr.
 .SH LOGGING
 
 Logging is done either to syslog or a file. The destination and
-verbosity are controlled by the \fIlog_file\fR, \fIlog_level\fR, and
-\fIsyslog\fR parameters which may be specified either on the
-command line or in the configuration file.
+verbosity are controlled by the \fI\-\-log_file\fR,
+\fI\-\-log_level\fR, and \fI\-\-syslog\fR parameters which may be
+specified either on the command line or in the configuration file.
 
 .SH OPTIONS
 
+.IP \fB\-\-daemonize\fR
+Run as a daemon, in the background. When running as a daemon the
+\fI\-\-pidfile\fR, \fI\-\-run\-as\-group\fR, and
+\fI\-\-run\-as\-user\fR flags become relevant.
+
+Default: disabled
+
 .IP \fB\-\-log-file\fR
 If you specify a file here, logs will be written to it (possibly in
 addition to syslog). Can be either a relative or absolute path. It
@@ -64,23 +87,47 @@ interesting notifications will be logged as well.
 
 Default: INFO
 
-.IP \fB\-\-password\fR,\ \fB\-p\fR
+.IP \fB\-\-output\-directory\fR,\ \fB\-o\fR
+To which directory should we write the XML files?
+
+Default: .
+
+.IP \fB\-\-password\fR
 The password associated with your TSN username. A password is
 required, so you must supply one either on the command line or in a
 configuration file.
 
 Default: none
 
-.IP \fB\-\-output_directory\fR,\ \fB\-o\fR
-To which directory should we write the XML files?
+.IP \fB\-\-pidfile\fR
+(Daemon mode only) Create a PID file in the given location. This is
+used by the init system on Unix to keep track of the running daemon.
 
-Default: .
+Default: /run/htsn.pid
+
+.IP \fB\-\-run\-as\-group\fR
+(Daemon mode only) Run as the given system group. The PID file is
+written before privileges are dropped, so the only privileges needed
+by htsn are those necessary to write the XML files and (optionally)
+the log file.
+
+Default: the current group
+
+.IP \fB\-\-run\-as\-user\fR
+(Daemon mode only) Run as the given system user. The PID file is
+written before privileges are dropped, so the only privileges needed
+by htsn are those necessary to write the XML files and (optionally)
+the log file.
+
+Default: the current user
 
 .IP \fB\-\-syslog\fR,\ \fB\-s\fR
 Enable logging to syslog. On Windows this will attempt to communicate
 (over UDP) with a syslog daemon on localhost, which will most likely
 not work.
 
+Default: disabled
+
 .IP \fB\-\-username\fR,\ \fB\-u\fR
 Your TSN username. A username is required, so you must supply one
 either on the command line or in a configuration file.