1MANLIFTER(1) Documentation Tools MANLIFTER(1)
2
6 manlifter - mass-conversion script and test harness for doclifter
7
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 manlifter [-S]
14
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 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 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 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 Stub pages that are just .so redirections are translated to
38 corresponding symlinks of XML files (and, with -h, HTML files).
39 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 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 Options are as follows:
53 -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 -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 -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 -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 -I
77 Specify the root of the manual-page tree. By default this is
78 /usr/share/man.
79 -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 -M
88 Lift the specified files, then do the equivalent of the -m option.
89 -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 -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 -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 -v
107 Pass the -v (verbose) option to each doclifter call. This option
108 can be repeated to increase the verbosity level.
109 -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 -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 -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 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 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 This initial line may be followed by information messages and the error
137 output of the doclifter run.
138 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
143 HTML generation is painfully slow. Unfortunately, there is little we
144 can do to remedy this, because XSLT engines are painfully slow.
145
147 doclifter(1), xmlto(1)
148
150 Eric S. Raymond <esr@thyrsus.com>
151 There is a project web page at http://www.catb.org/~esr/doclifter/.
153manlifter 07/21/2022 MANLIFTER(1)