NAME¶

ldptool - DocBook, Linuxdoc and Asciidoc build/publishing tool.

SYNOPSIS¶

ldptool [options] [pathname [...]]

DESCRIPTION¶

ldptool creates chunked HTML, single-page HTML, PDF and plain text outputs for each source document it is passed as a pathname. See Source document discovery.

If it is not passed any arguments, ldptool will collect all of the directories specified with the --sourcedir option and scan through these directories looking for valid source documents.

The action taken depends on the options passed to the utility. If no options are passed, then the default --build action will be attempted. The options controlling the overall program are described in the sections Action options and Main options. All other options are relegated to the tail of the manpage, because they are merely configurables for individual document processors.

The ldptool can:

ACTION OPTIONS¶

MAIN OPTIONS¶

SOURCE DOCUMENT DISCOVERY¶

Almost all documentation formats provide the possibility that a document can span multiple files. Although more than half of the LDP document collection consists of single-file HOWTO contributions, there are a number of documents that are composed of dozens, even hundreds of files. In order to accommodate both the simple documents and these much more complex documents, LDP adopted a simple (unoriginal) naming strategy to allow a single document to span multiple files:

Each document is referred to by a stem, which is the filename without any
extension.  A single file document is simple STEM.EXT.  A document that
requires many files must be contained in a directory with the STEM name.
Therefore, the primary source document will always be called either STEM.EXT
or STEM/STEM.EXT.

(If there is a STEM/STEM.xml and STEM/STEM.sgml in the same directory, that is an error, and ldptool will freak out and shoot pigeons.)

During document discovery, ldptool will walk through all of the source directories specified with --sourcedir and build a complete list of all identifiable source documents. Then, it will walk through the publication directory --pubdir and match up each output directory (by its STEM) with the corresponding STEM found in one of the source directories.

Then, ldptool can then determine whether any source files are newer. It uses content-hashing, i.e. MD5, and if a source file is newer, the status is stale. If there is no matching output, the source file is new. If there's an output with no source, that is in orphan. See the --statustypes output for the full list of STATUS types.

EXAMPLES¶

To build and publish a single document:

$ ldptool --publish DocBook-Demystification-HOWTO
$ ldptool --publish ~/vcs/LDP/LDP/howto/docbook/Valgrind-HOWTO.xml

To build and publish anything that is new or updated work:

$ ldptool --publish
$ ldptool --publish work

To (re-)build and publish everything, regardless of state:

$ ldptool --publish all

To generate a specific output (into a --builddir):

$ ldptool --build DocBook-Demystification-HOWTO

To generate all outputs into a --builddir (should exist):

$ ldptool --builddir ~/tmp/scratch-directory/ --build all

To build new/updated work, but pass over a trouble-maker:

$ ldptool --build --skip HOWTO-INDEX

To loudly generate all outputs, except a trouble-maker:

$ ldptool --build all --loglevel debug --skip HOWTO-INDEX

To print out a shell script for building a specific document:

$ ldptool --script TransparentProxy
$ ldptool --script ~/vcs/LDP/LDP/howto/docbook/Assembly-HOWTO.xml

ENVIRONMENT¶

The ldptool accepts configuration via environment variables. All such environment variables are prefixed with the name LDPTOOL_.

The name of each variable is constructed from the primary command-line option name. The -b is better known as --builddir, so the environment variable would be LDPTOOL_BUILDDIR. Similarly, the environment variable names for each of the handlers can be derived from the name of the handler and its option. For example, the Asciidoc processor needs to have access to the xmllint and asciidoc utilities.

The environment variable corresponding to the CLI option --asciidoc-xmllint would be LDPTOOL_ASCIIDOC_XMLLINT. Similarly, --asciidoc-asciidoc should be LDPTOOL_ASCIIDOC_ASCIIDOC.

Variables accepting multiple options use the comma as a separator:

LDPTOOL_RESOURCES=images,resources

The complete listing of possible environment variables with all current values can be printed by using ldptool --dump-env.

CONFIGURATION FILE¶

The system-installed configuration file is /etc/ldptool/ldptool.ini. The format is a simple INI-style configuration file with a block for the main program and a block for each handler. Here's a partial example:

[ldptool]
resources = images,


        resources
loglevel = 40
[ldptool-asciidoc]
asciidoc = /usr/bin/asciidoc
xmllint = /usr/bin/xmllint

Note that the comma separates multiple values for a single option (resources) in the above config fragment.

The complete, current configuration file can be printed by using ldptool --dump-cfg.

CONFIGURATION OPTION FRAGMENTS FOR EACH DOCTYPE HANDLER¶

Every source format has a single handler and each DOCTYPE handler may require a different set of executables and/or data files to complete its job. The defaults depend on the platform and are detected at runtime. In most cases, the commands are found in /usr/bin (see below). The data files, for example the LDP XSL files and the docbook.rng, may live in different places on different systems.

If a given DOCTYPE handler cannot find all of its requirements, it will complain to STDERR during execution, but will not abort the rest of the run.

If, for some reason, ldptool cannot find data files, but you know where they are, consider generating a configuration file with the --dump-cfg option, adjusting the relevant options and then passing the --configfile your.ini to specify these paths.

ASCIIDOC¶

N.B. The Asciidoc processor simply converts the source document to a Docbook4XML document and then uses the richer Docbook4XML toolchain.

DOCBOOK4XML¶

DOCBOOK5XML¶

DOCBOOKSGML¶

LINUXDOC¶

AUTHOR¶

Martin A. Brown <martin@linux-ip.net>

COPYRIGHT¶

Manual page (C) 2016, Linux Documentation Project