SYNOPSIS
man2html [-bare] [-belem name] [-botm lines] [-cgiurl string]
[-cgiurlexp expr] [-compress] [-headmap mapfile] [-help] [-k]
[-leftm chars] [-nodepage] [-noheads] [-pgsize lines]
[-seealso] [-solaris] [-sun] [-title string] [-topm lines]
[-uelem name]
Typical Usage:
man2html [-options] < infile > outfile
man topic | man2html [-options] > outfile
DESCRIPTION
The man2html filter reads formatted nroff text from standard input
(stdin) and writes a HTML document to standard output (stdout).
The formatted nroff output is surrounded with <PRE> tags with the fol-
lowing exceptions/additions:
o Section heads are wrapped in HTML header tags. See the SEC-
TION HEAD MAP FILE section below for additional information. The
-noheads option can be used to disable this feature.
o Bold words designated by a “<char><bs><char>” sequences are wrapped
in <B> tags (or the element specified via the -belem option).
o Underlined words designated by a “_<bs><char>” sequences are
wrapped in <I> tags (or the element specified via the -uelem
option).
OPTIONS
-bare
This option will eliminate HTML <HEAD> and <BODY> tags from the
output. This is useful when you wish to incorporate the output
into another HTML document.
-belem name
Use name as the name of the element to wrap overstriken charac-
ters. The default is B.
-botm lines
The lines argument specifies the number of lines representing the
bottom margin of the formatted nroff input. The line count
includes any running footers. The default value is 7.
-cgiurl string
The string argument specifies a template URL for creating links to
other manpages. See the LINKING TO OTHER MANPAGES section below
for additional information.
-help
Print out a short usage message and then exit immediately.
-k Process input resulting from a manpage keyword search (man -k).
See the KEYWORD SEARCH section below for additional information.
-leftm chars
The chars argument specifies the width of the number of characters
making up the left margin of the formatted nroff input. The
default value is 0.
-nodepage
By default, man2html merges multi-page formatted nroff into a sin-
gle page. This option may be used to disable depagination, caus-
ing running headers and footers in the formatted nroff input to be
carried over into the HTML output.
-noheads
By default, man2html wraps section heads in HTML header tags. See
the SECTION HEAD MAP FILE section below for additional informa-
tion. This option may be specified to disabled this feature.
-pgsize lines
The lines argument specifies the number of lines making up the
page size (length) of the formatted nroff input. The default
value is 66.
-seealso
If the -cgiurl option has been specified, then this option
restricts the creation of links to other manual pages to the
SEE ALSO section only.
-solaris
If the -k option has been specified, then this option modifies its
operation to process the alternate manual page keyword search for-
mat produced by the man(1) utility on systems running Solaris.
See the KEYWORD SEARCH section below for additional information.
-sun Do not require a section head to have bold overstriking in the
formatted nroff input. The option is called sun because it was on
a Sun workstation that section heads in manpages were found to not
be overstruck.
-title string
By default, man2html does not generate a HTML title (<TITLE>).
This option sets the title of the HTML output to the specified
string.
-topm lines
The lines argument specifies number number of lines representing
the top margin of the formatted nroff input. The line count
includes any running headers. The default value is 7.
perl(1) associative arrays. You do not need to be an expert in perl to
write a map file, however, having knowledge of perl allows you to be
more clever.
Augmenting the Default Map
To add to the default mapping defined by man2html, your map file will
contain lines with the following syntax:
$SectionHead{’<section head text>’} = ‘<html header tag>’;
where
<section head text>
is the text of the manpage section head. For example: SYNOPSIS
or DESCRIPTION.
<html header tag>
is the HTML header tag to wrap the section head in. Legal val-
ues are: <H1>, <H2>, <H3>, <H4>, <H5>, <H6>.
Overriding the Default Map
To override the default mapping with your own, then your map file will
have the following syntax:
%SectionHead = (
‘<section head text>’, ‘<html header tag>’,
‘<section head text>’, ‘<html header tag>’,
# … More section head/tag pairs
‘<section head text>’, ‘<html header tag>’,
);
The Default Map
As of this writing, this is the default map used by man2html:
%SectionHead = (
‘\S.*OPTIONS.*’ => ‘<H2>’,
‘AUTHORS?’ => ‘<H2>’,
‘BUGS’ => ‘<H2>’,
‘COMPATIBILITY’ => ‘<H2>’,
‘DEPENDENCIES’ => ‘<H2>’,
‘DESCRIPTION’ => ‘<H2>’,
‘DIAGNOSTICS’ => ‘<H2>’,
‘ENVIRONMENT’ => ‘<H2>’,
‘ERRORS’ => ‘<H2>’,
‘EXAMPLES’ => ‘<H2>’,
‘EXTERNAL INFLUENCES’ => ‘<H2>’,
‘FILES’ => ‘<H2>’,
‘LIMITATIONS’ => ‘<H2>’,
‘NAME’ => ‘<H2>’,
‘NOTES?’ => ‘<H2>’,
‘OPTIONS’ => ‘<H2>’,
‘REFERENCES’ => ‘<H2>’,
You can reassign the $HeadFallback variable to a different value if you
choose. This value is used as the header tag of a section head if no
matches are found in the %SectionHead map.
Using Regular Expressions in the Map File
You may have noticed unusual characters in the default map file, like
“\s” or “*”. The man2html utility actual treats the
<section head text> as a perl regular expression. If you are comfort-
able with perl regular expressions, then you have their full power to
use in your map file.
Caution: The man2html utility already anchors the regular expression to
the beginning of the line with left margin spacing specified by the
-leftm option. Therefore, do not use the `^’ character to anchor your
regular expression to the beginning. However, you may end your expres-
sion with a `$’ to anchor it to the end of the line.
Since the <section head text> is actually a regular expression, you
will have to be careful of special characters if you want them to be
treated literally. Any of the characters `[ ] ( ) . ^ { } $ * ? + |’
should be escaped by prefixing them by the `\’ character if you want
perl to treat them “as is”.
Caution: One should use single quotes instead of double quotes to
delimit <section head text>. This will preserve any `\’ characters for
character escaping or when the `\’ is used for special perl character
matching sequences (e.g., \s, \w, \S).
Other Tid-bits on the Map File
Comments can be inserted in the map file by using the ‘#’ character.
Anything after, and including, the ‘#’ character is ignored, up to the
end of line.
You might be thinking that the above is quite-a-bit-of-stuff just for
doing manpage section heads. However, you will be surprised how much
better the HTML output looks with header tags, even though, everything
else is in a <PRE> tag.
LINKING TO OTHER MANPAGES
The man2html utility allows the ability to link to other manpage refer-
ences. If the -cgiurl option is specified, man2html will create
anchors that link to other manpages.
The URL entered with the -cgiurl option is actually a template that
determines the actual URL used to link to other manpages. The follow-
ing variables are defined during run time that may be used in the tem-
plate string:
$title The title of the manual page referenced.
$section
template to avoid variable interpolation by the CGI program.
Normally, the URL calls a CGI program (hence the option name), but the
URL can easily link to statically converted documents.
Example1:
The following template string is specified to call a CGI program to
retrieve the appropriate manpage linked to:
/cgi-bin/man.cgi?section=${section}${subsection}&topic=${title}
If the ls(1) manpage is referenced in the SEE ALSO section, the above
template will translate to the following URL:
/cgi-bin/man.cgi?section=1&topic=ls
The actual HTML markup will look like the following:
<A HREF=”/cgi-bin/man.cgi?section=1&topic=ls”>ls(1)</A>
Example2:
The following template string is specified to retrieve pre-converted
manpages:
http://foo.org/man$section/$title.$section$subsection.html
If the mount(1M) manpage is referenced, the above template will trans-
late to the following URL:
http://foo.org/man1/mount.1M.html
The actual HTML markup will look like the following:
<A HREF=”http://foo.org/man1/mount.1M.html”>mount(1M)</A>
-cgiurlexp
The option -cgiurlexp is a more general form of the -cgiurl option.
-cgiurlexp allows one to specify a general Perl expression. For exam-
ple:
$title=~/^db_/i?”$title.html”:”/cgi-bin/man?$title+$section”
A -cgiurl string can be expressed as follows with -cgiurlexp:
return “string”
KEYWORD SEARCH
The man2html utility has the ability to process keyword search output
generated by the man -k or apropos commands, through the use of the -k
option. The man2html utility will generate an HTML document of the
keyword search input having the following format:
your HTML manpages.
Processing Keyword Search Results
Unfortunately, there is no standard controlling the format of keyword
search results. The man2html utility tries it best to handle all the
variations. However, the keyword search results generated by the
Solaris operating system is different enough from other systems that a
special command-line option (-solaris) must be specified to handle its
output.
Example of raw Solaris-type keyword search results:
strcpy strcpy (9f) - copy a string from one location to another.
strcpy string (3c) - string operations
strncpy strcpy (9f) - copy a string from one location to another.
strncpy string (3c) - string operations
If keyword search results on your systems appear in the following for-
mat:
<topic> <actual_manpage> (#) - Description
then you need to specify the -solaris option in addition to the -k
option.
ADDITIONAL NOTES
Different systems format manpages differently. Here is a list of rec-
ommended command-line options for certain systems:
Convex: <defaults should be okay>
HP: -leftm 1 -topm 8
Sun: -sun (and -solaris when using -k)
Some line spacing gets lost in the formatted nroff since the spacing
would occur in the middle of a page break. This can cause text to be
merged that shouldn’t be merged when man2html depaginates the text. To
avoid this problem, man2html keeps track of the margin indent right
before and after a page break. If the margin width of the line after
the page break is less than the line before the page break, then
man2html inserts a blank line in the HTML output.
A manpage cross-reference is detected by the following pseudo expres-
sion: [A-z.-+_]+([0-9][A-z]?)
The man2html utility only recognizes lines with ” - ” (the normal sepa-
rator between manpage references and summary text) while in keyword
search mode.
The man2html utility can be hooked in a CGI script/program to convert
manpages on the fly. This is the reason for the -cgiurl option.
LIMITATIONS
The order that section head mapping is searched is not defined. There-
SEE ALSO
man(1), nroff(1), perl(1)
http://www.oac.uci.edu/indiv/ehood/man2html.html
AUTHOR
Earl Hood
ehood@medusa.acs.uci.edu
ERRORS AND OMISSIONS
Troff version of this document initially created for version 2.1.0 by
C. Jeffery Small (jeff@cjsa.com) by copying, reformatting, rearranging
and partially rewriting the contents of the ascii text file
doc/man2html.txt.
97/08/12 MAN2HTML(1)