1 .\" sccsid = "@(#) man2html.1 1.2 08/12/97"
3 .\" ================================================
4 .\" ARGUMENT MACRO: .Ar "arg" [B]
6 .ie
\a\\$2
\aB
\a \%\fB\\$1\fR
9 .\" ================================================
10 .\" BRACKETED ARGUMENT MACRO: .Br "arg" [B]
12 .ie
\a\\$2
\aB
\a \%[\|\fB\\$1\fR\|]
13 .el \%[\|\fI\\$1\fR\|]
15 .\" ================================================
16 .\" OPTION FLAG MACRO .Of -x [arg]
18 .ie \\n(.$==1 \%[\|\fB\\$1\fR\|]
19 .el .if \\n(.$==2 \%[\|\fB\\$1\fR\0\fI\fI\\$2\fR\|]
21 .\" ================================================
22 .\" SYNOPSIS START MACRO
31 .\" ================================================
32 .\" SYNOPSIS END MACRO
37 .\" ================================================
40 .TH MAN2HTML 1 "97/08/12"
43 man2html \- convert UNIX nroff(1) manual pages to HTML format
86 filter reads formatted nroff text from standard input
88 and writes a \s-1HTML\s+1 document to standard output
91 The formatted nroff output is surrounded with
93 tags with the following exceptions/additions:
99 \(bu Section heads are wrapped in \s-1HTML\s+1
103 .B "\s-1SECTION\ HEAD\ MAP\ FILE\s+1"
104 section below for additional information.
107 option can be used to disable this feature.
113 \(bu Bold words designated by a \%"<char><bs><char>"
114 sequences are wrapped in
116 tags (or the element specified via the
124 \(bu Underlined words designated by a \%"_<bs><char>"
125 sequences are wrapped in
127 tags (or the element specified via the
136 This option will eliminate \s-1HTML\s+1
140 tags from the output.
141 This is useful when you wish to incorporate the output into another
142 \s-1HTML\s+1 document.
147 as the name of the element to wrap overstriken characters.
148 The default is \fBB\fR.
153 argument specifies the number of lines representing the bottom
154 margin of the formatted nroff input.
155 The line count includes any running footers.
156 The default value is 7.
161 argument specifies a template \s-1URL\s+1 for creating links to other manpages.
163 .B "\s-1LINKING\ TO\ OTHER\ MANPAGES\s+1"
164 section below for additional information.
166 .BI -cgiurlexp\0 expr
169 argument specifies a Perl expression evaluting to a \s-1URL\s+1 for
170 creating links to other manpages.
172 .B "\s-1LINKING\ TO\ OTHER\ MANPAGES\s+1"
173 section below for additional information.
176 Compress consecutive blank lines into a single line.
178 .BI -headmap\0 mapfile
181 argument is read to determine which \s-1HTML\s+1
182 header tags are to be used for various section heading in the manpage.
184 .B "\s-1SECTION\ HEAD\ MAP\ FILE\s+1"
185 section below for information on the format of the map file.
188 Print out a short usage message and then exit immediately.
191 Process input resulting from a manpage keyword search
194 .B "\s-1KEYWORD\ SEARCH\s+1"
195 section below for additional information.
200 argument specifies the width of the number of characters making
201 up the left margin of the formatted nroff input.
202 The default value is 0.
207 merges multi-page formatted nroff into a single page.
208 This option may be used to disable depagination, causing
209 running headers and footers in the formatted nroff input
210 to be carried over into the \s-1HTML\s+1 output.
215 wraps section heads in \s-1HTML\s+1
218 .B "\s-1SECTION\ HEAD\ MAP\ FILE\s+1"
219 section below for additional information.
220 This option may be specified to disabled this feature.
225 argument specifies the number of lines making up the page size (length)
226 of the formatted nroff input.
227 The default value is 66.
232 option has been specified, then this option restricts the
233 creation of links to other manual pages to the
234 .B "\%\s-1SEE\ ALSO\s+1"
240 option has been specified, then this option modifies its operation
241 to process the alternate manual page keyword search format produced
244 utility on systems running
247 .B "\s-1KEYWORD\ SEARCH\s+1"
248 section below for additional information.
251 Do not require a section head to have bold overstriking in the
252 formatted nroff input.
255 because it was on a Sun workstation that section heads in
256 manpages were found to not be overstruck.
261 does not generate a \s-1HTML\s+1 title
262 .RB ( \s-1<TITLE>\s+1 ).
263 This option sets the title of the \s-1HTML\s+1 output to the specified
269 argument specifies number number of lines representing the
270 top margin of the formatted nroff input.
271 The line count includes any running headers.
272 The default value is 7.
277 as the name of the element to wrap underscored characters.
278 The default is \fBI\fR.
280 .SH "SECTION HEAD MAP FILE"
285 option may be used to customize which \s-1HTML\s+1 header tags,
286 .BR "\s-1<H1>\s+1 ... \s-1<H6>\s+1" ,
287 are used in manpage section headings.
290 treats lines that are flush to the left margin
292 and contain overstriking (overstrike check is canceled with the
294 option), as section heads.
295 However, you can augment/override what \s-1HTML\s+1 header tags are used for
296 any given section head.
298 In order to write a section head map file, you will need to know about
301 You do not need to be an expert in
303 to write a map file, however, having knowledge of
305 allows you to be more clever.
307 .SS "Augmenting the Default Map"
309 To add to the default mapping defined by
311 your map file will contain lines with the following syntax:
314 .B "$SectionHead{'<section head text>'} = '<html header tag>';"
318 .IP "\fB\%<section\ head\ text>\fR"
319 is the text of the manpage section head.
323 .BR \s-1DESCRIPTION\s+1 .
324 .IP "\fB\%<html\ header\ tag>\fR"
325 is the \s-1HTML\s+1 header tag to wrap the section head in.
333 .SS "Overriding the Default Map"
334 To override the default mapping with your own, then your map file will
335 have the following syntax:
342 \&'<section head text>', '<html header tag>',
343 \&'<section head text>', '<html header tag>',
344 \&# ... More section head/tag pairs
345 \&'<section head text>', '<html header tag>',
350 .SS "The Default Map"
352 As of this writing, this is the default map used by
361 \&'\\S.*OPTIONS.*' => '<H2>',
362 \&'AUTHORS?' => '<H2>',
364 \&'COMPATIBILITY' => '<H2>',
365 \&'DEPENDENCIES' => '<H2>',
366 \&'DESCRIPTION' => '<H2>',
367 \&'DIAGNOSTICS' => '<H2>',
368 \&'ENVIRONMENT' => '<H2>',
369 \&'ERRORS' => '<H2>',
370 \&'EXAMPLES' => '<H2>',
371 \&'EXTERNAL INFLUENCES' => '<H2>',
373 \&'LIMITATIONS' => '<H2>',
375 \&'NOTES?' => '<H2>',
376 \&'OPTIONS' => '<H2>',
377 \&'REFERENCES' => '<H2>',
378 \&'RETURN VALUE' => '<H2>',
379 \&'SECTION.*:' => '<H2>',
380 \&'SEE ALSO' => '<H2>',
381 \&'STANDARDS CONFORMANCE' => '<H2>',
382 \&'STYLE CONVENTION' => '<H2>',
383 \&'SYNOPSIS' => '<H2>',
384 \&'SYNTAX' => '<H2>',
385 \&'WARNINGS' => '<H2>',
386 \&'\\s+Section.*:' => '<H3>',
389 $HeadFallback = '\s-1<H2>\s+1'; # Fallback tag if above is not found.
398 for the latest default mapping.
402 variable to a different value if you choose.
403 This value is used as the header tag of a section head if
404 no matches are found in the \%\fB%SectionHead\fR map.
405 .SS "Using Regular Expressions in the Map File"
407 You may have noticed unusual characters in the default map file, like
411 utility actual treats the
412 .B "\%<section\ head\ text>"
416 If you are comfortable with
418 regular expressions, then you have their full power to use
424 utility already anchors the regular expression to the beginning of the
425 line with left margin spacing specified by the
428 Therefore, do not use the `\fB\fR^' character to anchor your regular
429 expression to the beginning.
430 However, you may end your expression with a `\fB$\fR' to anchor it to
434 .B "\%<section\ head\ text>"
435 is actually a regular expression, you will have to be careful of
436 special characters if you want them to be treated literally.
437 Any of the characters
438 .RB ` "[ ] ( ) . ^ { } $ * ? + \\ |" '
439 should be escaped by prefixing them by the
440 \&`\fB\\\fR' character if you want
442 to treat them "as is".
445 One should use single quotes instead of double quotes to delimit
446 .BR "\%<section\ head\ text>" .
447 This will preserve any `\fB\\\fR' characters for character escaping
448 or when the `\fB\\\fR' is used for special
450 character matching sequences (e.g., \fB\\s\fR, \fB\\w\fR, \fB\\S\fR).
451 .SS "Other Tid-bits on the Map File"
453 Comments can be inserted in the map file by using the '\fB#\fR'
455 Anything after, and including, the '\fB#\fR' character is ignored,
456 up to the end of line.
458 You might be thinking that the above is quite-a-bit-of-stuff just for
459 doing manpage section heads.
460 However, you will be surprised how much better the \s-1HTML\s+1 output looks
461 with header tags, even though, everything else is in a
465 .SH "LINKING TO OTHER MANPAGES"
470 utility allows the ability to link to other manpage references.
475 will create anchors that link to other manpages.
477 The \s-1URL\s+1 entered with the
479 option is actually a template that determines the actual \s-1URL\s+1 used to
480 link to other manpages.
481 The following variables are defined during run time that may be used in
486 The title of the manual page referenced.
488 The section number of the manual page referenced.
489 .IP \fB$subsection\fR
490 The subsection of the manual page referenced.
493 Any other text in the template is preserved "as is".
498 utility evaluates the template string as a
501 Therefore, one might need to surround the variable names with
502 \&'\fB{\|}\fR' (e.g.,
506 properly recognizes the variable.
509 If a \s-1CGI\s+1 program calling
511 is actually a shell script or a
513 program, make sure to properly escape the '\fB$\fR' character
514 in the \s-1URL\s+1 template to avoid variable interpolation by the \s-1CGI\s+1
517 Normally, the \s-1URL\s+1 calls a \s-1CGI\s+1 program (hence the option name),
518 but the \s-1URL\s+1 can easily link to statically converted documents.
521 The following template string is specified to call a \s-1CGI\s+1 program to
522 retrieve the appropriate manpage linked to:
525 .B "/cgi-bin/man.cgi?section=${section}${subsection}&topic=${title}"
530 manpage is referenced in the
532 section, the above template will translate to the following \s-1URL\s+1:
534 .B "/cgi-bin/man.cgi?section=1&topic=ls"
536 The actual \s-1HTML\s+1 markup will look like the following:
538 \fB<A\ HREF="/cgi-bin/man.cgi?section=1&topic=ls">ls(1)</A>\fR
541 The following template string is specified to retrieve pre-converted
544 .B "http://foo.org/man$section/$title.$section$subsection.html"
548 manpage is referenced, the above template will translate to the
549 following \s-1URL\s+1:
551 .B "http://foo.org/man1/mount.1M.html"
553 The actual \s-1HTML\s+1 markup will look like the following:
555 \fB<A HREF="http://foo.org/man1/mount.1M.html">mount(1M)</A>\fR
559 is a more general form of the
563 allows one to specify a general Perl expression. For example:
565 \fB$title=~/^db_/i?"$title.html":"/cgi-bin/man?$title+$section"\fR
570 can be expressed as follows with \fB-cgiurlexp\fR:
572 \fBreturn "\fIstring\fB"\fR
579 utility has the ability to process keyword search output generated
580 by the \%\fBman\ -k\fR or \%\fBapropos\fR commands, through the
586 utility will generate an \s-1HTML\s+1 document of the keyword search input
587 having the following format:
593 \(bu All manpage references are listed by section.
599 \(bu Within each section listing, the manpage references
600 are sorted alphabetically (case-sensitive) in a
603 The manpage references are listed in the
605 section, and the summary text is listed in the
613 \(bu Each manpage reference listed is a hyperlink to the
614 actual manpage as specified by the
621 This ability to process keyword searches gives nice added functionality
622 to a \s-1WWW\s+1 forms interface to
624 Even if you have statically converted manpages to \s-1HTML\s+1 via another
625 man->\s-1HTML\s+1 program, you can use
627 and "\fBman\ -k\fR" to provide keyword search capabilities easily for
628 your \s-1HTML\s+1 manpages.
629 .SS "Processing Keyword Search Results"
632 Unfortunately, there is no standard controlling the format of keyword
636 utility tries it best to handle all the variations.
637 However, the keyword search results generated by the
639 operating system is different enough from other systems that a
640 special command-line option
642 must be specified to handle its output.
643 .SS "Example of raw Solaris-type keyword search results:"
648 strcpy strcpy (9f) - copy a string from one location to another.
649 strcpy string (3c) - string operations
650 strncpy strcpy (9f) - copy a string from one location to another.
651 strncpy string (3c) - string operations
655 If keyword search results on your systems appear in the following format:
658 .B "<topic> <actual_manpage> (#) - Description"
661 then you need to specify the
663 option in addition to the
666 .SH "ADDITIONAL NOTES"
669 Different systems format manpages differently.
670 Here is a list of recommended command-line options for certain systems:
676 \fBConvex\fR: <defaults should be okay>
677 \fBHP\fR: \fB-leftm 1 -topm 8\fR
678 \fBSun\fR: \fB-sun\fR (and \fB-solaris\fR when using \fB-k\fR)
682 Some line spacing gets lost in the formatted nroff since the
683 spacing would occur in the middle of a page break.
684 This can cause text to be merged that shouldn't be merged when
686 depaginates the text.
687 To avoid this problem,
689 keeps track of the margin indent right before and after a page break.
690 If the margin width of the line after the page break is less than the
691 line before the page break, then
693 inserts a blank line in the \s-1HTML\s+1 output.
695 A manpage cross-reference is detected by the following pseudo expression:
696 \%\fB[A-z.-+_]+([0-9][A-z]?)\fR
700 utility only recognizes lines with "\fB - \fR" (the normal separator
701 between manpage references and summary text) while in keyword
706 utility can be hooked in a \s-1CGI\s+1 script/program to convert manpages
708 This is the reason for the
714 The order that section head mapping is searched is not defined.
715 Therefore, if two or more
716 .B "\%<section\ head\ text>"
717 can match a give manpage section, there is no way to determine
718 which map tag is chosen.
722 is specified, all xrefs are detected after the
725 In other words, sections after
727 may contain hyperlinked xrefs.
731 Text that is flush to the left margin, but is not actually a
732 section head, can be mistaken for a section head.
733 This mistake is more likely when the
738 This documentation describes
747 .I http://www.oac.uci.edu/indiv/ehood/man2html.html
752 .I ehood@medusa.acs.uci.edu
754 .SH "ERRORS AND OMISSIONS"
756 Troff version of this document initially created for version 2.1.0
758 .RI ( jeff@cjsa.com )
759 by copying, reformatting, rearranging and partially rewriting
760 the contents of the ascii text file
761 .BR doc/man2html.txt .