From 0808a14f144067bd33654f4e78b9a68a442af5b8 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Sat, 26 Mar 2016 09:57:23 -0700 Subject: [PATCH] adding a section on minimal configuration --- README.rst | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 63 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index f6f1a4d..177b69f 100644 --- a/README.rst +++ b/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 `_ * `Source tree on GitHub `_ * `Output documentation tree (sample) `_