Debian Codegraph @

upstream/debian-unstable/man1/rman.1

raw
1 .TH PolyglotMan 1
2 .SH "NAME "
3 PolyglotMan, rman - reverse compile man pages from formatted
4 form to a number of source formats: ASCII, roff, TkMan, Tk,
5 Sections, HTML, SGML, MIME, LaTeX, LaTeX2e, RTF, POD.
6 .SH "SYNOPSIS "
7 rman [ \fIoptions \fR] [ \fIfile \fR]
8 .SH "DESCRIPTION "
9 Up-to-date instructions can be found at
10 http://polyglotman.sourceforge.net/rman.html
11
12 .PP
13 \fIPolyglotMan \fR takes man pages from most of the popular flavors
14 of UNIX and transforms them into any of a number of text source
15 formats. PolyglotMan was formerly known as RosettaMan. The name
16 of the binary is still called \fIrman\fR, for scripts that depend
17 on that name; mnemonically, just think "reverse man". Previously \fI
18 PolyglotMan \fR required pages to be formatted by nroff(1) prior
19 to its processing. With version 3.0, it \fIprefers [tn]roff source \fR
20 and usually produces results that are better yet. And source
21 processing is the only way to translate tables. Source format
22 translation is not as mature as formatted, however, so try formatted
23 translation as a backup.
24 .PP
25 In parsing [tn]roff source, one could implement an arbitrarily
26 large subset of [tn]roff, which I did not and will not do, so
27 the results can be off. I did implement a significant subset
28 of those used in man pages, however, including tbl (but not eqn),
29 if tests, and general macro definitions, so usually the results
30 look great. If they don't, format the page with nroff before
31 sending it to PolyglotMan. If PolyglotMan doesn't recognize a
32 key macro used by a large class of pages, however, e-mail me
33 the source and a uuencoded nroff-formatted page and I'll see
34 what I can do. When running PolyglotMan with man page source
35 that includes or redirects to other [tn]roff source using the .so (source
36 or inclusion) macro, you should be in the parent directory of
37 the page, since pages are written with this assumption. For example,
38 if you are translating /usr/share/man/man1/ls.1, first cd into /usr/share/man.
39 .PP
40 \fIPolyglotMan \fR accepts man pages from: SunOS, Sun Solaris,
41 Hewlett-Packard HP-UX, AT&T System V, OSF/1 aka Digital UNIX,
42 DEC Ultrix, SGI IRIX, Linux, FreeBSD, SCO. Source processing
43 works for: SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System
44 V, OSF/1 aka Digital UNIX, DEC Ultrix. It can produce printable
45 ASCII-only (control characters stripped), section headers-only,
46 Tk, TkMan, [tn]roff (traditional man page source), XML, HTML,
47 MIME, LaTeX, LaTeX2e, RTF, Perl 5 POD. A modular architecture
48 permits easy addition of additional output formats.
49 .PP
50 The latest version of PolyglotMan is available from \fI
51 http://polyglotman.sourceforge.net/ \fR.
52 .SH "OPTIONS "
53 The following options should not be used with any others and
54 exit PolyglotMan without processing any input.
55 .TP 15
56 \-h|\-\-help
57 Show list of command line options and exit.
58 .TP 15
59 \-v|\-\-version
60 Show version number and exit.
61 .PP
62 \fIYou should specify the filter first, as this sets a number
63 of parameters, and then specify other options.
64 .TP 15
65 \-f|\-\-filter <ASCII|roff|TkMan|Tk|Sections|HTML|XML|MIME|LaTeX|LaTeX2e|RTF|POD>
66 Set the output filter. Defaults to ASCII.
67 .TP 15
68 \-S|\-\-source
69 PolyglotMan tries to automatically determine whether its input
70 is source or formatted; use this option to declare source input.
71 .TP 15
72 \-F|\-\-format|\-\-formatted
73 PolyglotMan tries to automatically determine whether its input
74 is source or formatted; use this option to declare formatted
75 input.
76 .TP 15
77 \-l|\-\-title \fIprintf-string \fR
78 In HTML mode this sets the <TITLE> of the man pages, given the
79 same parameters as \fI-r \fR.
80 .TP 15
81 \-r|\-\-reference|\-\-manref \fIprintf-string \fR
82 In HTML and XML modes this sets the URL form by which to retrieve
83 other man pages. The string can use two supplied parameters:
84 the man page name and its section. (See the Examples section.)
85 If the string is null (as if set from a shell by "\-r ''"), `-'
86 or `off', then man page references will not be HREFs, just set
87 in italics. If your printf supports XPG3 positions specifier,
88 this can be quite flexible.
89 .TP 15
90 \-V|\-\-volumes \fI<colon-separated list> \fR
91 Set the list of valid volumes to check against when looking for
92 cross-references to other man pages. Defaults to \fI1:2:3:4:5:6:7:8:9:o:l:n:p \fR(volume
93 names can be multicharacter). If an non-whitespace string in
94 the page is immediately followed by a left parenthesis, then
95 one of the valid volumes, and ends with optional other characters
96 and then a right parenthesis--then that string is reported as
97 a reference to another manual page. If this \-V string starts
98 with an equals sign, then no optional characters are allowed
99 between the match to the list of valids and the right parenthesis. (This
100 option is needed for SCO UNIX.)
101 .PP
102 The following options apply only when formatted pages are given
103 as input. They do not apply to or are always handled correctly with
104 the source.
105 .TP 15
106 \-b|\-\-subsections
107 Try to recognize subsection titles in addition to section titles.
108 This can cause problems on some UNIX flavors.
109 .TP 15
110 \-K|\-\-nobreak
111 Indicate manual pages don't have page breaks, so don't look for
112 footers and headers around them. (Older nroff \-man macros always
113 put in page breaks, but lately some vendors have realized that
114 printouts are made through troff(1), whereas nroff \-man is used to
115 format pages for reading on screen, and so have eliminated page
116 breaks.) \fIPolyglotMan \fR usually gets this right even without
117 this flag.
118 .TP 15
119 \-k|\-\-keep
120 Keep headers and footers, as a canonical report at the end of
121 the page. changeleft
122 Move changebars, such as those found in the Tcl/Tk manual pages,
123 to the left. --> notaggressive
124 \fIDisable \fR aggressive man page parsing. Aggressive manual,
125 which is on by default, page parsing elides headers and footers,
126 identifies sections and more. -->
127 .TP 15
128 \-n|\-\-name \fIname \fR
129 Set name of man page (used in roff format). If the filename is
130 given in the form " \fIname \fR. \fIsection \fR", the name and
131 section are automatically determined. If the page is being parsed
132 from [tn]roff source and it has a .TH line, this information
133 is extracted from that line.
134 .TP 15
135 \-p|\-\-paragraph
136 paragraph mode toggle. The filter determines whether lines should
137 be linebroken as they were by nroff, or whether lines should
138 be flowed together into paragraphs. Mainly for internal use.
139 .TP 15
140 \-s|section \fI# \fR
141 Set volume (aka section) number of man page (used in roff format).
142 tables
143 Turn on aggressive table parsing. -->
144 .TP 15
145 \-t|\-\-tabstops \fI# \fR
146 For those macros sets that use tabs in place of spaces where
147 possible in order to reduce the number of characters used, set
148 tabstops every \fI# \fR columns. Defaults to 8.
149 .SH "NOTES ON FILTER TYPES "
150 .SS "ROFF "
151 Some flavors of UNIX ship man page without [tn]roff source, making
152 one's laser printer little more than a laser-powered daisy wheel.
153 This filter tries to intuit the original [tn]roff directives,
154 which can then be recompiled by [tn]roff.
155 .SS "TkMan "
156 TkMan(1), a hypertext man page browser, uses \fIPolyglotMan \fR
157 to show man pages without the (usually) useless headers and footers
158 on each page. It also collects section and (optionally) subsection
159 heads for direct access from a pulldown menu. TkMan and Tcl/Tk,
160 the toolkit in which it's written, are available via anonymous
161 ftp from \fIftp://ftp.smli.com/pub/tcl/ \fR
162 .SS "Tk "
163 This option outputs the text in a series of Tcl lists consisting
164 of text-tags pairs, where tag names roughly correspond to HTML.
165 This output can be inserted into a Tk text widget by doing an \fI
166 eval <textwidget> insert end <text> \fR. This format should be
167 relatively easily parsible by other programs that want both the
168 text and the tags. See also ASCII.
169 .SS "ASCII "
170 When printed on a line printer, man pages try to produce special
171 text effects by overstriking characters with themselves (to produce
172 bold) and underscores (underlining). Other text processing software,
173 such as text editors, searchers, and indexers, must counteract
174 this. The ASCII filter strips away this formatting. Piping nroff
175 output through \fIcol \-b \fR also strips away this formatting,
176 but it leaves behind unsightly page headers and footers. Also
177 see Tk.
178 .SS "Sections "
179 Dumps section and (optionally) subsection titles. This might
180 be useful for another program that processes man pages.
181 .SS "HTML "
182 With a simple extension to a HTTP server for Mosaic(1) or other
183 World Wide Web browser, \fIPolyglotMan \fR can produce high quality
184 HTML on the fly. Several such extensions and pointers to several
185 others are included in \fIPolyglotMan \fR's \fIcontrib \fR directory.
186 .SS "XML "
187 This is appoaching the Docbook DTD, but I'm hoping that someone
188 with a real interest in this will polish the tags
189 generated. Try it to see how close the tags are now.
190 .SS "MIME "
191 MIME (Multipurpose Internet Mail Extensions) as defined by RFC 1563,
192 good for consumption by MIME-aware e-mailers or as Emacs (>=19.29)
193 enriched documents.
194 .SS "LaTeX and LaTeX2e "
195 Why not?
196 .SS "RTF "
197 Use output on Mac or NeXT or whatever. Maybe take random man
198 pages and integrate them better with NeXT's documentation system.
199 Maybe NeXT has its own man page macros that do this.
200 .SS "PostScript and FrameMaker "
201 To produce PostScript, use \fIgroff \fR or \fIpsroff \fR. To
202 produce FrameMaker MIF, use FrameMaker's builtin filter. In both
203 cases you need \fI[tn]roff \fR source, so if you only have a
204 formatted version of the manual page, use \fIPolyglotMan \fR's
205 roff filter first.
206 .SH "EXAMPLES "
207 To convert the \fIformatted \fR man page named \fIls.1 \fR back
208 into [tn]roff source form:
209 .PP
210 \fIrman \-f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1 \fR
211 .br
212 .PP
213 Long man pages are often compressed to conserve space (compression
214 is especially effective on formatted man pages as many of the
215 characters are spaces). As it is a long man page, it probably
216 has subsections, which we try to separate out (some macro sets
217 don't distinguish subsections well enough for \fIPolyglotMan \fR
218 to detect them). Let's convert this to LaTeX format:
219 .br
220 .PP
221 \fIpcat /usr/catman/a_man/cat1/automount.z | rman \-b \-n automount \-s 1 \-f
222 latex > automount.man \fR
223 .br
224 .PP
225 Alternatively, \fIman 1 automount | rman \-b \-n automount \-s 1 \-f
226 latex > automount.man \fR
227 .br
228 .PP
229 For HTML/Mosaic users, \fIPolyglotMan \fR can, without modification
230 of the source code, produce HTML links that point to other HTML
231 man pages either pregenerated or generated on the fly. First
232 let's assume pregenerated HTML versions of man pages stored in \fI/usr/share/man/html \fR.
233 Generate these one-by-one with the following form:
234 .br
235 \fIrman \-f html \-r 'http:/usr/share/man/html/%s.%s.html' /usr/share/man/cat1/ls.1 > /usr/share/man/html/ls.1.html \fR
236 .br
237 .PP
238 If you've extended your HTML client to generate HTML on the fly
239 you should use something like:
240 .br
241 \fIrman \-f html \-r 'http:~/bin/man2html?%s:%s' /usr/share/man/cat1/ls.1 \fR
242 .br
243 when generating HTML.
244 .SH "BUGS/INCOMPATIBILITIES "
245 \fIPolyglotMan \fR is not perfect in all cases, but it usually
246 does a good job, and in any case reduces the problem of converting
247 man pages to light editing.
248 .PP
249 Tables in formatted pages, especially H-P's, aren't handled very
250 well. Be sure to pass in source for the page to recognize tables.
251 .PP
252 The man pager \fIwoman\fR(1) applies its own idea of formatting
253 for man pages, which can confuse \fIPolyglotMan \fR. Bypass \fI
254 woman \fR by passing the formatted manual page text directly
255 into \fIPolyglotMan \fR.
256 .PP
257 The [tn]roff output format uses fB to turn on boldface. If your
258 macro set requires .B, you'll have to a postprocess the \fIPolyglotMan \fR
259 output.
260 .SH "SEE ALSO "
261 \fItkman(1) \fR, \fIxman(1) \fR, \fIman(1) \fR, \fIman(7) \fR
262 or \fIman(5) \fR depending on your flavor of UNIX
263 .SH "AUTHOR "
264 PolyglotMan
265 .br
266 by Thomas A. Phelps ( \[email protected] \fR)
267 .br
268 developed at the
269 .br
270 University of California, Berkeley
271 .br
272 Computer Science Division
273 .PP
274 Manual page last updated on $Date: 1998/07/13 09:47:28 $