adding a section on minimal configuration

README.rst

@@ -45,8 +45,10 @@ Supported input formats are:
 - Docbook XML 5.x (basic support, as of 2016-03-10)
 
 
-Example usages:
----------------
+Example usages
+--------------
+If your attempts to run the below commands don't work or generate errors, see
+also `Minimal configuration`_.
 
 Here are some example usages against a live checkout of the LDP source
 repository and a local cache of the output tree:
@@ -218,6 +220,64 @@ above two documents:::
     ... and more ...
 
 
+Minimal configuration
+---------------------
+The most important configuration parameters that `ldptool` takes are the set
+of source directories (in which to find documents) and the output directory,
+in which to create the resulting outputs.  It will not be able to run unless
+it has at least one --sourcedir and an existing --pubdir directory.
+
+If you have an LDP checkout in your home directory, here's an example which
+would process all of the Linuxdoc HOWTO docs:::
+
+  mkdir LDP-output-tree
+  ldptool --sourcedir $HOME/LDP/LDP/howto/linuxdoc --pubdir LDP-output-tree
+
+If you would like to create a sample configuration file for use later (or for
+copying into the system location, `/etc/ldptool/ldptool.ini`, you can generate
+your own config file as follows:::
+
+  ldptool > sample-ldptool.cfg \
+          --sourcedir $HOME/LDP/LDP/faq/linuxdoc/ \
+          --sourcedir $HOME/LDP/LDP/guide/linuxdoc/ \
+          --sourcedir $HOME/LDP/LDP/howto/linuxdoc/ \
+          --sourcedir $HOME/LDP/LDP/howto/docbook/ \
+          --sourcedir $HOME/LDP/LDP/guide/docbook/ \
+          --sourcedir $HOME/LDP/LDP/ref/docbook/ \
+          --sourcedir $HOME/LDP/LDP/faq/docbook/ \
+          --pubdir $HOME/LDP-output/ \
+          --loglevel info \
+          --dump-cfg
+
+Then, you can run the same configuration again with:::
+
+  ldptool --configfile sample-ldptool.cfg
+
+The `ldptool` program tries to locate all of the tools it needs to process
+documents.  Each source format requires a certain set of tools, for example, to
+process DocBook 4.x XML, `ldptool` needs the executables xmllint, xstlproc,
+html2text, fop and dblatex.  It also requires the XSL files for generating FO,
+chunked HTML and single-page HTML.  All of the items are configurable on the
+command-line or in the configuration file, but here's a sample config file
+stanza:::
+
+  [ldptool-docbook4xml]
+  xslchunk = /usr/share/xml/docbook/stylesheet/ldp/html/tldp-sections.xsl
+  xslsingle = /usr/share/xml/docbook/stylesheet/ldp/html/tldp-one-page.xsl
+  fop = /usr/bin/fop
+  dblatex = /usr/bin/dblatex
+  xsltproc = /usr/bin/xsltproc
+  html2text = /usr/bin/html2text
+  xslprint = /usr/share/xml/docbook/stylesheet/ldp/fo/tldp-print.xsl
+  xmllint = /usr/bin/xmllint
+
+The above stanza was generated by running `ldptool --dump-cfg` on an Ubuntu
+14.04 system which had all of the software dependencies installed.  If your
+distribution does not supply ldp-docbook-xsl, for example, you would need to
+fetch those files, put them someplace in the filesystem and adjust your
+configuration file or command-line invocations accordingly.
+
+
 Software dependencies
 ---------------------
 There are a large number of packages listed here in the dependency set.  This
@@ -311,6 +371,6 @@ try that, please let me know any problems you encounter.
 Links
 -----
 
-* `Canonical python-tldp repository <https://github.com/tLDP/python-tldp`_
+* `Canonical python-tldp repository <https://github.com/tLDP/python-tldp>`_
 * `Source tree on GitHub <https://github.com/tLDP/LDP>`_
 * `Output documentation tree (sample) <http://www.tldp.org/>`_