Document the DEBUG log level.

[dead/htsn-import.git] / doc / man1 / htsn-import.1

diff --git a/doc/man1/htsn-import.1 b/doc/man1/htsn-import.1
index f1edf446f5b20b5a68dddf9722aec2006869c1dd..49a6927c4ef7c385f47c086fc1b9d6275170c165 100644 (file)
--- a/doc/man1/htsn-import.1
+++ b/doc/man1/htsn-import.1
@@ -48,16 +48,20 @@ pickle/unpickle everything already, this should be impossible.
 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
+Auto_Racing_Schedule_XML.dtd
 .IP \[bu]
-newsxml.dtd
+Heartbeat.dtd
 .IP \[bu]
 Injuries_Detail_XML.dtd
 .IP \[bu]
 injuriesxml.dtd
 .IP \[bu]
+newsxml.dtd
+.IP \[bu]
 Odds_XML.dtd
 .IP \[bu]
+scoresxml.dtd
+.IP \[bu]
 weatherxml.dtd
 
 .SH DATABASE SCHEMA
@@ -105,6 +109,30 @@ prevent duplication in this case anyway.
 UML diagrams of the resulting database schema for each XML document
 type are provided with the \fBhtsn-import\fR documentation.
 
+.SH XML Schema Oddities
+.P
+There are a number of problems with the XML on the wire. Even if we
+construct the DTDs ourselves, the results are sometimes
+inconsistent. Here we document a few of them.
+
+.IP \[bu]
+2 Odds_XML.dtd
+
+The <Notes> elements here are supposed to be associated with a set of
+<Game> elements, but since the pair
+(<Notes>...</Notes><Game>...</Game>) can appear zero or more times,
+this leads to ambiguity in parsing. We therefore ignore the notes
+entirely (although a hack is employed to facilitate parsing).
+
+.IP \[bu]
+weatherxml.dtd
+
+There appear to be two types of weather documents; the first has
+<listing> contained within <forecast> and the second has <forecast>
+contained within <listing>. While it would be possible to parse both,
+it would greatly complicate things. The first form is more common, so
+that's all we support for now.
+
 .SH OPTIONS
 
 .IP \fB\-\-backend\fR,\ \fB\-b\fR
@@ -128,10 +156,11 @@ 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
+How verbose should the logs be? We log notifications at four levels:
+DEBUG, 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.
+interesting notifications will be logged as well. The debug output is
+extremely verbose and will not be written to syslog even if you try.
 
 Default: INFO