From 9602e331747a91b9ea1e37263972a2af5bfbb102 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Mon, 23 Dec 2013 16:11:03 -0500 Subject: [PATCH] Add more cabal description. List the non-Main modules we use. --- htsn.cabal | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 174 insertions(+), 4 deletions(-) diff --git a/htsn.cabal b/htsn.cabal index 74a789f..3aeab95 100644 --- a/htsn.cabal +++ b/htsn.cabal @@ -8,10 +8,16 @@ license: GPL-3 license-file: doc/LICENSE build-type: Simple extra-source-files: - doc/man1/htsn.1 + doc/man1/htsn.1 test/xml/*.xml synopsis: Parse XML files from The Sports Network feed. description: + /Usage/: + . + @ + htsn [OPTIONS] [HOSTNAMES] + @ + . The Sports Network offers an XML feed containing various sports news and statistics. The goal of /htsn/ is to watch the XML feed and parse the individual XML documents into @@ -21,16 +27,169 @@ description: 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. + parse the feed saving all XML files to the configured output directory + (see @--output-directory@). . 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. . The program can run either interactively (that is, outputting to the - console), or as a daemon. + console), or as a daemon with the @--daemonize@ flag. + . + /Input/: + . + The program takes no input; a username and password must be supplied + on the command-line or in a configuration file. + . + /Output/: + . + 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: + . + * The only data we send to the feed are the username and password. + These will be highlighted in green on stdout. + . + * All data received from the feed will be echoed in the default color + to stdout. + . + * Informational messages will be highlighted in cyan and sent to stdout. + . + * Warnings will be highlighted in yellow and sent to stderr. + . + * Errors will be highlighted in red and sent to stderr. + . + /Logging/: + . + Logging is done either to syslog or a file. The destination and + verbosity are controlled by the @--log-file@, @--log-level@, + and @--syslog@ parameters which may be specified either on the command + line or in the configuration file. + . + /Options/: + . + @ + \--daemonize, -d + @ + . + Run as a daemon, in the background. When running as a daemon the + \--pidfile, --run-as-group, and --run-as-user flags become relevant. + . + Default: disabled + . + @ + \--log-file + @ + . + 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 + . + @ + \--log-level + @ + . + How verbose should the logs be? We log notifications at three levels: + INFO, WARN, and ERROR. Specify the "most boring" level of + notifications you would like to receive (in all-caps); more + interesting notifications will be logged as well. + . + Default: INFO + . + @ + \--output-directory, -o + @ + . + To which directory should we write the XML files? + . + Default: . . - /Full documentation can be found in the included man page./ + @ + \--password + @ + . + 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 + . + @ + \--pidfile + @ + . + (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 + . + @ + \--run-as-group + @ + . + (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 + . + @ + \--run-as-user + @ + . + (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 + . + @ + \--syslog, -s + @ + . + 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 + . + @ + \--username, -u + @ + . + Your TSN username. A username is required, so you must supply one + either on the command line or in a configuration file. + . + Default: none + . + /Feed Hosts/: + . + It is possible to pass a list of feed hostnames on the command-line + (see [HOSTNAMES] in the synopsis). By default /htsn/ 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. + . + /Configuration File/: + . + Any of the command-line options mentioned above can be specified in a + configuration file instead. We look for a file named ".htsnrc" + in the user's home directory; its syntax is given by examples in the + htsnrc.example file (included with /htsn/). + . + If you are using the @--run-as-user@ option, that means that + the configuration file will need to go in that user's home directory + (and not, for example, root's). + . + Options specified on the command-line override those in the + configuration file. + executable htsn build-depends: @@ -56,6 +215,17 @@ executable htsn hs-source-dirs: src/ + other-modules: + CommandLine + Configuration + ExitCodes + Logging + OptionalConfiguration + Terminal + TSN.FeedHosts + TSN.Xml + Unix + ghc-options: -Wall -fwarn-hi-shadowing -- 2.44.2