manlifter - mass-conversion script and test harness for doclifter
manlifter [-d option] [-e] [-f listfile] [-h] [-I mandir] [-m] [-M] [-o outdir] [-p patch-directory] [-P] [-q] [-v] [-s section] [-X exclude] name...
manlifter is a script that sequences doclifter(1) to convert an entire manual-page tree to XML-Docbook, optionally also generating HTML from the XML. Another use is as a torture-test tool for doclifter; it logs errors to standard output and collects timings.
Called without any file arguments, manlifter tries to convert all eligible man pages installed on the system, placing the resulting xml files under xmlman in the current directory. Each successfully translated page foo.N is copied to manN/foo.xml beneath the output directory, regardless of what source directory it came from.
A manual page is considered ineligible for batch conversion if it contains text indicating it has been generated from DocBook masters of from Doxygen.
For each source file examined, if the destination file exists and is newer than the source, the conversion is skipped; thus, incremental runs of manlifter do the least work needed to keep the target XML tree up to date. Likewise, in -h mode derived HTML files are only made when necessary.
Stub pages that are just .so redirections are translated to corresponding symlinks of XML files (and, with -h, HTML files).
manlifter may also be called with a single file argument, which is interpreted as the stem name of a potential manual page. manlifter then searches all selected manual sections for a matching page and attempts to convert it. In this case, a copy of the man page and the converted version are dropped immediately beheath the output directory, with the names foobar.man and foobar.man.xml, respectively. This mode is normally only of interest only to doclifter developers for debugging that program.
In either of the above cases, manlifter will uncompress the file if it has a .gz, .bz2 or .Z suffix on the name.
Options are as follows:
manlifter emits a logfile to standard output. The file begins with a timestamp line and a blank line, and ends with a line giving run time and various interesting statistics. Between these are stanzas, separated by blank lines, one for each file on which doclifter was run.
The first line of each stanza beguns with "! ", followed by the pathname of the source manual pager, followed by "=" and the return status of doclifter run on that file. Following that is a space and doclifter's runtime in seconds.
This initial line may be followed by information messages and the error output of the doclifter run.
manlifter must find a copy of doclifter in either the current directory or one of the command directories in your PATH in order to run.
HTML generation is painfully slow. Unfortunately, there is little we can do to remedy this, because XSLT engines are painfully slow.
Eric S. Raymond <email@example.com>
There is a project web page at http://www.catb.org/~esr/doclifter/.