xenial (1) manlifter.1.gz

Provided by: doclifter_2.11-1_all bug

NAME

       manlifter - mass-conversion script and test harness for doclifter

SYNOPSIS

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

       -P
           Enable profiling using the Python hotshot module; this is only useful for tuning doclifter so it runs
           faster. Raw data is written to manlifter.prof, and a digested report is appended to the log on
           standard output. Warning: the raw data files can become huge, and the postprocessing for report
           generation can take as long as the actual processing (or longer!).

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