add some explanatory text and full option set

add explanatory text and a full set of options for all of the section
fragments of the ldptool.ini

etc/ldptool.ini

@@ -1,18 +1,112 @@
-[ldptool]
-# sourcedir = /path/to/checkout/of/LDP/LDP/faq/linuxdoc/,
-#             /path/to/checkout/of/LDP/LDP/guide/linuxdoc/,
-#             /path/to/checkout/of/LDP/LDP/howto/linuxdoc/,
-#             /path/to/checkout/of/LDP/LDP/howto/docbook/,
-#             /path/to/checkout/of/LDP/LDP/guide/docbook/,
-#             /path/to/checkout/of/LDP/LDP/ref/docbook/,
-#             /path/to/checkout/of/LDP/LDP/faq/docbook/
+# -- System Wide configuration file for the ldptool, a command-line utility
+#    for building DocBook XML, DocBook SGML and Linuxdoc (SGML) documents into
+#    a variety of output formats.
+#
+[ldptool]
+
+# -- source dir is a comma-separated list of directories containing LDP
+#    documents; a document is either a plain file of a supported document type
+#    or a directory containing a file of a supported document type.
+#
+#    For example, in a sourcedir, the following will be detected and
+#    classified as source documents.  Note, in particular, that, in the naming
+#    convention, the file stem must match the directory base name:
+#
+#      Frobnitz-HOWTO.sgml
+#      Wascally-Wabbit-HOWTO/Wascally-Wabbit-HOWTO.xml
+#
+sourcedir = /path/to/checkout/LDP/LDP/faq/linuxdoc/,
+	/path/to/checkout/LDP/LDP/guide/linuxdoc/,
+	/path/to/checkout/LDP/LDP/howto/linuxdoc/,
+	/path/to/checkout/LDP/LDP/howto/docbook/,
+	/path/to/checkout/LDP/LDP/guide/docbook/,
+	/path/to/checkout/LDP/LDP/ref/docbook/,
+	/path/to/checkout/LDP/LDP/faq/docbook/
+
+# -- the pubdir is the location where the output directories will be found
+#    and/or created; this is the publication directory
+#
+pubdir = /path/to/publication/directory/
+
+# -- if you need to skip a particular (problematic?) document during build
+#    the skip option is available; this parameter holds comma-separated
+#    document STEM names
+#
+skip = 
+
+# -- the ldptool utility can be very chatty, if you wish; loglevel accepts the
+#    standard set of Python loglevel identifiers (or numeric values), e.g.
+#
+# loglevel = DEBUG
+# loglevel = INFO
+# loglevel = WARNING
+# loglevel = ERROR
+# loglevel = CRITICAL
+#
+# -- the default loglevel is ERROR (40); setting the loglevel as low as INFO
+#    (20) will produce only a moderate amount of output, and is probably
+#    suitable for automated processing; setting the loglevel to DEBUG will
+#    generate quite a bit of logging
+#
+loglevel = ERROR
+
+# -- Used only by the 'detail' command-line, you can get more verbose
+#    descriptions of the source and output documents by throwing the verbose
+#    flag
+#
+verbose = False
+
+# -- the four main actions, probably ought not to be set in the config file
+#
+# detail = False
+# summary = False
+# script = False
+# build = False
+
+# -- Each of the document types may require different executables and/or data
+#    files to support processing of a specific document type.  The below
+#    configuration file section fragments allow each document type processor
+#    to keep its own configurables separate from other document processors.
+#
+# -- The ldptool code uses $PATH (from the environment) to locate the
+#    executables, by default.  If the utilities are not installed in the
+#    system path, then it is possible to configure the full path to each
+#    executable, here, in this system-wide configuration file.
+#
+# -- Also, the data files, for example, the DocBook DSSSL and DocBook XSL
+#    stylesheets may be in a location that ldptool cannot find.  If so, it
+#    will skip building any document type if it is lacking the appropriate
+#    data files.  It is possible to configure the full path to the data files
+#    here, in this system-wide configuration file.
 #
-# pubdir = /home/mabrown/tmp/en/
 
 [ldptool-docbook4xml]
-# xslchunk = /path/to/checkout/of/LDP/LDP/builder/xsl/ldp-html-chunk.xsl
-# xslprint = /path/to/checkout/of/LDP/LDP/builder/xsl/ldp-print.xsl
-# xslsingle = /path/to/checkout/of/LDP/LDP/builder/xsl/ldp-html.xsl
+# xslchunk = 
+# fop = /usr/bin/fop
+# dblatex = /usr/bin/dblatex
+# xsltproc = /usr/bin/xsltproc
+# html2text = /usr/bin/html2text
+# xslprint = 
+# xslsingle = 
+
+[ldptool-linuxdoc]
+# sgml2html = /usr/bin/sgml2html
+# htmldoc = /usr/bin/htmldoc
+# html2text = /usr/bin/html2text
 
 [ldptool-docbooksgml]
-# ldpdsl = /path/to/checkout/of/LDP/LDP/builder/dsssl/ldp.dsl
+# ldpdsl = 
+# jw = /usr/bin/jw
+# dblatex = /usr/bin/dblatex
+# html2text = /usr/bin/html2text
+# collateindex = /home/mabrown/bin/collateindex.pl
+# docbookdsl = /usr/share/sgml/docbook/dsssl-stylesheets/html/docbook.dsl
+# openjade = /usr/bin/openjade
+
+[ldptool-docbook5xml]
+# xsltproc = /usr/bin/xsltproc
+# dblatex = /usr/bin/dblatex
+# fop = /usr/bin/fop
+# html2text = /usr/bin/html2text
+
+# -- end of file