Move the deployment section from README.development to the man page.

Remove another entry from the TODO.

diff --git a/doc/README.development b/doc/README.development
index b1df69861650a579959fa32b576590d00e978627..e58b418edf67adc2f755e98cff7e9586f87b97c6 100644 (file)
--- a/doc/README.development
+++ b/doc/README.development
@@ -27,23 +27,3 @@ If there's an error, you'll see something like the following:
   contents:   <Title>IRL - Firestone 600 - Final Results</Title><Track_Location>
   Texas Motor Sp...
   []
   contents:   <Title>IRL - Firestone 600 - Final Results</Title><Track_Location>
   Texas Motor Sp...
   []

-
-
-== Creating the Database Schema (Deployment) ==
-
-When deploying for the first time, the target database will most
-likely be empty. The schema will be migrated when a new document type
-is seen, but this has a downside: it can be months before every
-supported document type has been seen once. This can make it difficult
-to test the database permissions.
-
-Since all of the test XML documents have old timestamps, one easy
-workaround is the following: simply import all of the test XML
-documents, and then delete them. This will force the migration of the
-schema, after which you can set and test the database permissions.
-
-Something as simple as,
-
-  $ find ./test/xml -iname '*.xml' | xargs htsn-import -c foo.sqlite
-
-should do it.

diff --git a/doc/TODO b/doc/TODO
index fefb5dac9215c7c3f40ee2fbdc02ee96150a7d52..9b065db26c98ed4480bd08c0ddf844752c100363 100644 (file)
--- a/doc/TODO
+++ b/doc/TODO
@@ -65,14 +65,5 @@
    * WNBA_Individual_Stats_XML
    * WNBATeamScheduleXML
 
    * WNBA_Individual_Stats_XML
    * WNBATeamScheduleXML
 

-6. Add a note about the NULL vs. empty string policy in the man page.
-
-7. Create an XmlImportFkTeams class and use it for JFile, Odds, and
-   ScheduleChanges.
-
-8. Consolidate all of the make_game_time functions.
-
-9. Document how to get an empty database set up (import test xml then
-   delete).
-
-10. Add/update dbschema diagrams for JFile, Odds, and ScheduleChanges.
+6. Consolidate all of the make_game_time functions which take a
+   date/time and produce a combined time.

diff --git a/doc/man1/htsn-import.1 b/doc/man1/htsn-import.1
index 352eb2b6ab66048f400f97521b580f082c75794e..7a215b142c420e2931045a895daa1d3ebba974c6 100644 (file)
--- a/doc/man1/htsn-import.1
+++ b/doc/man1/htsn-import.1
@@ -106,6 +106,29 @@ type are provided with the \fBhtsn-import\fR documentation, in the
 should be considered a bug if they are incorrect. The diagrams are
 created using the pgModeler <http://www.pgmodeler.com.br/> tool.
 
 should be considered a bug if they are incorrect. The diagrams are
 created using the pgModeler <http://www.pgmodeler.com.br/> tool.
 

+.SH NULL POLICY
+.P
+Normally in a database one makes a distinction between fields that
+simply don't exist, and those fields that are
+\(dqempty\(dq. Translating from XML, there is a natural way to
+determine which one should be used: if an element is present in the
+XML document but its contents are empty, then an empty string should
+be inserted into the corresponding field. If on the other hand the
+element is missing entirely, the corresponding database entry should
+be NULL to indicate that fact.
+.P
+This sounds well and good, but the XML must be consistent for the
+database consumer to make any sense of what he sees. The feed XML uses
+optional and blank elements interchangeably, and without any
+discernable pattern. To propagate this pattern into the database would
+only cause confusion.
+.P
+As a result, a policy was adopted: both optional elements and elements
+whose contents can be empty will be considered nullable in the
+database. If the element is missing, the corresponding field is
+NULL. Likewise if the content is simply missing. That means there
+should never be a (completely) empty string in a database column.
+

 .SH XML SCHEMA GENERATION
 .P
 In order to parse XML, you need to know the structure of your
 .SH XML SCHEMA GENERATION
 .P
 In order to parse XML, you need to know the structure of your


@@ -264,6 +287,28 @@ it would greatly complicate things. The first form is more common, so
 that's all we support for now. An example is provided as
 schemagen/weatherxml/20143655.xml.
 
 that's all we support for now. An example is provided as
 schemagen/weatherxml/20143655.xml.
 

+.SH DEPLOYMENT
+.P
+When deploying for the first time, the target database will most
+likely be empty. The schema will be migrated when a new document type
+is seen, but this has a downside: it can be months before every
+supported document type has been seen once. This can make it difficult
+to test the database permissions.
+.P
+Since all of the test XML documents have old timestamps, one easy
+workaround is the following: simply import all of the test XML
+documents, and then delete them using whatever script is used to prune
+old entries. This will force the migration of the schema, after which
+you can set and test the database permissions.
+.P
+Something as simple as,
+.P
+.nf
+.I $ find ./test/xml -iname '*.xml' | xargs htsn-import -c foo.sqlite
+.fi
+.P
+should do it.
+

 .SH OPTIONS
 
 .IP \fB\-\-backend\fR,\ \fB\-b\fR
 .SH OPTIONS
 
 .IP \fB\-\-backend\fR,\ \fB\-b\fR