doc/man1/htsn.1

   1 .TH htsn 1
   2
   3 .SH NAME
   4 htsn \- Parse XML files from The Sports Network feed.
   5
   6 .SH SYNOPSIS
   7
   8 \fBhtsn\fR [OPTIONS] [HOSTNAMES]
   9
  10 .SH DESCRIPTION
  11 .P
  12 The Sports Network <http://www.sportsnetwork.com/> offers an XML feed
  13 containing various sports news and statistics. The goal of \fBhtsn\fR
  14 is to watch the XML feed and parse the individual XML documents into
  15 files.
  16 .P
  17 Once started, we will choose an XML feed host to connect to. The
  18 choice is made from a list in a round-robin fashion, and by default,
  19 the list contains all known TSN feed hosts. Once we have a connection,
  20 your username and password are sent. If they are accepted, we begin to
  21 parse the feed saving all XML files to the configured output directory
  22 (see \fI\-\-output\-directory\fR).
  23 .P
  24 If we encounter an error (say, the connection is dropped), then we
  25 will attempt to connect to the next host in the list after waiting
  26 five seconds. This process continues indefinitely.
  27 .P
  28 The program can run either interactively (that is, outputting to the
  29 console), or as a daemon with the \fI\-\-daemonize\fR flag.
  30
  31 .SH INPUT
  32 .P
  33 The program takes no input; a username and password must be supplied
  34 on the command-line or in a configuration file.
  35
  36 .SH OUTPUT
  37 .P
  38 Output is not generated when running as a daemon; otherwise, standard
  39 out and standard error are fairly noisy. All traffic between htsn and
  40 the feed server is displayed on stdout. Status messages are
  41 interspersed when they are generated with warnings and errors going to
  42 stderr. The following can be expected:
  43 .IP \[bu] 2
  44 The only data we send to the feed are the username and password. These
  45 will be highlighted in green on stdout.
  46 .IP \[bu]
  47 All data received from the feed will be echoed in the default color to
  48 stdout.
  49 .IP \[bu]
  50 Informational messages will be highlighted in cyan and sent to stdout.
  51 .IP \[bu]
  52 Warnings will be highlighted in yellow and sent to stderr.
  53 .IP \[bu]
  54 Errors will be highlighted in red and sent to stderr.
  55
  56 .SH LOGGING
  57 .P
  58 Logging is done either to syslog or a file. The destination and
  59 verbosity are controlled by the \fI\-\-log\-file\fR,
  60 \fI\-\-log\-level\fR, and \fI\-\-syslog\fR parameters which may be
  61 specified either on the command line or in the configuration file.
  62
  63 .SH OPTIONS
  64
  65 .IP \fB\-\-daemonize\fR,\ \fB\-d\fR
  66 Run as a daemon, in the background. When running as a daemon the
  67 \fI\-\-pidfile\fR, \fI\-\-run\-as\-group\fR, and
  68 \fI\-\-run\-as\-user\fR flags become relevant.
  69
  70 Default: disabled
  71
  72 .IP \fB\-\-log-file\fR
  73 If you specify a file here, logs will be written to it (possibly in
  74 addition to syslog). Can be either a relative or absolute path. It
  75 will not be auto-rotated; use something like logrotate for that.
  76
  77 Default: none
  78
  79 .IP \fB\-\-log-level\fR
  80 How verbose should the logs be? We log notifications at four levels:
  81 DEBUG, INFO, WARN, and ERROR. Specify the \(dqmost boring\(dq level of
  82 notifications you would like to receive (in all-caps); more
  83 interesting notifications will be logged as well. The debug output is
  84 extremely verbose and will not be written to syslog even if you try.
  85
  86 Default: INFO
  87
  88 .IP \fB\-\-output\-directory\fR,\ \fB\-o\fR
  89 To which directory should we write the XML files?
  90
  91 Default: .
  92
  93 .IP \fB\-\-password\fR
  94 The password associated with your TSN username. A password is
  95 required, so you must supply one either on the command line or in a
  96 configuration file.
  97
  98 Default: none
  99
 100 .IP \fB\-\-pidfile\fR
 101 (Daemon mode only) Create a PID file in the given location. This is
 102 used by the init system on Unix to keep track of the running daemon.
 103
 104 If necessary, its parent directory will be created with owner/group
 105 set to the appropriate user/group, but at most one directory will be
 106 created (that is, we won't create an entire directory tree).
 107
 108 Default: /run/htsn/htsn.pid
 109
 110 .IP \fB\-\-run\-as\-group\fR
 111 (Daemon mode only) Run as the given system group. The PID file is
 112 written before privileges are dropped, so the only privileges needed
 113 by htsn are those necessary to write the XML files and (optionally)
 114 the log file.
 115
 116 Default: the current group
 117
 118 .IP \fB\-\-run\-as\-user\fR
 119 (Daemon mode only) Run as the given system user. The PID file is
 120 written before privileges are dropped, so the only privileges needed
 121 by htsn are those necessary to write the XML files and (optionally)
 122 the log file.
 123
 124 Default: the current user
 125
 126 .IP \fB\-\-syslog\fR,\ \fB\-s\fR
 127 Enable logging to syslog. On Windows this will attempt to communicate
 128 (over UDP) with a syslog daemon on localhost, which will most likely
 129 not work.
 130
 131 Default: disabled
 132
 133 .IP \fB\-\-username\fR,\ \fB\-u\fR
 134 Your TSN username. A username is required, so you must supply one
 135 either on the command line or in a configuration file.
 136
 137 Default: none
 138
 139 .SH FEED HOSTS
 140 .P
 141 It is possible to pass a list of feed hostnames on the command-line
 142 (see [HOSTNAMES] in the synopsis). By default \fBhtsn\fR will attempt
 143 to connect to every known TSN XML feed host in a round-robin fashion,
 144 so there is rarely a need to do this.
 145
 146 .SH CONFIGURATION FILE
 147 .P
 148 Any of the command-line options mentioned above can be specified in a
 149 configuration file instead. We first look for \(dqhtsnrc\(dq in the
 150 system configuration directory. We then look for a file named
 151 \(dq.htsnrc\(dq in the user's home directory. The latter will override
 152 the former.
 153 .P
 154 The user's home directory is simply $HOME on Unix; on Windows it's
 155 wherever %APPDATA% points. The system configuration directory is
 156 determined by Cabal; the \(dqsysconfdir\(dq parameter during the
 157 \(dqconfigure\(dq step is used.
 158 .P
 159 The file's syntax is given by examples in the htsnrc.example file
 160 (included with \fBhtsn\fR).
 161 .P
 162 Options specified on the command-line override those in either
 163 configuration file.
 164
 165 .SH BUGS
 166
 167 .P
 168 Send bugs to michael@orlitzky.com.