adding a section on minimal configuration

This commit is contained in:
Martin A. Brown 2016-03-26 09:57:23 -07:00
parent 199db5d91d
commit 0808a14f14
1 changed files with 63 additions and 3 deletions

View File

@ -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 \
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
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.
* `Canonical python-tldp repository <`_
* `Canonical python-tldp repository <>`_
* `Source tree on GitHub <>`_
* `Output documentation tree (sample) <>`_