LDPTOOL(1)

📦 version 0.7.13, in ubuntu jammy

LDPTOOL 💅 (section 1 of the manual, bestie)

okay so. hi. you've found ldptool, and honestly? she's the whole publishing pipeline and she knows it. pull up a chair 🫶

✨ NAME ✨

ldptool — DocBook, Linuxdoc and Asciidoc build/publishing tool. 💖

✨ SYNOPSIS ✨

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

✨ DESCRIPTION ✨

so basically: you hand ldptool a pathname and it will cook up chunked HTML, single-page HTML, PDF and plain text outputs for every source document you passed it. (peep Source document discovery below, it's important, iykyk.)

if you pass it no arguments at all, she doesn't sulk — she gathers up every directory you gave to --sourcedir and scans through them looking for valid source documents. ✨

what she actually does depends entirely on the options you passed. and if you passed nothing? then the default --build action gets attempted. periodt. the options that steer the whole program live in the Action options and Main options sections. everything else got yeeted to the tail of the manpage, because those are just configurables for the individual document processors. not the main character energy. 💅

here's everything ldptool can do:

  • 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 — shows you a help message and dips. that's it, that's the whole vibe. 👋
  • -b, --build — builds LDP documentation into the --builddir and exits. this is the default action when you haven't specified any other one. no notes. ⭐
  • -p, --publish — builds LDP documentation into the --builddir. then, if every build succeeded, she copies the result for each source document into the --pubdir — which effectively replaces (and deletes 😭) the older documents. and finally, she removes --builddir if it's empty. she cleans up after herself, queen behavior. 👑
  • -S, --script — prints a runnable bash script to STDOUT. it's basically a little shell script showing exactly what would get executed upon --build. like a trailer for the movie. 🎬
  • -l, --detail, --list — examines the various SOURCEDIRs and the PUBDIR and generates a report showing the FORMAT of the source document and the STATUS of the document. add the --verbose flag for more info. 🔍
  • -t, --summary — examines the various SOURCEDIRs and the PUBDIR and generates a short report summarizing documents by STATUS and by DOCTYPE. add --verbose for more. 📊
  • -T, --doctypes, --formats, --format, --list-doctypes, --list-formats — lists the supported DOCTYPEs. there is exactly one processor for each DOCTYPE, no cap. 🧚
  • --statustypes, --list-statustypes — lists the possible document STATUS types. there are only seven basic status types, but several synonyms and groups of STATUS types (internally called 'classes'). so many little friend groups. 💜

🌈 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. (go off, stack them.)

  • -o, --pubdir, --output, --outputdir, --outdir PUBDIR (default: None) — specify the name of a PUBDIR. it's used as the publication destination if the build succeeds. when --publish is used together with --pubdir, the output of a successful document build gets 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. this is a scratch directory used to build each source document; it's temporary and will be removed if the build succeeds AND --publish has been requested. under the --build action though, all output directories and contents remain in the BUILDDIR for inspection. 👀
  • --verbose [True | False] (default: False) — provides more information in the --list and --detail actions. you can throw this option in without an argument, which is equivalent to True. and to let the CLI supersede environment or configuration file values, --verbose false is also supported. flexible queen. ✨
  • --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 (list below), and by the document STATUS (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 with this option. 🎀

the --resources option may be used more than once.

  • --loglevel LOGLEVEL (default: ERROR) — set the loglevel to LOGLEVEL. it 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. and even though only one CONFIGFILE can be specified via the environment or the command-line, the system config file (/etc/ldptool/ldptool.ini) is always read. always. she never skips it. 💅
  • --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 — provides lots of debugging information on option-processing; see also --loglevel debug. 💀

🦋 SOURCE DOCUMENT DISCOVERY 🦋

almost every documentation format out there allows a document to span multiple files. and like, more than half of the LDP document collection is single-file HOWTO contributions, but there are also a bunch of documents composed of dozens, even hundreds of files. 😭

so to handle both the lil baby single-file docs and these absolute units, LDP adopted a simple (unoriginal, bestie, they said it not me) naming strategy so one document can 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's a STEM/STEM.xml and a STEM/STEM.sgml in the same directory, that is an error, and ldptool will freak out and shoot pigeons. 🕊️💀 not a drill.)

during document discovery, ldptool walks through all of the source directories specified with --sourcedir and builds a complete list of all identifiable source documents. then she walks through the publication directory --pubdir and matches up each output directory (by its STEM) with the corresponding STEM found in one of the source directories. 💖

then ldptool can figure out whether any source files are newer. she uses content-hashing, i.e. MD5, and if a source file is newer, the status is stale. if there's no matching output, the source file is new. if there's an output with no source, that one's an 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 💜

ldptool accepts configuration via environment variables. all of these environment variables are prefixed with LDPTOOL_. every single one. 💅

the name of each variable is constructed from the primary command-line option name. so -b is better known as --builddir, which means the environment variable is 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. 🧚

so the environment variable corresponding to the CLI option --asciidoc-xmllint would be LDPTOOL_ASCIIDOC_XMLLINT. and similarly, --asciidoc-asciidoc should be LDPTOOL_ASCIIDOC_ASCIIDOC. slay.

variables that accept multiple options use the comma as a separator:

LDPTOOL_RESOURCES=images,resources

and if you want the complete listing of possible environment variables with all current values, just run ldptool --dump-env. 💖

🎀 CONFIGURATION FILE 🎀

okay so bestie, there's a whole config file situation and honestly it's giving organized queen energy. The system-installed one lives at /etc/ldptool/ldptool.ini. ✨

The format? It's a simple INI-style config file — one block for the main program, and then one block for each handler. Very demure, very mindful. Here's a partial example so you can see the vibe:

[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 (like resources up there in that config fragment, bestie — one option, many values, she contains multitudes 💅).

And if you wanna see the complete, current configuration file? Just hit ldptool --dump-cfg. It prints the whole thing for you. Obsessed. 💖

🦋 CONFIGURATION OPTION FRAGMENTS FOR EACH DOCTYPE HANDLER 🦋

So here's the tea: every source format has a single handler, and each DOCTYPE handler might need a different set of executables and/or data files to do its job. The defaults depend on the platform and get detected at runtime. 🌸

In most cases the commands live in /usr/bin (see below, bestie). The data files — like the LDP XSL files and the docbook.rng — may live in different places on different systems. It's giving "it depends" but make it filesystem. 🫶

If a given DOCTYPE handler can't find all of its requirements, it will complain to STDERR during execution — but it will NOT abort the rest of the run. So she'll throw a lil tantrum and then keep going. Resilient icon. 👑

And if for some reason ldptool can't 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 --configfile your.ini to specify these paths. Problem solved, no cap. ✨

🌈 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. So it's lowkey just handing you off to the fancier sibling. 💅

🔥 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> — king behavior, honestly. 👑

Manual page (C) 2016, Linux Documentation Project ✨

and that's the whole page, bestie!! 🦋 this manual page is version 1.9.2, dated Jul 13, 2017, and it's the LDPTOOL(1) page — go forth and document, you absolute icon 💅✨

📦 where this page comes from