Provided by: python3-tldp_0.7.13-1ubuntu1_all 
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:
• generate an inventory from multiple source directories (--sourcedir)
• crawl through a single output collection (--pubdir)
• match the sources to the outputs (based on document stem name)
• describe the collection by type and status (--summary)
• list out individual document type and status (--list)
• describe supported source formats (--formats)
• describe the meaning of document status (--statustypes)
• build the expected (non-configurable) set of outputs (--build)
• build and publish the outputs (--publish)
• produce runnable shell script to STDOUT (--script)
• generate configuration files that it can then take as input
ACTION OPTIONS
-h, --help
show a help message and exit
-b, --build
Build LDP documentation into the --builddir and exit. This is the default action
if no other action is specified.
-p, --publish
Build LDP documentation into the --builddir. If all builds are successful, then
copy the result for each source document into the --pubdir, effectively replacing
(and deleting) the older documents; finally, remove --builddir, if empty.
-S, --script
Print a runnable bash script to STDOUT. This will produce a shell script showing
what would be executed upon --build.
-l, --detail, --list
Examine the various SOURCEDIRs and the PUBDIR and generate a report showing the
FORMAT of the source document and STATUS of the document. Add the --verbose flag
for more information.
-t, --summary
Examine the various SOURCEDIRs and the PUBDIR and generate a short report
summarizing documents by STATUS and by DOCTYPE. Add the --verbose flag for more
information.
-T, --doctypes, --formats, --format, --list-doctypes, --list-formats
List the supported DOCTYPEs; there is one processor for each DOCTYPE.
--statustypes, --list-statustypes
List the possible document STATUS types. There are only seven basic status types,
but several synonyms and groups of STATUS types (internally called 'classes').
MAIN OPTIONS
-s, --sourcedir, --source-dir, --source-directory SOURCEDIR (default: None)
Specify the name of a SOURCEDIR which contains source documents. See also Source
document discovery.
The --sourcedir option may be used more than once.
-o, --pubdir, --output, --outputdir, --outdir PUBDIR (default: None)
Specify the the name of a PUBDIR. Used as the publication if the build succeeds.
When --publish is used with --pubdir, the output of a successful document build
will be used to replace any existing document output directory in PUBDIR.
-d, --builddir, --build-dir, --build-directory BUILDDIR (default: 'ldptool-build')
Specify the name of a BUILDDIR. A scratch directory used to build each source
document; directory is temporary and will be removed if the build succeeds AND
--publish has been requested. Under the --build action, all output directories and
contents remain in the BUILDDIR for inspection.
--verbose [True | False] (default: False)
Provide more information in --list and --detail actions. The option can be thrown
without an argument which is equivalent to True. To allow the CLI to supersede
environment or configuration file values, --verbose false is also supported.
--skip [STEM | DOCTYPE | STATUS]
Specify a source document name, document type or document status to skip during
processing. Each document is known by its STEM (see also Source document
discovery), its document DOCTYPE (see list below), and by the document STATUS (see
list below).
The --skip option may be used more than once.
DOCTYPE can be one of:
Asciidoc, Docbook4XML, Docbook5XML, DocbookSGML, or Linuxdoc (See also
output of --doctypes)
STATUS can be one of:
source, sources, output, outputs, published, stale, broken, new orphan,
orphans, orphaned, problems, work, all (See also output of --statustypes)
--resources RESOURCEDIR (default: ['images', 'resources'])
Some source documents provide images, scripts and other content. These files are
usually stored in a directory such as ./images/ that need to be copied intact into
the output directory. Adjust the set of resource directories wyth this option.
The --resources option may be used more than once.
--loglevel LOGLEVEL (default: ERROR)
set the loglevel to LOGLEVEL; can be passed as numeric or textual; in increasing
order: CRITICAL (50), ERROR (40), WARNING (30), INFO (20), DEBUG (10); N.B. the
text names are not case-sensitive: 'info' is OK
-c, --configfile, --config-file, --cfg CONFIGFILE (default: None)
Specify the name of a CONFIGFILE containing parameters to be read for this
invocation; an INI-style configuration file. A sample can be generated with
--dump-cfg. Although only one CONFIGFILE can be specified via the environment or
the command-line, the system config file (/etc/ldptool/ldptool.ini) is always read.
--dump_cli, --dump-cli
Produce the resulting, merged configuration as in CLI form. (After processing all
configuration sources (defaults, system configuration, user configuration,
environment variables, command-line.)
--dump_env, --dump-env
Produce the resulting, merged configuration as a shell environment file.
--dump_cfg, --dump-cfg
Produce the resulting, merged configuration as an INI-configuration file.
--debug_options, --debug-options
Provide lots of debugging information on option-processing; see also --loglevel
debug.
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
--asciidoc-asciidoc PATH
full path to asciidoc [/usr/bin/asciidoc]
--asciidoc-xmllint PATH
full path to xmllint [/usr/bin/xmllint]
N.B. The Asciidoc processor simply converts the source document to a Docbook4XML document
and then uses the richer Docbook4XML toolchain.
DOCBOOK4XML
--docbook4xml-xslchunk PATH
full path to LDP HTML chunker XSL
--docbook4xml-xslsingle PATH
full path to LDP HTML single-page XSL
--docbook4xml-xslprint PATH
full path to LDP FO print XSL
--docbook4xml-xmllint PATH
full path to xmllint [/usr/bin/xmllint]
--docbook4xml-xsltproc PATH
full path to xsltproc [/usr/bin/xsltproc]
--docbook4xml-html2text PATH
full path to html2text [/usr/bin/html2text]
--docbook4xml-fop PATH
full path to fop [/usr/bin/fop]
--docbook4xml-dblatex PATH
full path to dblatex [/usr/bin/dblatex]
DOCBOOK5XML
--docbook5xml-xslchunk PATH
full path to LDP HTML chunker XSL
--docbook5xml-xslsingle PATH
full path to LDP HTML single-page XSL
--docbook5xml-xslprint PATH
full path to LDP FO print XSL
--docbook5xml-rngfile PATH
full path to docbook.rng
--docbook5xml-xmllint PATH
full path to xmllint [/usr/bin/xmllint]
--docbook5xml-xsltproc PATH
full path to xsltproc [/usr/bin/xsltproc]
--docbook5xml-html2text PATH
full path to html2text [/usr/bin/html2text]
--docbook5xml-fop PATH
full path to fop [/usr/bin/fop]
--docbook5xml-dblatex PATH
full path to dblatex [/usr/bin/dblatex]
--docbook5xml-jing PATH
full path to jing [/usr/bin/jing]
DOCBOOKSGML
--docbooksgml-docbookdsl PATH
full path to html/docbook.dsl
--docbooksgml-ldpdsl PATH
full path to ldp/ldp.dsl [None]
--docbooksgml-jw PATH
full path to jw [/usr/bin/jw]
--docbooksgml-html2text PATH
full path to html2text [/usr/bin/html2text]
--docbooksgml-openjade PATH
full path to openjade [/usr/bin/openjade]
--docbooksgml-dblatex PATH
full path to dblatex [/usr/bin/dblatex]
--docbooksgml-collateindex PATH
full path to collateindex
LINUXDOC
--linuxdoc-sgmlcheck PATH
full path to sgmlcheck [/usr/bin/sgmlcheck]
--linuxdoc-sgml2html PATH
full path to sgml2html [/usr/bin/sgml2html]
--linuxdoc-html2text PATH
full path to html2text [/usr/bin/html2text]
--linuxdoc-htmldoc PATH
full path to htmldoc [/usr/bin/htmldoc]
AUTHOR
Martin A. Brown <martin@linux-ip.net>
COPYRIGHT
Manual page (C) 2016, Linux Documentation Project