Man Linux: Main Page and Category List

NAME

       manlifter - mass-conversion script and test harness for doclifter

SYNOPSIS

       manlifter [-d option] [-e] [-f listfile] [-h] [-I mandir] [-o outdir]
                 [-p patch-directory] [-q] [-v] [-s section] name...

       manlifter [-S]

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

       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.

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

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

                                  05/27/2008