| 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 $ |