From 4e53c500d87df2dbe1413d47562786fe4cc88f2a Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Sun, 22 Dec 2013 17:47:00 -0500 Subject: [PATCH] Update the man page to reflect current reality. --- doc/htsnrc.example | 2 +- doc/man1/htsn.1 | 101 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 79 insertions(+), 24 deletions(-) diff --git a/doc/htsnrc.example b/doc/htsnrc.example index 8af5398..2158504 100644 --- a/doc/htsnrc.example +++ b/doc/htsnrc.example @@ -50,7 +50,7 @@ # absolute path. It will not be auto-rotated; use something like # logrotate for that. # -# Default: empty +# Default: none # # log_file = /var/log/htsn/htsn.log diff --git a/doc/man1/htsn.1 b/doc/man1/htsn.1 index 7d4db34..ed2d0db 100644 --- a/doc/man1/htsn.1 +++ b/doc/man1/htsn.1 @@ -5,13 +5,15 @@ 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. +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. .SH INPUT @@ -22,24 +24,77 @@ on the command-line or in a configuration file. .SH OUTPUT .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). +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. +.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 + +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. + +.SH OPTIONS + +.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 log 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\-\-password\fR,\ \fB\-p\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? + +Default: . + +.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\-\-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 + +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 BUGS + +.P +Send bugs to michael@orlitzky.com. -- 2.44.2