Add a preliminary man page.

diff --git a/doc/man1/htsn-import.1 b/doc/man1/htsn-import.1
index 0816be35d33cc5eb8a035dc551e40d7e05f1b44b..bd1909d142e5a6035e49ace7d8a1063f3802ba36 100644 (file)
--- a/doc/man1/htsn-import.1
+++ b/doc/man1/htsn-import.1
@@ -8,6 +8,56 @@ htsn-import \- Import XML files from The Sports Network into an RDBMS.
 \fBhtsn-import\fR [OPTIONS] [FILES]
 
 .SH DESCRIPTION
+.P
+The Sports Network <http://www.sportsnetwork.com/> offers an XML feed
+containing various sports news and statistics. Our sister program
+\fBhtsn\fR is capable of retrieving the feed and saving the individual
+XML documents contained therein. But what to do with them?
+.P
+The purpose of \fBhtsn-import\fR is to take these XML documents and
+get them into something we can use, a relational database management
+system (RDBMS), loosely known as a SQL database. The structure of
+relational database, is, well, relational, and the feed XML is not. So
+there is some work to do before the data can be inserted.
+.P
+First, we must parse the XML. Each supported document type (see below)
+has a full pickle/unpickle implementation (\(dqpickle\(dq is simply a
+synonym for serialize here). That means that we parse the entire
+document into a data structure, and if we pickle (serialize) that data
+structure, we get the exact same XML document tha we started with.
+.P
+This is important for two reasons. First, it serves as a second level
+of validation. The first validation is performed by the XML parser,
+but if that succeeds and unpicking fails, we know that something is
+fishy. Second, we don't ever want to be surprised by some new element
+or attribute showing up in the XML. The fact that we can unpickle the
+whole thing now means that we won't be surprised in the future.
+.P
+The aforementioned feature is especially important because we
+automatically migrate the database schema every time we import a
+document. If you attempt to import a \(dqnewsxml.dtd\(dq document, all
+database objects relating to the news will be created if they do not
+exist. We don't want the schema to change out from under us without
+warning, so it's important that no XML be parsed that would result in
+a different schema than we had previously. Since we can
+pickle/unpickle everything already, this should be impossible.
+
+.SH SUPPORTED DOCUMENT TYPES
+.P
+The XML document types obtained from the feed are uniquely identified
+by their DTDs. We currently support documents with the following DTDs:
+.IP \[bu] 2
+Heartbeat.dtd
+.IP \[bu]
+newsxml.dtd
+.IP \[bu]
+Injuries_Detail_XML.dtd
+.IP \[bu]
+injuriesxml.dtd
+.IP \[bu]
+Odds_XML.dtd
+.IP \[bu]
+weatherxml.dtd
 
 .SH DATABASE SCHEMA
 .P
@@ -31,3 +81,118 @@ Wherever possible, children are kept unique to prevent pointless
 duplication. This slows down inserts, and speeds up reads (which we
 assume are much more frequent). The current rate at which the feed
 transmits XML is much too slow to cause problems inserting.
+.P
+UML diagrams of the resulting database schema for each XML document
+type are provided with the \fBhtsn-import\fR documentation.
+.P
+In some cases the top-level table for a document type has been
+omitted. For example, all of the information in the the
+\(dqinjuriesxml\(dq documents is contained in \(dqlisting\(dq
+elements. We therefore omit the \(dqinjuries\(dq table and create only
+\(dqinjuries_listings\(dq.
+
+.SH OPTIONS
+
+.IP \fB\-\-backend\fR,\ \fB\-b\fR
+The RDBMS backend to use. Valid choices are \fISqlite\fR and
+\fIPostgres\fR. Capitalization is important, sorry.
+
+Default: Sqlite
+
+.IP \fB\-\-connection-string\fR,\ \fB\-c\fR
+The connection string used for connecting to the database backend
+given by the \fB\-\-baclend\fR option. The default is appropriate for
+the \fISqlite\fR backend.
+
+Default: \(dq:memory:\(dq
+
+.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\-\-remove\fR,\ \fB\-r\fR
+Remove successfully processed files. If you enable this, you can see
+at a glance which XML files are not being processed, because they're
+all that should be left.
+
+Default: disabled
+
+.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 CONFIGURATION FILE
+.P
+Any of the command-line options mentioned above can be specified in a
+configuration file instead. We first look for \(dqhtsn-importrc\(dq in
+the system configuration directory. We then look for a file named
+\(dq.htsn-importrc\(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 htsn-importrc.example file
+(included with \fBhtsn-import\fR).
+.P
+Options specified on the command-line override those in either
+configuration file.
+
+.SH EXAMPLES
+.IP \[bu] 2
+Import newsxml.xml into a preexisting sqlite database named \(dqfoo.sqlite3\(dq:
+
+.nf
+.I $ htsn-import --connection-string='foo.sqlite3' \\\\
+.I "              test/xml/newsxml.xml"
+Successfully imported test/xml/newsxml.xml.
+Imported 1 document(s) total.
+.fi
+.IP \[bu]
+Repeat the previous example, but delete newsxml.xml afterwards:
+
+.nf
+.I $ htsn-import --connection-string='foo.sqlite3' \\\\
+.I "              --remove test/xml/newsxml.xml"
+Successfully imported test/xml/newsxml.xml.
+Imported 1 document(s) total.
+Removed processed file test/xml/newsxml.xml.
+.fi
+.IP \[bu]
+Use a Postgres database instead of the default Sqlite. This assumes
+that you have a database named \(dqhtsn\(dq accessible to user
+\(dqpostgres\(dq locally:
+
+.nf
+.I $ htsn-import --connection-string='dbname=htsn user=postgres' \\\\
+.I "              --backend=Postgres test/xml/newsxml.xml"
+Successfully imported test/xml/newsxml.xml.
+Imported 1 document(s) total.
+.fi
+
+.SH BUGS
+
+.P
+Send bugs to michael@orlitzky.com.