1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
'\" t
.\" Title: manlifter
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 11/25/2010
.\" Manual: Documentation Tools
.\" Source: manlifter
.\" Language: English
.\"
.TH "MANLIFTER" "1" "11/25/2010" "manlifter" "Documentation Tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
manlifter \- mass\-conversion script and test harness for doclifter
.SH "SYNOPSIS"
.HP \w'\fBmanlifter\fR\ 'u
\fBmanlifter\fR [\-d\ \fIoption\fR] [\-e] [\-f\ \fIlistfile\fR] [\-h] [\-I\ \fImandir\fR] [\-m] [\-o\ \fIoutdir\fR] [\-p\ \fIpatch\-directory\fR] [\-P] [\-q] [\-v] [\-s\ \fIsection\fR] \fIname\fR...
.HP \w'\fBmanlifter\fR\ 'u
\fBmanlifter\fR [\-S]
.SH "DESCRIPTION"
.PP
\fBmanlifter\fR
is a script that sequences
\fBdoclifter\fR(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\&.
.PP
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\&.
.PP
For each source file examined, if the destination file exists and is newer than the source, the conversion is skipped; thus, incremental runs of
\fBmanlifter\fR
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\&.
.PP
Stub pages that are just
\fB\&.so\fR
redirections are translated to corresponding symlinks of XML files (and, with \-h, HTML files)\&.
.PP
\fBmanlifter\fR
may also be called with a single file argument, which is interpreted as the stem name of a potential manual page\&.
\fBmanlifter\fR
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
\fBdoclifter\fR
developers for debugging that program\&.
.PP
In either of the above cases,
\fBmanlifter\fR
will uncompress the file if it has a
\&.gz,
\&.bz2
or
\&.Z
suffix on the name\&.
.PP
Options are as follows:
.PP
\-d
.RS 4
Pass the string argument to each doclifter call as options\&. Each space\-separated token in the string becomes a separate argument in the call\&.
.RE
.PP
\-e
.RS 4
Run in log\-filter mode (mainly of interest to
\fBdoclifter\fR
developers)\&. In this mode,
\fBmanlifter\fR
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\&.
.RE
.PP
\-f
.RS 4
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\&.
.RE
.PP
\-h
.RS 4
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\&.
.RE
.PP
\-I
.RS 4
Specify the root of the manual\-page tree\&. By default this is
/usr/share/man\&.
.RE
.PP
\-m
.RS 4
Make a patch to correct the last page fetched\&. It is copied, an editor is called on the copy (using tghe environment variable
\fB$EDITOR\fR), and then
\fBdiff\fR(1)
is called to drop the patch in the prepatch directory\&. Fails with an error if such a patch is already present\&.
.RE
.PP
\-o
.RS 4
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\&.
.RE
.PP
\-p
.RS 4
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\&.
.RE
.PP
\-P
.RS 4
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!)\&.
.RE
.PP
\-q
.RS 4
Normally, pass the \-q (quiet) option to each doclifter call\&. In error\-filter mode, return a list of files on which translation failed\&.
.RE
.PP
\-v
.RS 4
Pass the \-v (verbose) option to each doclifter call\&. This option can be repeated to increase the verbosity level\&.
.RE
.PP
\-s
.RS 4
Specify a section to scan\&. Use this with an argument; it should not be necessary when doing a conversion of the entire tree\&.
.RE
.PP
\-S
.RS 4
Compile error statistics from a
\fBmanlifter\fR
logfile presented on standard input\&. This option will be of interest mainly to
\fBdoclifter\fR
developers\&.
.RE
.PP
\fBmanlifter\fR
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
\fBdoclifter\fR
was run\&.
.PP
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
\fBdoclifter\fR\*(Aqs runtime in seconds\&.
.PP
This initial line may be followed by information messages and the error output of the doclifter run\&.
.PP
\fBmanlifter\fR
must find a copy of
\fBdoclifter\fR
in either the current directory or one of the command directories in your
\fBPATH\fR
in order to run\&.
.SH "BUGS"
.PP
HTML generation is painfully slow\&. Unfortunately, there is little we can do to remedy this, because XSLT engines are painfully slow\&.
.SH "SEE ALSO"
.PP
\fBdoclifter\fR(1),
\fBxmlto\fR(1)
.SH "AUTHOR"
.PP
Eric S\&. Raymond
esr@thyrsus\&.com
.PP
There is a project web page at
\m[blue]\fBhttp://www\&.catb\&.org/~esr/doclifter/\fR\m[]\&.
|
