1
by Stephen M Moraco
Import upstream version 3.0.9 |
1 |
.TH PolyglotMan 1 |
2 |
.SH "NAME " |
|
3 |
PolyglotMan, rman - reverse compile man pages from formatted |
|
5.1.1
by Anton Gladky
* New mantainer (closes: #465951) |
4 |
form to a number of source formats: ASCII, roff, TkMan, Tk, |
5 |
Sections, HTML, SGML, MIME, LaTeX, LaTeX2e, RTF, POD. |
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
6 |
.SH "SYNOPSIS " |
7 |
rman [ \fIoptions \fR] [ \fIfile \fR] |
|
8 |
.SH "DESCRIPTION " |
|
1.1.1
by Stephen M Moraco
Import upstream version 3.2 |
9 |
Up-to-date instructions can be found at |
10 |
http://polyglotman.sourceforge.net/rman.html |
|
11 |
||
12 |
.PP
|
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
3
by Stephen M Moraco
* Update Policy Version |
16 |
of the binary is still called \fIrman\fR, for scripts that depend |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
17 |
on that name; mnemonically, just think "reverse man". Previously \fI
|
3
by Stephen M Moraco
* Update Policy Version |
18 |
PolyglotMan \fR required pages to be formatted by nroff(1) prior
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
3
by Stephen M Moraco
* Update Policy Version |
28 |
of those used in man pages, however, including tbl (but not eqn), |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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, |
|
5
by Frank Lichtenheld
* QA upload. |
38 |
if you are translating /usr/share/man/man1/ls.1, first cd into /usr/share/man. |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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, |
|
5.1.1
by Anton Gladky
* New mantainer (closes: #465951) |
46 |
Tk, TkMan, [tn]roff (traditional man page source), XML, HTML, |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
47 |
MIME, LaTeX, LaTeX2e, RTF, Perl 5 POD. A modular architecture |
48 |
permits easy addition of additional output formats. |
|
49 |
.PP
|
|
1.1.1
by Stephen M Moraco
Import upstream version 3.2 |
50 |
The latest version of PolyglotMan is available from \fI
|
51 |
http://polyglotman.sourceforge.net/ \fR.
|
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
56 |
\-h|\-\-help |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
57 |
Show list of command line options and exit. |
58 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
59 |
\-v|\-\-version |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5.1.1
by Anton Gladky
* New mantainer (closes: #465951) |
65 |
\-f|\-\-filter <ASCII|roff|TkMan|Tk|Sections|HTML|XML|MIME|LaTeX|LaTeX2e|RTF|POD> |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
66 |
Set the output filter. Defaults to ASCII. |
67 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
68 |
\-S|\-\-source |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
69 |
PolyglotMan tries to automatically determine whether its input |
70 |
is source or formatted; use this option to declare source input. |
|
71 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
72 |
\-F|\-\-format|\-\-formatted |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
77 |
\-l|\-\-title \fIprintf-string \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
78 |
In HTML mode this sets the <TITLE> of the man pages, given the |
79 |
same parameters as \fI-r \fR. |
|
80 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
81 |
\-r|\-\-reference|\-\-manref \fIprintf-string \fR |
5.1.1
by Anton Gladky
* New mantainer (closes: #465951) |
82 |
In HTML and XML modes this sets the URL form by which to retrieve |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
83 |
other man pages. The string can use two supplied parameters: |
84 |
the man page name and its section. (See the Examples section.) |
|
5
by Frank Lichtenheld
* QA upload. |
85 |
If the string is null (as if set from a shell by "\-r ''"), `-'
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
90 |
\-V|\-\-volumes \fI<colon-separated list> \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
97 |
a reference to another manual page. If this \-V string starts
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
3
by Stephen M Moraco
* Update Policy Version |
103 |
as input. They do not apply to or are always handled correctly with |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
104 |
the source. |
105 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
106 |
\-b|\-\-subsections |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
107 |
Try to recognize subsection titles in addition to section titles. |
108 |
This can cause problems on some UNIX flavors. |
|
109 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
110 |
\-K|\-\-nobreak |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
111 |
Indicate manual pages don't have page breaks, so don't look for |
5
by Frank Lichtenheld
* QA upload. |
112 |
footers and headers around them. (Older nroff \-man macros always
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
113 |
put in page breaks, but lately some vendors have realized that |
5
by Frank Lichtenheld
* QA upload. |
114 |
printouts are made through troff(1), whereas nroff \-man is used to
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
119 |
\-k|\-\-keep |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
128 |
\-n|\-\-name \fIname \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
135 |
\-p|\-\-paragraph |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
140 |
\-s|section \fI# \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
141 |
Set volume (aka section) number of man page (used in roff format). |
142 |
tables |
|
143 |
Turn on aggressive table parsing. --> |
|
144 |
.TP 15 |
|
5
by Frank Lichtenheld
* QA upload. |
145 |
\-t|\-\-tabstops \fI# \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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. |
|
3
by Stephen M Moraco
* Update Policy Version |
153 |
This filter tries to intuit the original [tn]roff directives, |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
154 |
which can then be recompiled by [tn]roff. |
155 |
.SS "TkMan " |
|
3
by Stephen M Moraco
* Update Policy Version |
156 |
TkMan(1), a hypertext man page browser, uses \fIPolyglotMan \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
157 |
to show man pages without the (usually) useless headers and footers |
3
by Stephen M Moraco
* Update Policy Version |
158 |
on each page. It also collects section and (optionally) subsection |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
3
by Stephen M Moraco
* Update Policy Version |
168 |
text and the tags. See also ASCII. |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
175 |
output through \fIcol \-b \fR also strips away this formatting, |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 " |
|
5.1.1
by Anton Gladky
* New mantainer (closes: #465951) |
182 |
With a simple extension to a HTTP server for Mosaic(1) or other |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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. |
|
5.1.1
by Anton Gladky
* New mantainer (closes: #465951) |
186 |
.SS "XML " |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
187 |
This is appoaching the Docbook DTD, but I'm hoping that someone |
3
by Stephen M Moraco
* Update Policy Version |
188 |
with a real interest in this will polish the tags |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
3
by Stephen M Moraco
* Update Policy Version |
198 |
pages and integrate them better with NeXT's documentation system. |
199 |
Maybe NeXT has its own man page macros that do this. |
|
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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
|
|
5
by Frank Lichtenheld
* QA upload. |
210 |
\fIrman \-f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1 \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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
|
|
5
by Frank Lichtenheld
* QA upload. |
221 |
\fIpcat /usr/catman/a_man/cat1/automount.z | rman \-b \-n automount \-s 1 \-f |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
222 |
latex > automount.man \fR
|
223 |
.br
|
|
224 |
.PP
|
|
5
by Frank Lichtenheld
* QA upload. |
225 |
Alternatively, \fIman 1 automount | rman \-b \-n automount \-s 1 \-f |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 |
|
5
by Frank Lichtenheld
* QA upload. |
232 |
let's assume pregenerated HTML versions of man pages stored in \fI/usr/share/man/html \fR. |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
233 |
Generate these one-by-one with the following form: |
234 |
.br
|
|
5
by Frank Lichtenheld
* QA upload. |
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 |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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
|
|
5
by Frank Lichtenheld
* QA upload. |
241 |
\fIrman \-f html \-r 'http:~/bin/man2html?%s:%s' /usr/share/man/cat1/ls.1 \fR |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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
|
|
3
by Stephen M Moraco
* Update Policy Version |
252 |
The man pager \fIwoman\fR(1) applies its own idea of formatting |
1
by Stephen M Moraco
Import upstream version 3.0.9 |
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 ( \fIphelps@ACM.org \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 $ |