.SH SYNOPSIS
-\fBhtsn\fR [\fB-h\fR] [\fB-u\fR USERNAME] [\fB-p\fR PASSWORD] [\fB-f\fR FEED_HOSTS]
+\fBhtsn\fR [OPTIONS] [HOSTNAMES]
.SH DESCRIPTION
-
.P
-The Sports Network <http://www.sportsnetwork.com> offers an XML feed
-containing various sports news and statistics.
+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 (that is, outputting to the
+console), or as a daemon with the \fI\-\-daemonize\fR flag.
.SH INPUT
-
.P
The program takes no input; a username and password must be supplied
on the command-line or in a configuration file.
.SH OUTPUT
+.P
+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]
+All data received from the feed will be echoed in the default color to
+stdout.
+.IP \[bu]
+Informational messages will be highlighted in cyan and sent to stdout.
+.IP \[bu]
+Warnings will be highlighted in yellow and sent to stderr.
+.IP \[bu]
+Errors will be highlighted in red and sent to stderr.
+.SH LOGGING
.P
-There are three \(dqoutput streams\(dq:
+Logging is done either to syslog or a file. The destination and
+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,\ \fB\-d\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
+will not be auto-rotated; use something like logrotate for that.
+
+Default: none
+
+.IP \fB\-\-log-level\fR
+How verbose should the logs be? We log notifications at three levels:
+INFO, WARN, and ERROR. Specify the \(dqmost boring\(dq level of
+notifications you would like to receive (in all-caps); more
+interesting notifications will be logged as well.
+
+Default: INFO
+
+.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
-.nr step 1 1
-.IP \n[step] 2
-\fIStandard output/error\fR. The entire conversation with the feed
-will be output to standard out in the default color.
+.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.
-The username and password prompt from TSN will be highlighted in
-green. Errors will be highlighted in red. Informational messages will
-NOT be output to standard out, as they would interfere with the
-display of the XML on the wire.
+If necessary, its parent directory will be created with owner/group
+set to the appropriate user/group, but at most one directory will be
+created (that is, we won't create an entire directory tree).
-Warnings and errors will be written, in red, to standard error.
-.IP \n+[step]
-\fIXML files\fR. Each XML received from the feed will be inspected for
-an XML_File_ID element, and then written to a file named
-accordingly. The name fill be of the form <XML_File_ID>.xml, and it
-will be written to the \fBoutput_directory\fR described below.
-.IP \n+[step]
-\fILogs\fR. Informational messages, warnings, and errors will all be
-logged. This should eventually be configurable.
+Default: /run/htsn/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.
+
+Default: none
+
+.SH FEED HOSTS
+.P
+It is possible to pass a list of feed hostnames on the command-line
+(see [HOSTNAMES] in the synopsis). By default \fBhtsn\fR will attempt
+to connect to every known TSN XML feed host in a round-robin fashion,
+so there is rarely a need to do this.
+
+.SH CONFIGURATION FILE
+.P
+Any of the command-line options mentioned above can be specified in a
+configuration file instead. We first look for \(dqhtsnrc\(dq in the
+system configuration directory. We then look for a file named
+\(dq.htsnrc\(dq in the user's home directory. The latter will override
+the former.
+.P
+The user's home directory is simply $HOME on Unix; on Windows it's
+wherever %APPDATA% points. The system configuration directory is
+determined by Cabal; the \(dqsysconfdir\(dq parameter during the
+\(dqconfigure\(dq step is used.
+.P
+The file's syntax is given by examples in the htsnrc.example file
+(included with \fBhtsn\fR).
+.P
+Options specified on the command-line override those in either
+configuration file.
+
+.SH BUGS
+
+.P
+Send bugs to michael@orlitzky.com.
projects / dead / htsn.git / blobdiff