<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
</PRE>
<H2>NAME</H2><PRE>
man2html - convert UNIX <B>nroff(1)</B> manual pages to HTML format
</PRE>
<H2>SYNOPSIS</H2><PRE>
<B>man2html</B> [<B>-bare</B>] [<B>-belem</B> <I>name</I>] [<B>-botm</B> <I>lines</I>]
[<B>-cgiurl</B> <I>string</I>] [<B>-cgiurlexp</B> <I>expr</I>] [<B>-compress</B>]
[<B>-headmap</B> <I>mapfile</I>] [<B>-help</B>] [<B>-k</B>] [<B>-leftm</B> <I>chars</I>]
[<B>-nodepage</B>] [<B>-noheads</B>] [<B>-pgsize</B> <I>lines</I>] [<B>-seealso</B>]
[<B>-solaris</B>] [<B>-sun</B>] [<B>-title</B> <I>string</I>] [<B>-topm</B> <I>lines</I>]
[<B>-uelem</B> <I>name</I>]
Typical Usage:
<B>man2html</B> [<B>-options</B>] <B><</B> <I>infile</I> <B>></B> <I>outfile</I>
<B>man</B> <I>topic</I> <B>|</B> <B>man2html</B> [<B>-options</B>] <B>></B> <I>outfile</I>
</PRE>
<H2>DESCRIPTION</H2><PRE>
The <B>man2html</B> filter reads formatted nroff text from standard
input (<I>stdin</I>) and writes a HTML document to standard output
(<I>stdout</I>).
The formatted nroff output is surrounded with <B><PRE></B> tags
with the following exceptions/additions:
<B>o</B> Section heads are wrapped in HTML <I>header</I> tags. See the
<B>SECTION</B> <B>HEAD</B> <B>MAP</B> <B>FILE</B> section below for additional
information. The <B>-noheads</B> option can be used to disable
this feature.
<B>o</B> Bold words designated by a "<char><bs><char>" sequences
are wrapped in <B><B></B> tags (or the element specified via
the <B>-belem</B> option).
<B>o</B> Underlined words designated by a "_<bs><char>" sequences
are wrapped in <B><I></B> tags (or the element specified via
the <B>-uelem</B> option).
</PRE>
<H2>OPTIONS</H2><PRE>
<B>-bare</B>
This option will eliminate HTML <B><HEAD></B> and <B><BODY></B> tags
from the output. This is useful when you wish to
incorporate the output into another HTML document.
<B>-belem</B> <I>name</I>
Use <I>name</I> as the name of the element to wrap overstriken
characters. The default is <B>B</B>.
<B>-botm</B> <I>lines</I>
The <I>lines</I> argument specifies the number of lines repre-
senting the bottom margin of the formatted nroff input.
The line count includes any running footers. The
default value is 7.
<B>-cgiurl</B> <I>string</I>
The <I>string</I> argument specifies a template URL for creat-
ing links to other manpages. See the
<B>LINKING</B> <B>TO</B> <B>OTHER</B> <B>MANPAGES</B> section below for additional
information.
<B>-cgiurlexp</B> <I>expr</I>
The <I>expr</I> argument specifies a Perl expression evaluting
to a URL for creating links to other manpages. See the
<B>LINKING</B> <B>TO</B> <B>OTHER</B> <B>MANPAGES</B> section below for additional
information.
<B>-compress</B>
Compress consecutive blank lines into a single line.
<B>-headmap</B> <I>mapfile</I>
The <I>mapfile</I> argument is read to determine which HTML
header tags are to be used for various section heading
in the manpage. See the <B>SECTION</B> <B>HEAD</B> <B>MAP</B> <B>FILE</B> section
below for information on the format of the map file.
<B>-help</B>
Print out a short usage message and then exit immedi-
ately.
<B>-k</B> Process input resulting from a manpage keyword search
(<B>man</B> <B>-k</B>). See the <B>KEYWORD</B> <B>SEARCH</B> section below for
additional information.
<B>-leftm</B> <I>chars</I>
The <I>chars</I> argument specifies the width of the number of
characters making up the left margin of the formatted
nroff input. The default value is 0.
<B>-nodepage</B>
By default, <B>man2html</B> merges multi-page formatted nroff
into a single page. This option may be used to disable
depagination, causing running headers and footers in
the formatted nroff input to be carried over into the
HTML output.
<B>-noheads</B>
By default, <B>man2html</B> wraps section heads in HTML header
tags. See the <B>SECTION</B> <B>HEAD</B> <B>MAP</B> <B>FILE</B> section below for
additional information. This option may be specified
to disabled this feature.
<B>-pgsize</B> <I>lines</I>
The <I>lines</I> argument specifies the number of lines making
up the page size (length) of the formatted nroff input.
The default value is 66.
<B>-seealso</B>
If the <B>-cgiurl</B> option has been specified, then this
option restricts the creation of links to other manual
pages to the <B>SEE</B> <B>ALSO</B> section only.
<B>-solaris</B>
If the <B>-k</B> option has been specified, then this option
modifies its operation to process the alternate manual
page keyword search format produced by the <B>man(1)</B> util-
ity on systems running <I>Solaris</I>. See the <B>KEYWORD</B> <B>SEARCH</B>
section below for additional information.
<B>-sun</B> Do not require a section head to have bold overstriking
in the formatted nroff input. The option is called <B>sun</B>
because it was on a Sun workstation that section heads
in manpages were found to not be overstruck.
<B>-title</B> <I>string</I>
By default, <B>man2html</B> does not generate a HTML title
(<B><TITLE></B>). This option sets the title of the HTML out-
put to the specified <I>string</I>.
<B>-topm</B> <I>lines</I>
The <I>lines</I> 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.
<B>-uelem</B> <I>name</I>
Use <I>name</I> as the name of the element to wrap underscored
characters. The default is <B>I</B>.
</PRE>
<H2>SECTION HEAD MAP FILE</H2><PRE>
The <B>-headmap</B> option may be used to customize which HTML
header tags, <B><H1></B> <B>...</B> <B><H6></B>, are used in manpage section
headings. Normally, <B>man2html</B> treats lines that are flush to
the left margin (<B>-leftm</B>), and contain overstriking (over-
strike check is canceled with the <B>-sun</B> option), as section
heads. However, you can augment/override what HTML header
tags are used for any given section head.
In order to write a section head map file, you will need to
know about <B>perl(1)</B> associative arrays. You do not need to
be an expert in <B>perl</B> to write a map file, however, having
knowledge of <B>perl</B> allows you to be more clever.
<B>Augmenting</B> <B>the</B> <B>Default</B> <B>Map</B>
To add to the default mapping defined by <B>man2html</B>, your map
file will contain lines with the following syntax:
<B>$SectionHead{'<section</B> <B>head</B> <B>text>'}</B> <B>=</B> <B>'<html</B> <B>header</B> <B>tag>';</B>
where
<B><section</B> <B>head</B> <B>text></B>
is the text of the manpage section head. For example:
<B>SYNOPSIS</B> or <B>DESCRIPTION</B>.
<B><html</B> <B>header</B> <B>tag></B>
is the HTML header tag to wrap the section head in.
Legal values are: <B><H1></B>, <B><H2></B>, <B><H3></B>, <B><H4></B>, <B><H5></B>, <B><H6></B>.
<B>Overriding</B> <B>the</B> <B>Default</B> <B>Map</B>
To override the default mapping with your own, then your map
file will have the following syntax:
<B>%SectionHead</B> <B>=</B> <B>(</B>
<B>'<section</B> <B>head</B> <B>text>',</B> <B>'<html</B> <B>header</B> <B>tag>',</B>
<B>'<section</B> <B>head</B> <B>text>',</B> <B>'<html</B> <B>header</B> <B>tag>',</B>
<B>#</B> <B>...</B> <B>More</B> <B>section</B> <B>head/tag</B> <B>pairs</B>
<B>'<section</B> <B>head</B> <B>text>',</B> <B>'<html</B> <B>header</B> <B>tag>',</B>
<B>);</B>
<B>The</B> <B>Default</B> <B>Map</B>
As of this writing, this is the default map used by
<B>man2html</B>:
%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>',
'RETURN VALUE' => '<H2>',
'SECTION.*:' => '<H2>',
'SEE ALSO' => '<H2>',
'STANDARDS CONFORMANCE' => '<H2>',
'STYLE CONVENTION' => '<H2>',
'SYNOPSIS' => '<H2>',
'SYNTAX' => '<H2>',
'WARNINGS' => '<H2>',
'\s+Section.*:' => '<H3>',
);
$HeadFallback = '<H2>'; # Fallback tag if above is not found.
Check the <B>perl</B> source code of <B>man2html</B> for the latest
default mapping.
You can reassign the <B>$HeadFallback</B> 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
<B>%SectionHead</B> map.
<B>Using</B> <B>Regular</B> <B>Expressions</B> <B>in</B> <B>the</B> <B>Map</B> <B>File</B>
You may have noticed unusual characters in the default map
file, like "\s" or "*". The <B>man2html</B> utility actual treats
the <B><section</B> <B>head</B> <B>text></B> as a <B>perl</B> regular expression. If
you are comfortable with <B>perl</B> regular expressions, then you
have their full power to use in your map file.
<I>Caution:</I> The <B>man2html</B> utility already anchors the regular
expression to the beginning of the line with left margin
spacing specified by the <B>-leftm</B> option. Therefore, do not
use the `^' character to anchor your regular expression to
the beginning. However, you may end your expression with a
`<B>$</B>' to anchor it to the end of the line.
Since the <B><section</B> <B>head</B> <B>text></B> is actually a regular expres-
sion, you will have to be careful of special characters if
you want them to be treated literally. Any of the charac-
ters `<B>[</B> <B>]</B> <B>(</B> <B>)</B> <B>.</B> <B>^</B> <B>{</B> <B>}</B> <B>$</B> <B>*</B> <B>?</B> <B>+</B> <B>|</B>' should be escaped by pre-
fixing them by the `<B>\</B>' character if you want <B>perl</B> to treat
them "as is".
<I>Caution:</I> One should use single quotes instead of double
quotes to delimit <B><section</B> <B>head</B> <B>text></B>. This will preserve
any `<B>\</B>' characters for character escaping or when the `<B>\</B>' is
used for special <B>perl</B> character matching sequences (e.g.,
<B>\s</B>, <B>\w</B>, <B>\S</B>).
<B>Other</B> <B>Tid-bits</B> <B>on</B> <B>the</B> <B>Map</B> <B>File</B>
Comments can be inserted in the map file by using the '<B>#</B>'
character. Anything after, and including, the '<B>#</B>' 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 <B><PRE></B> tag.
</PRE>
<H2>LINKING TO OTHER MANPAGES</H2><PRE>
The <B>man2html</B> utility allows the ability to link to other
manpage references. If the <B>-cgiurl</B> option is specified,
<B>man2html</B> will create anchors that link to other manpages.
The URL entered with the <B>-cgiurl</B> option is actually a tem-
plate that determines the actual URL used to link to other
manpages. The following variables are defined during run
time that may be used in the template string:
<B>$title</B>
The title of the manual page referenced.
<B>$section</B>
The section number of the manual page referenced.
<B>$subsection</B>
The subsection of the manual page referenced.
Any other text in the template is preserved "as is".
<I>Caution:</I> The <B>man2html</B> utility evaluates the template string
as a <B>perl</B> string expression. Therefore, one might need to
surround the variable names with '<B>{}</B>' (e.g., <B>${title}</B>) so
that <B>man2html</B> properly recognizes the variable.
<I>Note:</I> If a CGI program calling <B>man2html</B> is actually a shell
script or a <B>perl</B> program, make sure to properly escape the
'<B>$</B>' character in the URL template to avoid variable interpo-
lation 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.
<B>Example1:</B>
The following template string is specified to call a CGI
program to retrieve the appropriate manpage linked to:
<B>/cgi-bin/man.cgi?section=${section}${subsection}&topic=${title}</B>
If the <B>ls(1)</B> manpage is referenced in the <B>SEE</B> <B>ALSO</B> section,
the above template will translate to the following URL:
<B>/cgi-bin/man.cgi?section=1&topic=ls</B>
The actual HTML markup will look like the following:
<B><A</B> <B>HREF="/cgi-bin/man.cgi?section=1&topic=ls">ls(1)</A></B>
<B>Example2:</B>
The following template string is specified to retrieve pre-
converted manpages:
<B>http://foo.org/man$section/$title.$section$subsection.html</B>
If the <B>mount(1M)</B> manpage is referenced, the above template
will translate to the following URL:
<B>http://foo.org/man1/mount.1M.html</B>
The actual HTML markup will look like the following:
<B><A</B> <B>HREF="http://foo.org/man1/mount.1M.html">mount(1M)</A></B>
<B>-cgiurlexp</B>
The option <B>-cgiurlexp</B> is a more general form of the <B>-cgiurl</B>
option. <B>-cgiurlexp</B> allows one to specify a general Perl
expression. For example:
<B>$title=~/^db_/i?"$title.html":"/cgi-bin/man?$title+$section"</B>
A <B>-cgiurl</B> <I>string</I> can be expressed as follows with <B>-cgiurl-</B>
<B>exp</B>:
<B>return</B> <B>"</B><I>string</I><B>"</B>
</PRE>
<H2>KEYWORD SEARCH</H2><PRE>
The <B>man2html</B> utility has the ability to process keyword
search output generated by the <B>man</B> <B>-k</B> or <B>apropos</B> commands,
through the use of the <B>-k</B> option. The <B>man2html</B> utility will
generate an HTML document of the keyword search input having
the following format:
<B>o</B> All manpage references are listed by section.
<B>o</B> Within each section listing, the manpage references are
sorted alphabetically (case-sensitive) in a <B><DL></B> tag.
The manpage references are listed in the <B><DT></B> section,
and the summary text is listed in the <B><DD></B> section.
<B>o</B> Each manpage reference listed is a hyperlink to the
actual manpage as specified by the <B>-cgiurl</B> option.
This ability to process keyword searches gives nice added
functionality to a WWW forms interface to <B>man(1)</B>. Even if
you have statically converted manpages to HTML via another
man->HTML program, you can use <B>man2html</B> and "<B>man</B> <B>-k</B>" to pro-
vide keyword search capabilities easily for your HTML man-
pages.
<B>Processing</B> <B>Keyword</B> <B>Search</B> <B>Results</B>
Unfortunately, there is no standard controlling the format
of keyword search results. The <B>man2html</B> utility tries it
best to handle all the variations. However, the keyword
search results generated by the <I>Solaris</I> operating system is
different enough from other systems that a special command-
line option (<B>-solaris</B>) must be specified to handle its out-
put.
<B>Example</B> <B>of</B> <B>raw</B> <B>Solaris-type</B> <B>keyword</B> <B>search</B> <B>results:</B>
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 fol-
lowing format:
<B><topic></B> <B><actual_manpage></B> <B>(#)</B> <B>-</B> <B>Description</B>
then you need to specify the <B>-solaris</B> option in addition to
the <B>-k</B> option.
</PRE>
<H2>ADDITIONAL NOTES</H2><PRE>
Different systems format manpages differently. Here is a
list of recommended command-line options for certain sys-
tems:
<B>Convex</B>: <defaults should be okay>
<B>HP</B>: <B>-leftm</B> <B>1</B> <B>-topm</B> <B>8</B>
<B>Sun</B>: <B>-sun</B> (and <B>-solaris</B> when using <B>-k</B>)
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
<B>man2html</B> depaginates the text. To avoid this problem,
<B>man2html</B> 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 <B>man2html</B> inserts a blank line in the HTML output.
A manpage cross-reference is detected by the following
pseudo expression: <B>[A-z.-+_]+([0-9][A-z]?)</B>
The <B>man2html</B> utility only recognizes lines with " <B>-</B> " (the
normal separator between manpage references and summary
text) while in keyword search mode.
The <B>man2html</B> utility can be hooked in a CGI script/program
to convert manpages on the fly. This is the reason for the
<B>-cgiurl</B> option.
</PRE>
<H2>LIMITATIONS</H2><PRE>
The order that section head mapping is searched is not
defined. Therefore, if two or more <B><section</B> <B>head</B> <B>text></B> can
match a give manpage section, there is no way to determine
which map tag is chosen.
If <B>-seealso</B> is specified, all xrefs are detected after the
<B>SEE</B> <B>ALSO</B> heading. In other words, sections after <B>SEE</B> <B>ALSO</B>
may contain hyperlinked xrefs.
</PRE>
<H2>BUGS</H2><PRE>
Text that is flush to the left margin, but is not actually a
section head, can be mistaken for a section head. This mis-
take is more likely when the <B>-sun</B> option is in affect.
</PRE>
<H2>VERSION</H2><PRE>
This documentation describes <B>man2html</B> version 3.0.1
</PRE>
<H2>SEE ALSO</H2><PRE>
<B>man(1)</B>, <B>nroff(1)</B>, <B>perl(1)</B>
<I>http://www.oac.uci.edu/indiv/ehood/man2html.html</I>
</PRE>
<H2>AUTHOR</H2><PRE>
<B>Earl</B> <B>Hood</B>
<I>ehood@medusa.acs.uci.edu</I>
</PRE>
<H2>ERRORS AND OMISSIONS</H2><PRE>
Troff version of this document initially created for version
2.1.0 by C. Jeffery Small (<I>jeff@cjsa.com</I>) by copying, refor-
matting, rearranging and partially rewriting the contents of
the ascii text file <B>doc/man2html.txt</B>.
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>