X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=doc%2Fman1%2Fhtsn.1;h=43858c6b53a8edd5f0eac629e22e07ccb6da7da2;hb=b13f4b597ff3055026722adc5661566b1aa8b3ed;hp=7d4db34fcb7603a751251ec0cd486ee3a110550b;hpb=0b964afe4e7dd1ed45e0bc76a4dce760513b1fe0;p=dead%2Fhtsn.git diff --git a/doc/man1/htsn.1 b/doc/man1/htsn.1 index 7d4db34..43858c6 100644 --- a/doc/man1/htsn.1 +++ b/doc/man1/htsn.1 @@ -5,41 +5,163 @@ htsn \- Parse XML files from The Sports Network feed. .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 offers an XML feed -containing various sports news and statistics. +The Sports Network 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 +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 + +.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. + +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). + +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 -There are three \(dqoutput streams\(dq: - -.nr step 1 1 -.IP \n[step] 2 -\fIStandard output/error\fR. If the log level is set to DEBUG, all -data received from the feed will be output to standard out in the -default color. This is the default. - -Data sent to the remote host (i.e. your username and password) will be -highlighted in green at all log levels. Informational (status) -messages will be displayed in blue at log levels greater than -INFO. Warnings and errors will displayed in red at log levels greater -than WARNING and ERROR respectively. -.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, 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 by default to syslog (on Unix) or the event log (on Windows). +Send bugs to michael@orlitzky.com.