1MANLIFTER(1)                  Documentation Tools                 MANLIFTER(1)
2
3
4

NAME

6       manlifter - mass-conversion script and test harness for doclifter
7

SYNOPSIS

9       manlifter [-d option] [-e] [-f listfile] [-h] [-I mandir] [-m] [-M]
10                 [-o outdir] [-p patch-directory] [-P] [-q] [-v] [-s section]
11                 [-X exclude] name...
12
13       manlifter [-S]
14

DESCRIPTION

16       manlifter is a script that sequences doclifter(1) to convert an entire
17       manual-page tree to XML-Docbook, optionally also generating HTML from
18       the XML. Another use is as a torture-test tool for doclifter; it logs
19       errors to standard output and collects timings.
20
21       Called without any file arguments, manlifter tries to convert all
22       eligible man pages installed on the system, placing the resulting xml
23       files under xmlman in the current directory. Each successfully
24       translated page foo.N is copied to manN/foo.xml beneath the output
25       directory, regardless of what source directory it came from.
26
27       A manual page is considered ineligible for batch conversion if it
28       contains text indicating it has been generated from DocBook masters of
29       from Doxygen.
30
31       For each source file examined, if the destination file exists and is
32       newer than the source, the conversion is skipped; thus, incremental
33       runs of manlifter do the least work needed to keep the target XML tree
34       up to date. Likewise, in -h mode derived HTML files are only made when
35       necessary.
36
37       Stub pages that are just .so redirections are translated to
38       corresponding symlinks of XML files (and, with -h, HTML files).
39
40       manlifter may also be called with a single file argument, which is
41       interpreted as the stem name of a potential manual page.  manlifter
42       then searches all selected manual sections for a matching page and
43       attempts to convert it. In this case, a copy of the man page and the
44       converted version are dropped immediately beheath the output directory,
45       with the names foobar.man and foobar.man.xml, respectively. This mode
46       is normally only of interest only to doclifter developers for debugging
47       that program.
48
49       In either of the above cases, manlifter will uncompress the file if it
50       has a .gz, .bz2 or .Z suffix on the name.
51
52       Options are as follows:
53
54       -d
55           Pass the string argument to each doclifter call as options. Each
56           space-separated token in the string becomes a separate argument in
57           the call.
58
59       -e
60           Run in log-filter mode (mainly of interest to doclifter
61           developers). In this mode, manlifter reads a test log from standard
62           input and filters it in a a way dependent on the -f and -q options.
63           If neither of these is given, messages from successful runs are
64           stripped out and only errors passed through to standard output.
65
66       -f
67           Normally, run doclifter on the files named by each line in the
68           argument file. In error-filter mode the argument is instead
69           interpreted as a filtering regular expression.
70
71       -h
72           Also generate HTML translations into the output directory. DocBook
73           citerefentry markup is transformed to hyperlinks in the directory,
74           and a contents listing is generated to index.html.
75
76       -I
77           Specify the root of the manual-page tree. By default this is
78           /usr/share/man.
79
80       -m
81           Make a patch to correct the last page fetched. It is copied, an
82           editor is called on the copy (using the environment variable
83           $EDITOR), and then diff(1) is called to drop the patch in the
84           prepatch directory. Fails with an error if such a patch is already
85           present.
86
87       -M
88           Lift the specified files, then do the equivalent of the -m option.
89
90       -o
91           Set the output directory into which XML-DocBook translations will
92           be dropped. By default this is xmlman under the current directory
93           in batch mode, or the current directory otherwise.
94
95       -p
96           Interpret the argument as the name of a patch directory (the
97           default name is prepatch under the current directory). Each file
98           named foo.N.patch is interpreted as a patch to be applied to the
99           manual page foo(N) before doclifter translates it.
100
101       -q
102           Normally, pass the -q (quiet) option to each doclifter call. In
103           error-filter mode, return a list of files on which translation
104           failed.
105
106       -v
107           Pass the -v (verbose) option to each doclifter call. This option
108           can be repeated to increase the verbosity level.
109
110       -s
111           Specify a section to scan. Use this with an argument; it should not
112           be necessary when doing a conversion of the entire tree.
113
114       -S
115           Compile error statistics from a manlifter logfile presented on
116           standard input. This option will be of interest mainly to doclifter
117           developers.
118
119       -X
120           In batch mode exclude pages listed in the argument file. Meant to
121           be used for pages that are known good and take an extremely long
122           time to lift, in order to cut down the time for a test run. (Most
123           pages lift in less than a half second, but a few can take 15
124           minutes or longer.)
125
126       manlifter emits a logfile to standard output. The file begins with a
127       timestamp line and a blank line, and ends with a line giving run time
128       and various interesting statistics. Between these are stanzas,
129       separated by blank lines, one for each file on which doclifter was run.
130
131       The first line of each stanza beguns with "! ", followed by the
132       pathname of the source manual pager, followed by "=" and the return
133       status of doclifter run on that file. Following that is a space and
134       doclifter's runtime in seconds.
135
136       This initial line may be followed by information messages and the error
137       output of the doclifter run.
138
139       manlifter must find a copy of doclifter in either the current directory
140       or one of the command directories in your PATH in order to run.
141

BUGS

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

SEE ALSO

147       doclifter(1), xmlto(1)
148

AUTHOR

150       Eric S. Raymond <esr@thyrsus.com>
151
152       There is a project web page at http://www.catb.org/~esr/doclifter/.
153
154
155
156manlifter                         07/21/2022                      MANLIFTER(1)
Impressum