doc/man2html.M

   1 .\" sccsid = "@(#)  man2html.1  1.2  08/12/97"
   2 .\"
   3 .\" ================================================
   4 .\" ARGUMENT MACRO:             .Ar "arg" [B]
   5 .de Ar
   6 .ie \a\\$2\aB\a  \%\fB\\$1\fR
   7 .el              \%\fI\\$1\fR
   8 ..
   9 .\" ================================================
  10 .\" BRACKETED ARGUMENT MACRO:   .Br "arg" [B]
  11 .de Br
  12 .ie \a\\$2\aB\a  \%[\|\fB\\$1\fR\|]
  13 .el              \%[\|\fI\\$1\fR\|]
  14 ..
  15 .\" ================================================
  16 .\" OPTION FLAG MACRO           .Of -x [arg]
  17 .de Of
  18 .ie \\n(.$==1      \%[\|\fB\\$1\fR\|]
  19 .el .if \\n(.$==2  \%[\|\fB\\$1\fR\0\fI\fI\\$2\fR\|]
  20 ..
  21 .\" ================================================
  22 .\" SYNOPSIS START MACRO
  23 .de Ss                          .Ss name
  24 .na
  25 .nr aA \w\a\\$1\\0\au
  26 .in +\\n(aAu
  27 'ti -\\n(aAu
  28 .ta  \\n(aAu
  29 \&\fB\\$1\fR\t\c
  30 ..
  31 .\" ================================================
  32 .\" SYNOPSIS END MACRO
  33 .de Se                          .Se
  34 .ad
  35 .in
  36 ..
  37 .\" ================================================
  38 .\"
  39 .\"
  40 .TH MAN2HTML 1 "97/08/12"
  41 .SH NAME
  42 .na
  43 man2html \- convert UNIX nroff(1) manual pages to HTML format
  44 .SH SYNOPSIS
  45 .na
  46 .Ss man2html
  47 .Of -bare
  48 .Of -belem name
  49 .Of -botm lines
  50 .Of -cgiurl string
  51 .Of -cgiurlexp expr
  52 .Of -compress
  53 .Of -headmap mapfile
  54 .Of -help
  55 .Of -k
  56 .Of -leftm chars
  57 .Of -nodepage
  58 .Of -noheads
  59 .Of -pgsize lines
  60 .Of -seealso
  61 .Of -solaris
  62 .Of -sun
  63 .Of -title string
  64 .Of -topm lines
  65 .Of -uelem name
  66 .Se
  67 .sp 2
  68 Typical Usage:
  69 .sp
  70 .Ss man2html
  71 .Of -options
  72 .BI "\0<\0" infile
  73 .BI "\0\0>\0" outfile
  74 .Se
  75 .sp
  76 .B man
  77 .I topic
  78 .B | man2html
  79 .Of -options
  80 .BI "\0>\0" outfile
  81 .\"
  82 .SH DESCRIPTION
  83 .na
  84 The
  85 .B man2html
  86 filter reads formatted nroff text from standard input
  87 .RI ( stdin )
  88 and writes a \s-1HTML\s+1 document to standard output
  89 .RI ( stdout ).
  90 .LP
  91 The formatted nroff output is surrounded with
  92 .B \s-1<PRE>\s+1
  93 tags with the following exceptions/additions:
  94 .RS 4n
  95 .LP
  96 .na
  97 'ti -2n
  98 'ta  2n
  99 \(bu    Section heads are wrapped in \s-1HTML\s+1
 100 .I header
 101 tags.
 102 See the
 103 .B "\s-1SECTION\ HEAD\ MAP\ FILE\s+1"
 104 section below for additional information.
 105 The
 106 .B \%-noheads
 107 option can be used to disable this feature.
 108 .ad
 109 .LP
 110 .na
 111 'ti -2n
 112 'ta  2n
 113 \(bu    Bold words designated by a \%"<char><bs><char>"
 114 sequences are wrapped in
 115 .B \s-1<B>\s+1
 116 tags (or the element specified via the
 117 .B \%-belem
 118 option).
 119 .ad
 120 .LP
 121 .na
 122 'ti -2n
 123 'ta  2n
 124 \(bu    Underlined words designated by a \%"_<bs><char>"
 125 sequences are wrapped in
 126 .B \s-1<I>\s+1
 127 tags (or the element specified via the
 128 .B \%-uelem
 129 option).
 130 .ad
 131 .RE
 132 .SH OPTIONS
 133 .na
 134 .TP 0.5i
 135 .B -bare
 136 This option will eliminate \s-1HTML\s+1
 137 .B \s-1<HEAD>\s+1
 138 and
 139 .B \s-1<BODY>\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.
 143 .TP 0.5i
 144 .BI -belem\0 name
 145 Use
 146 .I name
 147 as the name of the element to wrap overstriken characters.
 148 The default is \fBB\fR.
 149 .TP 0.5i
 150 .BI -botm\0 lines
 151 The
 152 .I lines
 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.
 157 .TP 0.5i
 158 .BI -cgiurl\0 string
 159 The
 160 .I string
 161 argument specifies a template \s-1URL\s+1 for creating links to other manpages.
 162 See the
 163 .B "\s-1LINKING\ TO\ OTHER\ MANPAGES\s+1"
 164 section below for additional information.
 165 .TP 0.5i
 166 .BI -cgiurlexp\0 expr
 167 The
 168 .I expr
 169 argument specifies a Perl expression evaluting to a \s-1URL\s+1 for
 170 creating links to other manpages.
 171 See the
 172 .B "\s-1LINKING\ TO\ OTHER\ MANPAGES\s+1"
 173 section below for additional information.
 174 .TP 0.5i
 175 .B -compress
 176 Compress consecutive blank lines into a single line.
 177 .TP 0.5i
 178 .BI -headmap\0 mapfile
 179 The
 180 .I 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.
 183 See the
 184 .B "\s-1SECTION\ HEAD\ MAP\ FILE\s+1"
 185 section below for information on the format of the map file.
 186 .TP 0.5i
 187 .B -help
 188 Print out a short usage message and then exit immediately.
 189 .TP 0.5i
 190 .B -k
 191 Process input resulting from a manpage keyword search
 192 .RB ( "man\ -k" ).
 193 See the
 194 .B "\s-1KEYWORD\ SEARCH\s+1"
 195 section below for additional information.
 196 .TP 0.5i
 197 .BI -leftm\0 chars
 198 The
 199 .I chars
 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.
 203 .TP 0.5i
 204 .B -nodepage
 205 By default,
 206 .B man2html
 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.
 211 .TP 0.5i
 212 .B -noheads
 213 By default,
 214 .B man2html
 215 wraps section heads in \s-1HTML\s+1
 216 header tags.
 217 See the
 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.
 221 .TP 0.5i
 222 .BI -pgsize\0 lines
 223 The
 224 .I lines
 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.
 228 .TP 0.5i
 229 .B -seealso
 230 If the
 231 .B -cgiurl
 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"
 235 section only.
 236 .TP 0.5i
 237 .B -solaris
 238 If the
 239 .B -k
 240 option has been specified, then this option modifies its operation
 241 to process the alternate manual page keyword search format produced
 242 by the
 243 .BR man (1)
 244 utility on systems running
 245 .IR Solaris .
 246 See the
 247 .B "\s-1KEYWORD\ SEARCH\s+1"
 248 section below for additional information.
 249 .TP 0.5i
 250 .B -sun
 251 Do not require a section head to have bold overstriking in the
 252 formatted nroff input.
 253 The option is called
 254 .B \%sun
 255 because it was on a Sun workstation that section heads in
 256 manpages were found to not be overstruck.
 257 .TP 0.5i
 258 .BI -title\0 string
 259 By default,
 260 .B man2html
 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
 264 .IR string .
 265 .TP 0.5i
 266 .BI -topm\0 lines
 267 The
 268 .I lines
 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.
 273 .TP 0.5i
 274 .BI -uelem\0 name
 275 Use
 276 .I name
 277 as the name of the element to wrap underscored characters.
 278 The default is \fBI\fR.
 279 .\"
 280 .SH "SECTION HEAD MAP FILE"
 281 .na
 282 .LP
 283 The
 284 .B \%-headmap
 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.
 288 Normally,
 289 .B man2html
 290 treats lines that are flush to the left margin
 291 .RB ( -leftm ),
 292 and contain overstriking (overstrike check is canceled with the
 293 .B -sun
 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.
 297 .LP
 298 In order to write a section head map file, you will need to know about
 299 .BR perl (1)
 300 associative arrays.
 301 You do not need to be an expert in
 302 .B perl
 303 to write a map file, however, having knowledge of
 304 .B perl
 305 allows you to be more clever.
 306 .\"
 307 .SS "Augmenting the Default Map"
 308 .LP
 309 To add to the default mapping defined by
 310 .BR man2html ,
 311 your map file will contain lines with the following syntax:
 312 .sp
 313 .if t .RS 4n
 314 .B "$SectionHead{'<section head text>'} = '<html header tag>';"
 315 .if t .RE
 316 .sp
 317 where
 318 .IP "\fB\%<section\ head\ text>\fR"
 319 is the text of the manpage section head.
 320 For example:
 321 .B  \s-1SYNOPSIS\s+1
 322 or
 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.
 326 Legal values are:
 327 .BR \s-1<H1>\s+1 ,
 328 .BR \s-1<H2>\s+1 ,
 329 .BR \s-1<H3>\s+1 ,
 330 .BR \s-1<H4>\s+1 ,
 331 .BR \s-1<H5>\s+1 ,
 332 .BR \s-1<H6>\s+1 .
 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:
 336 .sp
 337 .RS 4n
 338 .ft B
 339 .nf
 340 .ne 6v
 341 %SectionHead = (
 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>',
 346 );
 347 .fi
 348 .ft
 349 .RE
 350 .SS "The Default Map"
 351 .LP
 352 As of this writing, this is the default map used by
 353 .BR man2html :
 354 .RS 4n
 355 .sp
 356 .ft C
 357 .nf
 358 .ne 29v
 359 %SectionHead = (
 360 .ps -1
 361     \&'\\S.*OPTIONS.*'             => '<H2>',
 362     \&'AUTHORS?'                  => '<H2>',
 363     \&'BUGS'                      => '<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>',
 372     \&'FILES'                     => '<H2>',
 373     \&'LIMITATIONS'               => '<H2>',
 374     \&'NAME'                      => '<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>',
 387 .ps +1
 388 );
 389 $HeadFallback = '\s-1<H2>\s+1';  # Fallback tag if above is not found.
 390 .fi
 391 .ft
 392 .RE
 393 .LP
 394 Check the
 395 .B perl
 396 source code of
 397 .B man2html
 398 for the latest default mapping.
 399 .LP
 400 You can reassign the
 401 .B \%$HeadFallback
 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"
 406 .LP
 407 You may have noticed unusual characters in the default map file, like
 408 "\\s" or "*".
 409 The
 410 .B man2html
 411 utility actual treats the
 412 .B "\%<section\ head\ text>"
 413 as a
 414 .B perl
 415 regular expression.
 416 If you are comfortable with
 417 .B perl
 418 regular expressions, then you have their full power to use
 419 in your map file.
 420 .LP
 421 .I Caution:
 422 The
 423 .B man2html
 424 utility already anchors the regular expression to the beginning of the
 425 line with left margin spacing specified by the
 426 .B \%-leftm
 427 option.
 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
 431 the end of the line.
 432 .LP
 433 Since the
 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
 441 .B perl
 442 to treat them "as is".
 443 .LP
 444 .I Caution:
 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
 449 .B perl
 450 character matching sequences (e.g.,  \fB\\s\fR, \fB\\w\fR, \fB\\S\fR).
 451 .SS "Other Tid-bits on the Map File"
 452 .LP
 453 Comments can be inserted in the map file by using the '\fB#\fR'
 454 character.
 455 Anything after, and including, the '\fB#\fR' character is ignored,
 456 up to the end of line.
 457 .LP
 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
 462 .B \s-1<PRE>\s+1
 463 tag.
 464 .\"
 465 .SH "LINKING TO OTHER MANPAGES"
 466 .na
 467 .LP
 468 The
 469 .B man2html
 470 utility allows the ability to link to other manpage references.
 471 If the
 472 .B \%-cgiurl
 473 option is specified,
 474 .B man2html
 475 will create anchors that link to other manpages.
 476 .LP
 477 The \s-1URL\s+1 entered with the
 478 .B \%-cgiurl
 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
 482 the template string:
 483 .sp
 484 .RS 4n
 485 .IP \fB$title\fR
 486 The title of the manual page referenced.
 487 .IP \fB$section\fR
 488 The section number of the manual page referenced.
 489 .IP \fB$subsection\fR
 490 The subsection of the manual page referenced.
 491 .RE
 492 .LP
 493 Any other text in the template is preserved "as is".
 494 .LP
 495 .I Caution:
 496 The
 497 .B man2html
 498 utility evaluates the template string as a
 499 .B perl
 500 string expression.
 501 Therefore, one might need to surround the variable names with
 502 \&'\fB{\|}\fR' (e.g.,
 503 .BR ${\|title\|}\| )
 504 so that
 505 .B man2html
 506 properly recognizes the variable.
 507 .LP
 508 .I Note:
 509 If a \s-1CGI\s+1 program calling
 510 .B man2html
 511 is actually a shell script or a
 512 .B perl
 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
 515 program.
 516 .LP
 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.
 519 .SS "Example1:"
 520 .LP
 521 The following template string is specified to call a \s-1CGI\s+1 program to
 522 retrieve the appropriate manpage linked to:
 523 .LP
 524 .nf
 525 .B "/cgi-bin/man.cgi?section=${section}${subsection}&topic=${title}"
 526 .fi
 527 .LP
 528 If the
 529 .BR ls (1)
 530 manpage is referenced in the
 531 .B "SEE ALSO"
 532 section, the above template will translate to the following \s-1URL\s+1:
 533 .LP
 534 .B "/cgi-bin/man.cgi?section=1&topic=ls"
 535 .LP
 536 The actual \s-1HTML\s+1 markup will look like the following:
 537 .LP
 538 \fB<A\ HREF="/cgi-bin/man.cgi?section=1&topic=ls">ls(1)</A>\fR
 539 .SS "Example2:"
 540 .LP
 541 The following template string is specified to retrieve pre-converted
 542 manpages:
 543 .LP
 544 .B "http://foo.org/man$section/$title.$section$subsection.html"
 545 .LP
 546 If the
 547 .BR mount (1M)
 548 manpage is referenced, the above template will translate to the
 549 following \s-1URL\s+1:
 550 .LP
 551 .B "http://foo.org/man1/mount.1M.html"
 552 .LP
 553 The actual \s-1HTML\s+1 markup will look like the following:
 554 .LP
 555 \fB<A HREF="http://foo.org/man1/mount.1M.html">mount(1M)</A>\fR
 556 .SS "-cgiurlexp"
 557 The option
 558 .B \%-cgiurlexp
 559 is a more general form of the
 560 .B \%-cgiurl
 561 option.
 562 .B \%-cgiurlexp
 563 allows one to specify a general Perl expression.  For example:
 564 .LP
 565 \fB$title=~/^db_/i?"$title.html":"/cgi-bin/man?$title+$section"\fR
 566 .LP
 567 A
 568 .B \%-cgiurl
 569 .I string
 570 can be expressed as follows with \fB-cgiurlexp\fR:
 571 .LP
 572 \fBreturn "\fIstring\fB"\fR
 573 .\"
 574 .SH "KEYWORD SEARCH"
 575 .na
 576 .LP
 577 The
 578 .B man2html
 579 utility has the ability to process keyword search output generated
 580 by the \%\fBman\ -k\fR or \%\fBapropos\fR commands, through the
 581 use of the
 582 .B -k
 583 option.
 584 The
 585 .B man2html
 586 utility will generate an \s-1HTML\s+1 document of the keyword search input
 587 having the following format:
 588 .RS 4n
 589 .LP
 590 .na
 591 'ti -2n
 592 'ta  2n
 593 \(bu    All manpage references are listed by section.
 594 .ad
 595 .LP
 596 .na
 597 'ti -2n
 598 'ta  2n
 599 \(bu    Within each section listing, the manpage references
 600 are sorted alphabetically (case-sensitive) in a
 601 .B \s-1<DL>\s+1
 602 tag.
 603 The manpage references are listed in the
 604 .B \s-1<DT>\s+1
 605 section, and the summary text is listed in the
 606 .B \s-1<DD>\s+1
 607 section.
 608 .ad
 609 .LP
 610 .na
 611 'ti -2n
 612 'ta  2n
 613 \(bu    Each manpage reference listed is a hyperlink to the
 614 actual manpage as specified by the
 615 .B \%-cgiurl
 616 option.
 617 .ad
 618 .RE
 619 .LP
 620 .na
 621 This ability to process keyword searches gives nice added functionality
 622 to a \s-1WWW\s+1 forms interface to
 623 .BR man (1).
 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
 626 .B man2html
 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"
 630 .na
 631 .LP
 632 Unfortunately, there is no standard controlling the format of keyword
 633 search results.
 634 The
 635 .B man2html
 636 utility tries it best to handle all the variations.
 637 However, the keyword search results generated by the
 638 .I Solaris
 639 operating system is different enough from other systems that a
 640 special command-line option
 641 .RB ( -solaris )
 642 must be specified to handle its output.
 643 .SS "Example of raw Solaris-type keyword search results:"
 644 .LP
 645 .ft C
 646 .nf
 647 .ne 10v
 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
 652 .fi
 653 .ft
 654 .LP
 655 If keyword search results on your systems appear in the following format:
 656 .LP
 657 .RS 4n
 658 .B "<topic>  <actual_manpage> (#) - Description"
 659 .RE
 660 .LP
 661 then you need to specify the
 662 .B \%-solaris
 663 option in addition to the
 664 .B -k
 665 option.
 666 .SH "ADDITIONAL NOTES"
 667 .na
 668 .LP
 669 Different systems format manpages differently.
 670 Here is a list of recommended command-line options for certain systems:
 671 .RS 4n
 672 .LP
 673 .ta 1i
 674 .nf
 675 .ne 3v
 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)
 679 .fi
 680 .RE
 681 .LP
 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
 685 .B man2html
 686 depaginates the text.
 687 To avoid this problem,
 688 .B man2html
 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
 692 .B man2html
 693 inserts a blank line in the \s-1HTML\s+1 output.
 694 .LP
 695 A manpage cross-reference is detected by the following pseudo expression:
 696 \%\fB[A-z.-+_]+([0-9][A-z]?)\fR
 697 .LP
 698 The
 699 .B man2html
 700 utility only recognizes lines with "\fB - \fR" (the normal separator
 701 between manpage references and summary text) while in keyword
 702 search mode.
 703 .LP
 704 The
 705 .B man2html
 706 utility can be hooked in a \s-1CGI\s+1 script/program to convert manpages
 707 on the fly.
 708 This is the reason for the
 709 .B \%-cgiurl
 710 option.
 711 .SH LIMITATIONS
 712 .na
 713 .LP
 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.
 719 .LP
 720 If
 721 .B \%-seealso
 722 is specified, all xrefs are detected after the
 723 .B "\%SEE\ ALSO"
 724 heading.
 725 In other words, sections after
 726 .B "\%SEE\ ALSO"
 727 may contain hyperlinked xrefs.
 728 .SH BUGS
 729 .na
 730 .LP
 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
 734 .B \%-sun
 735 option is in affect.
 736 .SH VERSION
 737 .na
 738 This documentation describes
 739 .B man2html
 740 version 3.0.1
 741 .SH "SEE ALSO"
 742 .na
 743 .BR man (1),
 744 .BR nroff (1),
 745 .BR perl (1)
 746 .LP
 747 .I http://www.oac.uci.edu/indiv/ehood/man2html.html
 748 .SH AUTHOR
 749 .LP
 750 .B Earl Hood
 751 .br
 752 .I ehood@medusa.acs.uci.edu
 753 .\"
 754 .SH "ERRORS AND OMISSIONS"
 755 .na
 756 Troff version of this document initially created for version 2.1.0
 757 by C. Jeffery Small
 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 .