unroff-html-man(1)unroff-html-man(1)NAMEunroff-html-man - back-end to translate manual pages to HTML 2.0
SYNOPSIS
unroff [ -fhtml ] [ -man ] [ file | option... ]
OVERVIEW
When called with the -fhtml and -man options, the troff translator
unroff loads the back-end for converting UNIX manual pages to the
Hypertext Markup Language (HTML) version 2.0.
Please read unroff(1) first for an overview of the Scheme-based, pro‐
grammable troff translator and for a description of the generic options
that exist in addition to -f and -m. The translation of basic troff
requests, special characters, escape sequences, etc. as well as the
HTML-specific options are described in unroff-html(1). For information
about extending and programming unroff also refer to the Unroff Pro‐
grammer's Manual.
OPTIONS
The -man extension provides one new keyword/value option in addition to
those listed in unroff(1) and unroff-html(1):
do-signature (boolean)
If set to 1, a signature is appended to each output file. The
signature is composed of a horizontal rule and a one-line mes‐
sage consisting of version information and date and time. The
default value of this option is 1.
DESCRIPTION
unroff reads and parses its input files (each containing a UNIX manual
page); the HTML output is written to a separate output file for each
input file. The name of an output file is obtained by appending the
suffix “.html” to the name of the corresponding input file. Any docu‐
ment option is ignored if input files are named in the command line.
As usual, the special file name `-' can be used to interpolate standard
input.
If no file name is given in the command line, a manual page is read
from standard input and sent to standard output, unless the document
option is given, in which case the HTML output is written to the speci‐
fied file (with “.html” appended). Example: this call to unroff trans‐
lates two manual pages and creates two corresponding output files,
cc.1.html and send.2.html:
unroff -fhtml -man /usr/man/man1/cc.1 /usr/man/man2/send.2
The following -man macros are recognized and translated (in addition to
any user-defined macros):
.TH .SH .SS .I .B .SB .SM
.BI .BR .IB .IR .RB .RI .TP
.IP .HP .RS .RE .LP .PP .P
In addition, the following Sun-specific macros are silently ignored
(.TX generates an informational message containing its argument):
.TX .IX .DT .PD .UC
The following predefined troff strings are recognized (\*S expands to
the empty string):
\*R \*S \*(lq \*(rq
The title of each HTML document generated is obtained by calling the
primitive substitute (as explained in the Programmer's Manual) with the
value of the option title and the first and second arguments passed to
the initial call to .TH. Thus, the specifiers “%1%” and “%2%” can be
used in the option to interpolate the command (or whatever is docu‐
mented in the manual page) and the section number. If title has not
been specified, the string “Manual page for %1%(%2%)” is taken. As
generating the HTML title element is deferred until the call to .TH,
any macros or other troff requests that produce output must not be used
before the initial .TH.
HTML header elements <h2> and <h3> are created for .SH and .SS
requests. The markup created for the initial NAME section differs in
that the contents of the section (usually a single line) is itself
placed inside a header element.
The font switching macros are based on changes to the fonts `R', `I',
and `B', as explained under FONTS in unroff-html(1). Of course, this
fails if the fonts (which are mounted on startup) are unmounted by
explicit .fp requests. As HTML is lacking the concept of text size,
the macro .SB is just an alias for .B, and .SM simply echoes its argu‐
ments.
The translation rules for .TP and .IP employ a heuristic to determine
whether to generate a definition list or an unordered list: if the
first in a sequence of tagged/indented paragraph macros is called with
a tag consisting of the special character \(bu, a definition list is
begun, otherwise an unordered list. Subsequent invocations cause the
list style to change if appropriate. Use of tagged paragraphs inside
non-filled (pre-formatted) text violates the HTML definition and should
be avoided. A warning message is printed in this and other question‐
able situations.
As hanging tags cannot be realized with HTML 2.0, a kludge is used for
the .HP (hanging paragraph) macro: the macro starts a definition list
(as does the ordinary .TP macro), and everything up to the next request
that causes a break is placed inside the definition tag. This method
obviously fails if no break occurs in subsequent lines, but it works
for the common, idiomatic use of hanging paragraphs in manual pages.
SEE ALSOunroff(1), unroff-html(1), troff(1), man(5 or 7).
Unroff Programmer's Manual.
http://www.informatik.uni-bremen.de/~net/unroff
Berners-Lee, Connolly, et al., HyperText Markup Language Specifica‐
tion—2.0, Internet Draft, Internet Engineering Task Force.
1995/08/23 unroff-html-man(1)
