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"
 
 
 # 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
 
 
 #
 # 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
 
 
 #
 # 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
 #
 #
 # 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.
 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
 
 
 .SH INPUT
 


@@ -24,9 +38,11 @@ on the command-line or in a configuration file.
 .SH OUTPUT
 
 .P
 .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.
 .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
 .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
 
 
 .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
 .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
 
 
 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
 
 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.
 
 
 .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.
 .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.