= manlifter(1)
:doctype: manpage
:manmanual: Documentation Tools
:mansource: manlifter
:manvolnum: 1

== NAME
manlifter - mass-conversion script and test harness for doclifter

== SYNOPSIS
*manlifter* [options] [_name_...]

== DESCRIPTION

`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:

-d::
  Pass the string argument to each doclifter call as options. Each
  space-separated token in the string becomes a separate argument in the
  call.
-e::
  Run in log-filter mode (mainly of interest to `doclifter` developers).
  In this mode, `manlifter` reads a test log from standard input and
  filters it in a a way dependent on the -f and -q options. If neither
  of these is given, messages from successful runs are stripped out and
  only errors passed through to standard output.
-f::
  Normally, run doclifter on the files named by each line in the
  argument file. In error-filter mode the argument is instead
  interpreted as a filtering regular expression.
-h::
  Also generate HTML translations into the output directory. DocBook
  citerefentry markup is transformed to hyperlinks in the directory, and
  a contents listing is generated to `index.html`.
-I::
  Specify the root of the manual-page tree. By default this is
  `/usr/share/man`.
-m::
  Make a patch to correct the last page fetched. It is copied, an editor
  is called on the copy (using the environment variable `$EDITOR`), and
  then `diff(1)` is called to drop the patch in the prepatch directory.
  Fails with an error if such a patch is already present.
-M::
  Lift the specified files, then do the equivalent of the -m option.
-o::
  Set the output directory into which XML-DocBook translations will be
  dropped. By default this is `xmlman` under the current directory in
  batch mode, or the current directory otherwise.
-p::
  Interpret the argument as the name of a patch directory (the default
  name is `prepatch` under the current directory). Each file named
  `foo.N.patch` is interpreted as a patch to be applied to the manual
  page foo(N) before doclifter translates it.
-q::
  Normally, pass the -q (quiet) option to each doclifter call. In
  error-filter mode, return a list of files on which translation failed.
-v::
  Pass the -v (verbose) option to each doclifter call. This option can
  be repeated to increase the verbosity level.
-s::
  Specify a section to scan. Use this with an argument; it should not be
  necessary when doing a conversion of the entire tree.
-S::
  Compile error statistics from a `manlifter` logfile presented on
  standard input. This option will be of interest mainly to `doclifter`
  developers.
-X::
  In batch mode exclude pages listed in the argument file. Meant to be
  used for pages that are known good and take an extremely long time to
  lift, in order to cut down the time for a test run. (Most pages lift
  in less than a half second, but a few can take 15 minutes or longer.)

`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.

== BUGS

HTML generation is painfully slow. Unfortunately, there is little we can
do to remedy this, because XSLT engines are painfully slow.

== SEE ALSO

`doclifter(1)`, `xmlto(1)`

== AUTHOR

Eric S. Raymond <esr@thyrsus.com>

There is a project web page at http://www.catb.org/~esr/doclifter/.
