home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / lib / Pod / Man.pm < prev    next >
Text File  |  2000-03-18  |  44KB  |  1,218 lines
  1. # Pod::Man -- Convert POD data to formatted *roff input.
  2. # $Id: Man.pm,v 1.2 2000/03/19 07:30:13 eagle Exp $
  3. #
  4. # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
  5. #
  6. # This program is free software; you can redistribute it and/or modify it
  7. # under the same terms as Perl itself.
  8. #
  9. # This module is intended to be a replacement for the pod2man script
  10. # distributed with versions of Perl prior to 5.6, and attempts to match its
  11. # output except for some specific circumstances where other decisions seemed
  12. # to produce better output.  It uses Pod::Parser and is designed to be easy
  13. # to subclass.
  14. #
  15. # Perl core hackers, please note that this module is also separately
  16. # maintained outside of the Perl core as part of the podlators.  Please send
  17. # me any patches at the address above in addition to sending them to the
  18. # standard Perl mailing lists.
  19.  
  20. ############################################################################
  21. # Modules and declarations
  22. ############################################################################
  23.  
  24. package Pod::Man;
  25.  
  26. require 5.004;
  27.  
  28. use Carp qw(carp croak);
  29. use Pod::Parser ();
  30.  
  31. use strict;
  32. use subs qw(makespace);
  33. use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
  34.  
  35. @ISA = qw(Pod::Parser);
  36.  
  37. # Don't use the CVS revision as the version, since this module is also in
  38. # Perl core and too many things could munge CVS magic revision strings.
  39. # This number should ideally be the same as the CVS revision in podlators,
  40. # however.
  41. $VERSION = 1.02;
  42.  
  43.  
  44. ############################################################################
  45. # Preamble and *roff output tables
  46. ############################################################################
  47.  
  48. # The following is the static preamble which starts all *roff output we
  49. # generate.  It's completely static except for the font to use as a
  50. # fixed-width font, which is designed by @CFONT@.  $PREAMBLE should
  51. # therefore be run through s/\@CFONT\@/<font>/g before output.
  52. $PREAMBLE = <<'----END OF PREAMBLE----';
  53. .de Sh \" Subsection heading
  54. .br
  55. .if t .Sp
  56. .ne 5
  57. .PP
  58. \fB\\$1\fR
  59. .PP
  60. ..
  61. .de Sp \" Vertical space (when we can't use .PP)
  62. .if t .sp .5v
  63. .if n .sp
  64. ..
  65. .de Ip \" List item
  66. .br
  67. .ie \\n(.$>=3 .ne \\$3
  68. .el .ne 3
  69. .IP "\\$1" \\$2
  70. ..
  71. .de Vb \" Begin verbatim text
  72. .ft @CFONT@
  73. .nf
  74. .ne \\$1
  75. ..
  76. .de Ve \" End verbatim text
  77. .ft R
  78.  
  79. .fi
  80. ..
  81. .\" Set up some character translations and predefined strings.  \*(-- will
  82. .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  83. .\" double quote, and \*(R" will give a right double quote.  | will give a
  84. .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  85. .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  86. .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  87. .tr \(*W-|\(bv\*(Tr
  88. .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  89. .ie n \{\
  90. .    ds -- \(*W-
  91. .    ds PI pi
  92. .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  93. .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  94. .    ds L" ""
  95. .    ds R" ""
  96. .    ds C` `
  97. .    ds C' '
  98. 'br\}
  99. .el\{\
  100. .    ds -- \|\(em\|
  101. .    ds PI \(*p
  102. .    ds L" ``
  103. .    ds R" ''
  104. 'br\}
  105. .\"
  106. .\" If the F register is turned on, we'll generate index entries on stderr
  107. .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  108. .\" index entries marked with X<> in POD.  Of course, you'll have to process
  109. .\" the output yourself in some meaningful fashion.
  110. .if \nF \{\
  111. .    de IX
  112. .    tm Index:\\$1\t\\n%\t"\\$2"
  113. .    .
  114. .    nr % 0
  115. .    rr F
  116. .\}
  117. .\"
  118. .\" For nroff, turn off justification.  Always turn off hyphenation; it
  119. .\" makes way too many mistakes in technical documents.
  120. .hy 0
  121. .if n .na
  122. .\"
  123. .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  124. .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  125. .bd B 3
  126. .    \" fudge factors for nroff and troff
  127. .if n \{\
  128. .    ds #H 0
  129. .    ds #V .8m
  130. .    ds #F .3m
  131. .    ds #[ \f1
  132. .    ds #] \fP
  133. .\}
  134. .if t \{\
  135. .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  136. .    ds #V .6m
  137. .    ds #F 0
  138. .    ds #[ \&
  139. .    ds #] \&
  140. .\}
  141. .    \" simple accents for nroff and troff
  142. .if n \{\
  143. .    ds ' \&
  144. .    ds ` \&
  145. .    ds ^ \&
  146. .    ds , \&
  147. .    ds ~ ~
  148. .    ds /
  149. .\}
  150. .if t \{\
  151. .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  152. .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  153. .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  154. .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  155. .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  156. .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  157. .\}
  158. .    \" troff and (daisy-wheel) nroff accents
  159. .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  160. .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
  161. .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
  162. .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
  163. .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
  164. .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
  165. .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
  166. .ds ae a\h'-(\w'a'u*4/10)'e
  167. .ds Ae A\h'-(\w'A'u*4/10)'E
  168. .    \" corrections for vroff
  169. .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
  170. .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
  171. .    \" for low resolution devices (crt and lpr)
  172. .if \n(.H>23 .if \n(.V>19 \
  173. \{\
  174. .    ds : e
  175. .    ds 8 ss
  176. .    ds o a
  177. .    ds d- d\h'-1'\(ga
  178. .    ds D- D\h'-1'\(hy
  179. .    ds th \o'bp'
  180. .    ds Th \o'LP'
  181. .    ds ae ae
  182. .    ds Ae AE
  183. .\}
  184. .rm #[ #] #H #V #F C
  185. ----END OF PREAMBLE----
  186.                                    
  187. # This table is taken nearly verbatim from Tom Christiansen's pod2man.  It
  188. # assumes that the standard preamble has already been printed, since that's
  189. # what defines all of the accent marks.  Note that some of these are quoted
  190. # with double quotes since they contain embedded single quotes, so use \\
  191. # uniformly for backslash for readability.
  192. %ESCAPES = (
  193.     'amp'       =>    '&',      # ampersand
  194.     'lt'        =>    '<',      # left chevron, less-than
  195.     'gt'        =>    '>',      # right chevron, greater-than
  196.     'quot'      =>    '"',      # double quote
  197.  
  198.     'Aacute'    =>    "A\\*'",  # capital A, acute accent
  199.     'aacute'    =>    "a\\*'",  # small a, acute accent
  200.     'Acirc'     =>    'A\\*^',  # capital A, circumflex accent
  201.     'acirc'     =>    'a\\*^',  # small a, circumflex accent
  202.     'AElig'     =>    '\*(AE',  # capital AE diphthong (ligature)
  203.     'aelig'     =>    '\*(ae',  # small ae diphthong (ligature)
  204.     'Agrave'    =>    "A\\*`",  # capital A, grave accent
  205.     'agrave'    =>    "A\\*`",  # small a, grave accent
  206.     'Aring'     =>    'A\\*o',  # capital A, ring
  207.     'aring'     =>    'a\\*o',  # small a, ring
  208.     'Atilde'    =>    'A\\*~',  # capital A, tilde
  209.     'atilde'    =>    'a\\*~',  # small a, tilde
  210.     'Auml'      =>    'A\\*:',  # capital A, dieresis or umlaut mark
  211.     'auml'      =>    'a\\*:',  # small a, dieresis or umlaut mark
  212.     'Ccedil'    =>    'C\\*,',  # capital C, cedilla
  213.     'ccedil'    =>    'c\\*,',  # small c, cedilla
  214.     'Eacute'    =>    "E\\*'",  # capital E, acute accent
  215.     'eacute'    =>    "e\\*'",  # small e, acute accent
  216.     'Ecirc'     =>    'E\\*^',  # capital E, circumflex accent
  217.     'ecirc'     =>    'e\\*^',  # small e, circumflex accent
  218.     'Egrave'    =>    'E\\*`',  # capital E, grave accent
  219.     'egrave'    =>    'e\\*`',  # small e, grave accent
  220.     'ETH'       =>    '\\*(D-', # capital Eth, Icelandic
  221.     'eth'       =>    '\\*(d-', # small eth, Icelandic
  222.     'Euml'      =>    'E\\*:',  # capital E, dieresis or umlaut mark
  223.     'euml'      =>    'e\\*:',  # small e, dieresis or umlaut mark
  224.     'Iacute'    =>    "I\\*'",  # capital I, acute accent
  225.     'iacute'    =>    "i\\*'",  # small i, acute accent
  226.     'Icirc'     =>    'I\\*^',  # capital I, circumflex accent
  227.     'icirc'     =>    'i\\*^',  # small i, circumflex accent
  228.     'Igrave'    =>    'I\\*`',  # capital I, grave accent
  229.     'igrave'    =>    'i\\*`',  # small i, grave accent
  230.     'Iuml'      =>    'I\\*:',  # capital I, dieresis or umlaut mark
  231.     'iuml'      =>    'i\\*:',  # small i, dieresis or umlaut mark
  232.     'Ntilde'    =>    'N\*~',   # capital N, tilde
  233.     'ntilde'    =>    'n\*~',   # small n, tilde
  234.     'Oacute'    =>    "O\\*'",  # capital O, acute accent
  235.     'oacute'    =>    "o\\*'",  # small o, acute accent
  236.     'Ocirc'     =>    'O\\*^',  # capital O, circumflex accent
  237.     'ocirc'     =>    'o\\*^',  # small o, circumflex accent
  238.     'Ograve'    =>    'O\\*`',  # capital O, grave accent
  239.     'ograve'    =>    'o\\*`',  # small o, grave accent
  240.     'Oslash'    =>    'O\\*/',  # capital O, slash
  241.     'oslash'    =>    'o\\*/',  # small o, slash
  242.     'Otilde'    =>    'O\\*~',  # capital O, tilde
  243.     'otilde'    =>    'o\\*~',  # small o, tilde
  244.     'Ouml'      =>    'O\\*:',  # capital O, dieresis or umlaut mark
  245.     'ouml'      =>    'o\\*:',  # small o, dieresis or umlaut mark
  246.     'szlig'     =>    '\*8',    # small sharp s, German (sz ligature)
  247.     'THORN'     =>    '\\*(Th', # capital THORN, Icelandic
  248.     'thorn'     =>    '\\*(th', # small thorn, Icelandic
  249.     'Uacute'    =>    "U\\*'",  # capital U, acute accent
  250.     'uacute'    =>    "u\\*'",  # small u, acute accent
  251.     'Ucirc'     =>    'U\\*^',  # capital U, circumflex accent
  252.     'ucirc'     =>    'u\\*^',  # small u, circumflex accent
  253.     'Ugrave'    =>    'U\\*`',  # capital U, grave accent
  254.     'ugrave'    =>    'u\\*`',  # small u, grave accent
  255.     'Uuml'      =>    'U\\*:',  # capital U, dieresis or umlaut mark
  256.     'uuml'      =>    'u\\*:',  # small u, dieresis or umlaut mark
  257.     'Yacute'    =>    "Y\\*'",  # capital Y, acute accent
  258.     'yacute'    =>    "y\\*'",  # small y, acute accent
  259.     'yuml'      =>    'y\\*:',  # small y, dieresis or umlaut mark
  260. );
  261.  
  262.  
  263. ############################################################################
  264. # Static helper functions
  265. ############################################################################
  266.  
  267. # Protect leading quotes and periods against interpretation as commands.
  268. # Also protect anything starting with a backslash, since it could expand
  269. # or hide something that *roff would interpret as a command.  This is
  270. # overkill, but it's much simpler than trying to parse *roff here.
  271. sub protect {
  272.     local $_ = shift;
  273.     s/^([.\'\\])/\\&$1/mg;
  274.     $_;
  275. }
  276.                     
  277. # Given a command and a single argument that may or may not contain double
  278. # quotes, handle double-quote formatting for it.  If there are no double
  279. # quotes, just return the command followed by the argument in double quotes.
  280. # If there are double quotes, use an if statement to test for nroff, and for
  281. # nroff output the command followed by the argument in double quotes with
  282. # embedded double quotes doubled.  For other formatters, remap paired double
  283. # quotes to `` and ''.
  284. sub switchquotes {
  285.     my $command = shift;
  286.     local $_ = shift;
  287.     my $extra = shift;
  288.     s/\\\*\([LR]\"/\"/g;
  289.     if (/\"/) {
  290.         s/\"/\"\"/g;
  291.         my $troff = $_;
  292.         $troff =~ s/\"\"([^\"]*)\"\"/\`\`$1\'\'/g;
  293.         s/\"/\"\"/g if $extra;
  294.         $troff =~ s/\"/\"\"/g if $extra;
  295.         $_ = qq("$_") . ($extra ? " $extra" : '');
  296.         $troff = qq("$troff") . ($extra ? " $extra" : '');
  297.         return ".if n $command $_\n.el $command $troff\n";
  298.     } else {
  299.         $_ = qq("$_") . ($extra ? " $extra" : '');
  300.         return "$command $_\n";
  301.     }
  302. }
  303.  
  304. # Translate a font string into an escape.
  305. sub toescape { (length ($_[0]) > 1 ? '\f(' : '\f') . $_[0] }
  306.  
  307.                     
  308. ############################################################################
  309. # Initialization
  310. ############################################################################
  311.  
  312. # Initialize the object.  Here, we also process any additional options
  313. # passed to the constructor or set up defaults if none were given.  center
  314. # is the centered title, release is the version number, and date is the date
  315. # for the documentation.  Note that we can't know what file name we're
  316. # processing due to the architecture of Pod::Parser, so that *has* to either
  317. # be passed to the constructor or set separately with Pod::Man::name().
  318. sub initialize {
  319.     my $self = shift;
  320.  
  321.     # Figure out the fixed-width font.  If user-supplied, make sure that
  322.     # they are the right length.
  323.     for (qw/fixed fixedbold fixeditalic fixedbolditalic/) {
  324.         if (defined $$self{$_}) {
  325.             if (length ($$self{$_}) < 1 || length ($$self{$_}) > 2) {
  326.                 croak "roff font should be 1 or 2 chars, not `$$self{$_}'";
  327.             }
  328.         } else {
  329.             $$self{$_} = '';
  330.         }
  331.     }
  332.  
  333.     # Set the default fonts.  We can't be sure what fixed bold-italic is
  334.     # going to be called, so default to just bold.
  335.     $$self{fixed}           ||= 'CW';
  336.     $$self{fixedbold}       ||= 'CB';
  337.     $$self{fixeditalic}     ||= 'CI';
  338.     $$self{fixedbolditalic} ||= 'CB';
  339.  
  340.     # Set up a table of font escapes.  First number is fixed-width, second
  341.     # is bold, third is italic.
  342.     $$self{FONTS} = { '000' => '\fR', '001' => '\fI',
  343.                       '010' => '\fB', '011' => '\f(BI',
  344.                       '100' => toescape ($$self{fixed}),
  345.                       '101' => toescape ($$self{fixeditalic}),
  346.                       '110' => toescape ($$self{fixedbold}),
  347.                       '111' => toescape ($$self{fixedbolditalic})};
  348.  
  349.     # Extra stuff for page titles.
  350.     $$self{center} = 'User Contributed Perl Documentation'
  351.         unless defined $$self{center};
  352.     $$self{indent}  = 4 unless defined $$self{indent};
  353.  
  354.     # We used to try first to get the version number from a local binary,
  355.     # but we shouldn't need that any more.  Get the version from the running
  356.     # Perl.  Work a little magic to handle subversions correctly under both
  357.     # the pre-5.6 and the post-5.6 version numbering schemes.
  358.     if (!defined $$self{release}) {
  359.         my @version = ($] =~ /^(\d+)\.(\d{3})(\d{0,3})$/);
  360.         $version[2] ||= 0;
  361.         $version[2] *= 10 ** (3 - length $version[2]);
  362.         for (@version) { $_ += 0 }
  363.         $$self{release} = 'perl v' . join ('.', @version);
  364.     }
  365.  
  366.     # Double quotes in things that will be quoted.
  367.     for (qw/center date release/) {
  368.         $$self{$_} =~ s/\"/\"\"/g if $$self{$_};
  369.     }
  370.  
  371.     $$self{INDENT}  = 0;        # Current indentation level.
  372.     $$self{INDENTS} = [];       # Stack of indentations.
  373.     $$self{INDEX}   = [];       # Index keys waiting to be printed.
  374.  
  375.     $self->SUPER::initialize;
  376. }
  377.  
  378. # For each document we process, output the preamble first.  Note that the
  379. # fixed width font is a global default; once we interpolate it into the
  380. # PREAMBLE, it ain't ever changing.  Maybe fix this later.
  381. sub begin_pod {
  382.     my $self = shift;
  383.  
  384.     # Try to figure out the name and section from the file name.
  385.     my $section = $$self{section} || 1;
  386.     my $name = $$self{name};
  387.     if (!defined $name) {
  388.         $name = $self->input_file;
  389.         $section = 3 if (!$$self{section} && $name =~ /\.pm\z/i);
  390.         $name =~ s/\.p(od|[lm])\z//i;
  391.         if ($section =~ /^1/) {
  392.             require File::Basename;
  393.             $name = uc File::Basename::basename ($name);
  394.         } else {
  395.             # Lose everything up to the first of
  396.             #     */lib/*perl*      standard or site_perl module
  397.             #     */*perl*/lib      from -D prefix=/opt/perl
  398.             #     */*perl*/         random module hierarchy
  399.             # which works.  Should be fixed to use File::Spec.  Also handle
  400.             # a leading lib/ since that's what ExtUtils::MakeMaker creates.
  401.             for ($name) {
  402.                 s%//+%/%g;
  403.                 if (     s%^.*?/lib/[^/]*perl[^/]*/%%si
  404.                       or s%^.*?/[^/]*perl[^/]*/(?:lib/)?%%si) {
  405.                     s%^site(_perl)?/%%s;      # site and site_perl
  406.                     s%^(.*-$^O|$^O-.*)/%%so;  # arch
  407.                     s%^\d+\.\d+%%s;           # version
  408.                 }
  409.                 s%^lib/%%;
  410.                 s%/%::%g;
  411.             }
  412.         }
  413.     }
  414.  
  415.     # Modification date header.  Try to use the modification time of our
  416.     # input.
  417.     if (!defined $$self{date}) {
  418.         my $time = (stat $self->input_file)[9] || time;
  419.         my ($day, $month, $year) = (localtime $time)[3,4,5];
  420.         $month++;
  421.         $year += 1900;
  422.         $$self{date} = sprintf ('%4d-%02d-%02d', $year, $month, $day);
  423.     }
  424.  
  425.     # Now, print out the preamble and the title.
  426.     $PREAMBLE =~ s/\@CFONT\@/$$self{fixed}/;
  427.     chomp $PREAMBLE;
  428.     print { $self->output_handle } <<"----END OF HEADER----";
  429. .\\" Automatically generated by Pod::Man version $VERSION
  430. .\\" @{[ scalar localtime ]}
  431. .\\"
  432. .\\" Standard preamble:
  433. .\\" ======================================================================
  434. $PREAMBLE
  435. .\\" ======================================================================
  436. .\\"
  437. .IX Title "$name $section"
  438. .TH $name $section "$$self{release}" "$$self{date}" "$$self{center}"
  439. .UC
  440. ----END OF HEADER----
  441. #"# for cperl-mode
  442.  
  443.     # Initialize a few per-file variables.
  444.     $$self{INDENT} = 0;
  445.     $$self{NEEDSPACE} = 0;
  446. }
  447.  
  448.  
  449. ############################################################################
  450. # Core overrides
  451. ############################################################################
  452.  
  453. # Called for each command paragraph.  Gets the command, the associated
  454. # paragraph, the line number, and a Pod::Paragraph object.  Just dispatches
  455. # the command to a method named the same as the command.  =cut is handled
  456. # internally by Pod::Parser.
  457. sub command {
  458.     my $self = shift;
  459.     my $command = shift;
  460.     return if $command eq 'pod';
  461.     return if ($$self{EXCLUDE} && $command ne 'end');
  462.     $command = 'cmd_' . $command;
  463.     $self->$command (@_);
  464. }
  465.  
  466. # Called for a verbatim paragraph.  Gets the paragraph, the line number, and
  467. # a Pod::Paragraph object.  Rofficate backslashes, untabify, put a
  468. # zero-width character at the beginning of each line to protect against
  469. # commands, and wrap in .Vb/.Ve.
  470. sub verbatim {
  471.     my $self = shift;
  472.     return if $$self{EXCLUDE};
  473.     local $_ = shift;
  474.     return if /^\s+$/;
  475.     s/\s+$/\n/;
  476.     my $lines = tr/\n/\n/;
  477.     1 while s/^(.*?)(\t+)/$1 . ' ' x (length ($2) * 8 - length ($1) % 8)/me;
  478.     s/\\/\\e/g;
  479.     s/^(\s*\S)/'\&' . $1/gme;
  480.     $self->makespace if $$self{NEEDSPACE};
  481.     $self->output (".Vb $lines\n$_.Ve\n");
  482.     $$self{NEEDSPACE} = 0;
  483. }
  484.  
  485. # Called for a regular text block.  Gets the paragraph, the line number, and
  486. # a Pod::Paragraph object.  Perform interpolation and output the results.
  487. sub textblock {
  488.     my $self = shift;
  489.     return if $$self{EXCLUDE};
  490.     $self->output ($_[0]), return if $$self{VERBATIM};
  491.  
  492.     # Perform a little magic to collapse multiple L<> references.  We'll
  493.     # just rewrite the whole thing into actual text at this part, bypassing
  494.     # the whole internal sequence parsing thing.
  495.     my $text = shift;
  496.     $text =~ s{
  497.         (L<                     # A link of the form L</something>.
  498.               /
  499.               (
  500.                   [:\w]+        # The item has to be a simple word...
  501.                   (\(\))?       # ...or simple function.
  502.               )
  503.           >
  504.           (
  505.               ,?\s+(and\s+)?    # Allow lots of them, conjuncted.
  506.               L<  
  507.                   /
  508.                   ( [:\w]+ ( \(\) )? )
  509.               >
  510.           )+
  511.         )
  512.     } {
  513.         local $_ = $1;
  514.         s{ L< / ( [^>]+ ) > } {$1}xg;
  515.         my @items = split /(?:,?\s+(?:and\s+)?)/;
  516.         my $string = 'the ';
  517.         my $i;
  518.         for ($i = 0; $i < @items; $i++) {
  519.             $string .= $items[$i];
  520.             $string .= ', ' if @items > 2 && $i != $#items;
  521.             $string .= ' ' if @items == 2 && $i == 2;
  522.             $string .= 'and ' if ($i == $#items - 1);
  523.         }
  524.         $string .= ' entries elsewhere in this document';
  525.         $string;
  526.     }gex;
  527.  
  528.     # Parse the tree and output it.  collapse knows about references to
  529.     # scalars as well as scalars and does the right thing with them.
  530.     $text = $self->parse ($text, @_);
  531.     $text =~ s/\n\s*$/\n/;
  532.     $self->makespace if $$self{NEEDSPACE};
  533.     $self->output (protect $self->mapfonts ($text));
  534.     $self->outindex;
  535.     $$self{NEEDSPACE} = 1;
  536. }
  537.  
  538. # Called for an interior sequence.  Takes a Pod::InteriorSequence object and
  539. # returns a reference to a scalar.  This scalar is the final formatted text.
  540. # It's returned as a reference so that other interior sequences above us
  541. # know that the text has already been processed.
  542. sub sequence {
  543.     my ($self, $seq) = @_;
  544.     my $command = $seq->cmd_name;
  545.  
  546.     # Zero-width characters.
  547.     if ($command eq 'Z') {
  548.         # Workaround to generate a blessable reference, needed by 5.005.
  549.         my $tmp = '\&';
  550.         return bless \ "$tmp", 'Pod::Man::String';
  551.     }
  552.  
  553.     # C<>, L<>, X<>, and E<> don't apply guesswork to their contents.
  554.     local $_ = $self->collapse ($seq->parse_tree, $command =~ /^[CELX]$/);
  555.  
  556.     # Handle E<> escapes.
  557.     if ($command eq 'E') {
  558.         if (/^\d+$/) {
  559.             return bless \ chr ($_), 'Pod::Man::String';
  560.         } elsif (exists $ESCAPES{$_}) {
  561.             return bless \ "$ESCAPES{$_}", 'Pod::Man::String';
  562.         } else {
  563.             carp "Unknown escape E<$1>";
  564.             return bless \ "E<$_>", 'Pod::Man::String';
  565.         }
  566.     }
  567.  
  568.     # For all the other sequences, empty content produces no output.
  569.     return '' if $_ eq '';
  570.  
  571.     # Handle formatting sequences.
  572.     if ($command eq 'B') {
  573.         return bless \ ('\f(BS' . $_ . '\f(BE'), 'Pod::Man::String';
  574.     } elsif ($command eq 'F') {
  575.         return bless \ ('\f(IS' . $_ . '\f(IE'), 'Pod::Man::String';
  576.     } elsif ($command eq 'I') {
  577.         return bless \ ('\f(IS' . $_ . '\f(IE'), 'Pod::Man::String';
  578.     } elsif ($command eq 'C') {
  579.         s/-/\\-/g;
  580.         s/__/_\\|_/g;
  581.         return bless \ ('\f(FS\*(C`' . $_ . "\\*(C'\\f(FE"),
  582.             'Pod::Man::String';
  583.     }
  584.  
  585.     # Handle links.
  586.     if ($command eq 'L') {
  587.         # A bug in lvalue subs in 5.6 requires the temporary variable.
  588.         my $tmp = $self->buildlink ($_);
  589.         return bless \ "$tmp", 'Pod::Man::String';
  590.     }
  591.                          
  592.     # Whitespace protection replaces whitespace with "\ ".
  593.     if ($command eq 'S') {
  594.         s/\s+/\\ /g;
  595.         return bless \ "$_", 'Pod::Man::String';
  596.     }
  597.  
  598.     # Add an index entry to the list of ones waiting to be output.
  599.     if ($command eq 'X') { push (@{ $$self{INDEX} }, $_); return '' }
  600.  
  601.     # Anything else is unknown.
  602.     carp "Unknown sequence $command<$_>";
  603. }
  604.  
  605.  
  606. ############################################################################
  607. # Command paragraphs
  608. ############################################################################
  609.  
  610. # All command paragraphs take the paragraph and the line number.
  611.  
  612. # First level heading.  We can't output .IX in the NAME section due to a bug
  613. # in some versions of catman, so don't output a .IX for that section.  .SH
  614. # already uses small caps, so remove any E<> sequences that would cause
  615. # them.
  616. sub cmd_head1 {
  617.     my $self = shift;
  618.     local $_ = $self->parse (@_);
  619.     s/\s+$//;
  620.     s/\\s-?\d//g;
  621.     $self->output (switchquotes ('.SH', $self->mapfonts ($_)));
  622.     $self->outindex (($_ eq 'NAME') ? () : ('Header', $_));
  623.     $$self{NEEDSPACE} = 0;
  624. }
  625.  
  626. # Second level heading.
  627. sub cmd_head2 {
  628.     my $self = shift;
  629.     local $_ = $self->parse (@_);
  630.     s/\s+$//;
  631.     $self->output (switchquotes ('.Sh', $self->mapfonts ($_)));
  632.     $self->outindex ('Subsection', $_);
  633.     $$self{NEEDSPACE} = 0;
  634. }
  635.  
  636. # Start a list.  For indents after the first, wrap the outside indent in .RS
  637. # so that hanging paragraph tags will be correct.
  638. sub cmd_over {
  639.     my $self = shift;
  640.     local $_ = shift;
  641.     unless (/^[-+]?\d+\s+$/) { $_ = $$self{indent} }
  642.     if (@{ $$self{INDENTS} } > 0) {
  643.         $self->output (".RS $$self{INDENT}\n");
  644.     }
  645.     push (@{ $$self{INDENTS} }, $$self{INDENT});
  646.     $$self{INDENT} = ($_ + 0);
  647. }
  648.  
  649. # End a list.  If we've closed an embedded indent, we've mangled the hanging
  650. # paragraph indent, so temporarily replace it with .RS and set WEIRDINDENT.
  651. # We'll close that .RS at the next =back or =item.
  652. sub cmd_back {
  653.     my $self = shift;
  654.     $$self{INDENT} = pop @{ $$self{INDENTS} };
  655.     unless (defined $$self{INDENT}) {
  656.         carp "Unmatched =back";
  657.         $$self{INDENT} = 0;
  658.     }
  659.     if ($$self{WEIRDINDENT}) {
  660.         $self->output (".RE\n");
  661.         $$self{WEIRDINDENT} = 0;
  662.     }
  663.     if (@{ $$self{INDENTS} } > 0) {
  664.         $self->output (".RE\n");
  665.         $self->output (".RS $$self{INDENT}\n");
  666.         $$self{WEIRDINDENT} = 1;
  667.     }
  668.     $$self{NEEDSPACE} = 1;
  669. }
  670.  
  671. # An individual list item.  Emit an index entry for anything that's
  672. # interesting, but don't emit index entries for things like bullets and
  673. # numbers.  rofficate bullets too while we're at it (so for nice output, use
  674. # * for your lists rather than o or . or - or some other thing).  Newlines
  675. # in an item title are turned into spaces since *roff can't handle them
  676. # embedded.
  677. sub cmd_item {
  678.     my $self = shift;
  679.     local $_ = $self->parse (@_);
  680.     s/\s+$//;
  681.     s/\s*\n\s*/ /g;
  682.     my $index;
  683.     if (/\w/ && !/^\w[.\)]\s*$/) {
  684.         $index = $_;
  685.         $index =~ s/^\s*[-*+o.]?\s*//;
  686.     }
  687.     s/^\*(\s|\Z)/\\\(bu$1/;
  688.     if ($$self{WEIRDINDENT}) {
  689.         $self->output (".RE\n");
  690.         $$self{WEIRDINDENT} = 0;
  691.     }
  692.     $_ = $self->mapfonts ($_);
  693.     $self->output (switchquotes ('.Ip', $_, $$self{INDENT}));
  694.     $self->outindex ($index ? ('Item', $index) : ());
  695.     $$self{NEEDSPACE} = 0;
  696. }
  697.  
  698. # Begin a block for a particular translator.  Setting VERBATIM triggers
  699. # special handling in textblock().
  700. sub cmd_begin {
  701.     my $self = shift;
  702.     local $_ = shift;
  703.     my ($kind) = /^(\S+)/ or return;
  704.     if ($kind eq 'man' || $kind eq 'roff') {
  705.         $$self{VERBATIM} = 1;
  706.     } else {
  707.         $$self{EXCLUDE} = 1;
  708.     }
  709. }
  710.  
  711. # End a block for a particular translator.  We assume that all =begin/=end
  712. # pairs are properly closed.
  713. sub cmd_end {
  714.     my $self = shift;
  715.     $$self{EXCLUDE} = 0;
  716.     $$self{VERBATIM} = 0;
  717. }
  718.  
  719. # One paragraph for a particular translator.  Ignore it unless it's intended
  720. # for man or roff, in which case we output it verbatim.
  721. sub cmd_for {
  722.     my $self = shift;
  723.     local $_ = shift;
  724.     return unless s/^(?:man|roff)\b[ \t]*\n?//;
  725.     $self->output ($_);
  726. }
  727.  
  728.  
  729. ############################################################################
  730. # Link handling
  731. ############################################################################
  732.  
  733. # Handle links.  We can't actually make real hyperlinks, so this is all to
  734. # figure out what text and formatting we print out.
  735. sub buildlink {
  736.     my $self = shift;
  737.     local $_ = shift;
  738.  
  739.     # Smash whitespace in case we were split across multiple lines.
  740.     s/\s+/ /g;
  741.  
  742.     # If we were given any explicit text, just output it.
  743.     if (m{ ^ ([^|]+) \| }x) { return $1 }
  744.  
  745.     # Okay, leading and trailing whitespace isn't important.
  746.     s/^\s+//;
  747.     s/\s+$//;
  748.  
  749.     # Default to using the whole content of the link entry as a section
  750.     # name.  Note that L<manpage/> forces a manpage interpretation, as does
  751.     # something looking like L<manpage(section)>.  Do the same thing to
  752.     # L<manpage(section)> as we would to manpage(section) without the L<>;
  753.     # see guesswork().  If we've added italics, don't add the "manpage"
  754.     # text; markup is sufficient.
  755.     my ($manpage, $section) = ('', $_);
  756.     if (/^"\s*(.*?)\s*"$/) {
  757.         $section = '"' . $1 . '"';
  758.     } elsif (m{ ^ [-:.\w]+ (?: \( \S+ \) )? $ }x) {
  759.         ($manpage, $section) = ($_, '');
  760.         $manpage =~ s/^([^\(]+)\(/'\f(IS' . $1 . '\f(IE\|('/e;
  761.     } elsif (m%/%) {
  762.         ($manpage, $section) = split (/\s*\/\s*/, $_, 2);
  763.         if ($manpage =~ /^[-:.\w]+(?:\(\S+\))?$/) {
  764.             $manpage =~ s/^([^\(]+)\(/'\f(IS' . $1 . '\f(IE\|'/e;
  765.         }
  766.         $section =~ s/^\"\s*//;
  767.         $section =~ s/\s*\"$//;
  768.     }
  769.     if ($manpage && $manpage !~ /\\f\(IS/) {
  770.         $manpage = "the $manpage manpage";
  771.     }
  772.  
  773.     # Now build the actual output text.
  774.     my $text = '';
  775.     if (!length ($section) && !length ($manpage)) {
  776.         carp "Invalid link $_";
  777.     } elsif (!length ($section)) {
  778.         $text = $manpage;
  779.     } elsif ($section =~ /^[:\w]+(?:\(\))?/) {
  780.         $text .= 'the ' . $section . ' entry';
  781.         $text .= (length $manpage) ? " in $manpage"
  782.                                    : " elsewhere in this document";
  783.     } else {
  784.         if ($section !~ /^".*"$/) { $section = '"' . $section . '"' }
  785.         $text .= 'the section on ' . $section;
  786.         $text .= " in $manpage" if length $manpage;
  787.     }
  788.     $text;
  789. }
  790.  
  791.  
  792. ############################################################################
  793. # Escaping and fontification
  794. ############################################################################
  795.  
  796. # At this point, we'll have embedded font codes of the form \f(<font>[SE]
  797. # where <font> is one of B, I, or F.  Turn those into the right font start
  798. # or end codes.  B<someI<thing> else> should map to \fBsome\f(BIthing\fB
  799. # else\fR.  The old pod2man didn't get this right; the second \fB was \fR,
  800. # so nested sequences didn't work right.  We take care of this by using
  801. # variables as a combined pointer to our current font sequence, and set each
  802. # to the number of current nestings of start tags for that font.  Use them
  803. # as a vector to look up what font sequence to use.
  804. sub mapfonts {
  805.     my $self = shift;
  806.     local $_ = shift;
  807.  
  808.     my ($fixed, $bold, $italic) = (0, 0, 0);
  809.     my %magic = (F => \$fixed, B => \$bold, I => \$italic);
  810.     s { \\f\((.)(.) } {
  811.         ${ $magic{$1} } += ($2 eq 'S') ? 1 : -1;
  812.         $$self{FONTS}{($fixed && 1) . ($bold && 1) . ($italic && 1)};
  813.     }gxe;
  814.     $_;
  815. }
  816.  
  817.  
  818. ############################################################################
  819. # *roff-specific parsing
  820. ############################################################################
  821.  
  822. # Called instead of parse_text, calls parse_text with the right flags.
  823. sub parse {
  824.     my $self = shift;
  825.     $self->parse_text ({ -expand_seq   => 'sequence',
  826.                          -expand_ptree => 'collapse' }, @_);
  827. }
  828.     
  829. # Takes a parse tree and a flag saying whether or not to treat it as literal
  830. # text (not call guesswork on it), and returns the concatenation of all of
  831. # the text strings in that parse tree.  If the literal flag isn't true,
  832. # guesswork() will be called on all plain scalars in the parse tree.
  833. # Assumes that everything in the parse tree is either a scalar or a
  834. # reference to a scalar.
  835. sub collapse {
  836.     my ($self, $ptree, $literal) = @_;
  837.     if ($literal) {
  838.         return join ('', map {
  839.             if (ref $_) {
  840.                 $$_;
  841.             } else {
  842.                 s/\\/\\e/g;
  843.                 $_;
  844.             }
  845.         } $ptree->children);
  846.     } else {
  847.         return join ('', map {
  848.             ref ($_) ? $$_ : $self->guesswork ($_)
  849.         } $ptree->children);
  850.     }
  851. }
  852.  
  853. # Takes a text block to perform guesswork on; this is guaranteed not to
  854. # contain any interior sequences.  Returns the text block with remapping
  855. # done.
  856. sub guesswork {
  857.     my $self = shift;
  858.     local $_ = shift;
  859.  
  860.     # rofficate backslashes.
  861.     s/\\/\\e/g;
  862.  
  863.     # Ensure double underbars have a tiny space between them.
  864.     s/__/_\\|_/g;
  865.  
  866.     # Make all caps a little smaller.  Be careful here, since we don't want
  867.     # to make @ARGV into small caps, nor do we want to fix the MIME in
  868.     # MIME-Version, since it looks weird with the full-height V.
  869.     s{
  870.         ( ^ | [\s\(\"\'\`\[\{<>] )
  871.         ( [A-Z] [A-Z] [/A-Z+:\d_\$&-]* )
  872.         (?: (?= [\s>\}\]\)\'\".?!,;:] | -- ) | $ )
  873.     } { $1 . '\s-1' . $2 . '\s0' }egx;
  874.  
  875.     # Turn PI into a pretty pi.
  876.     s{ (?: \\s-1 | \b ) PI (?: \\s0 | \b ) } {\\*\(PI}gx;
  877.  
  878.     # Italize functions in the form func().
  879.     s{
  880.         \b
  881.         (
  882.             [:\w]+ (?:\\s-1)? \(\)
  883.         )
  884.     } { '\f(IS' . $1 . '\f(IE' }egx;
  885.  
  886.     # func(n) is a reference to a manual page.  Make it \fIfunc\fR\|(n).
  887.     s{
  888.         \b
  889.         (\w[-:.\w]+ (?:\\s-1)?)
  890.         (
  891.             \( [^\)] \)
  892.         )
  893.     } { '\f(IS' . $1 . '\f(IE\|' . $2 }egx;
  894.  
  895.     # Convert simple Perl variable references to a fixed-width font.
  896.     s{
  897.         ( \s+ )
  898.         ( [\$\@%] [\w:]+ )
  899.         (?! \( )
  900.     } { $1 . '\f(FS' . $2 . '\f(FE'}egx;
  901.  
  902.     # Translate -- into a real em dash if it's used like one and fix up
  903.     # dashes, but keep hyphens hyphens.
  904.     s{ (\G|^|.) (-+) (\b|.) } {
  905.         my ($pre, $dash, $post) = ($1, $2, $3);
  906.         if (length ($dash) == 1) {
  907.             ($pre =~ /[a-zA-Z]/) ? "$pre-$post" : "$pre\\-$post";
  908.         } elsif (length ($dash) == 2
  909.                  && ((!$pre && !$post)
  910.                      || ($pre =~ /\w/ && !$post)
  911.                      || ($pre eq ' ' && $post eq ' ')
  912.                      || ($pre eq '=' && $post ne '=')
  913.                      || ($pre ne '=' && $post eq '='))) {
  914.             "$pre\\*(--$post";
  915.         } else {
  916.             $pre . ('\-' x length $dash) . $post;
  917.         }
  918.     }egxs;
  919.  
  920.     # Fix up double quotes.
  921.     s{ \" ([^\"]+) \" } { '\*(L"' . $1 . '\*(R"' }egx;
  922.  
  923.     # Make C++ into \*(C+, which is a squinched version.
  924.     s{ \b C\+\+ } {\\*\(C+}gx;
  925.  
  926.     # All done.
  927.     $_;
  928. }
  929.  
  930.  
  931. ############################################################################
  932. # Output formatting
  933. ############################################################################
  934.  
  935. # Make vertical whitespace.
  936. sub makespace {
  937.     my $self = shift;
  938.     $self->output ($$self{INDENT} > 0 ? ".Sp\n" : ".PP\n");
  939. }
  940.  
  941. # Output any pending index entries, and optionally an index entry given as
  942. # an argument.  Support multiple index entries in X<> separated by slashes,
  943. # and strip special escapes from index entries.
  944. sub outindex {
  945.     my ($self, $section, $index) = @_;
  946.     my @entries = map { split m%\s*/\s*% } @{ $$self{INDEX} };
  947.     return unless ($section || @entries);
  948.     $$self{INDEX} = [];
  949.     my $output;
  950.     if (@entries) {
  951.         my $output = '.IX Xref "'
  952.             . join (' ', map { s/\"/\"\"/; $_ } @entries)
  953.             . '"' . "\n";
  954.     }
  955.     if ($section) {
  956.         $index =~ s/\"/\"\"/;
  957.         $index =~ s/\\-/-/g;
  958.         $index =~ s/\\(?:s-?\d|.\(..|.)//g;
  959.         $output .= ".IX $section " . '"' . $index . '"' . "\n";
  960.     }
  961.     $self->output ($output);
  962. }
  963.  
  964. # Output text to the output device.
  965. sub output { print { $_[0]->output_handle } $_[1] }
  966.  
  967. __END__
  968.  
  969. .\" These are some extra bits of roff that I don't want to lose track of
  970. .\" but that have been removed from the preamble to make it a bit shorter
  971. .\" since they're not currently being used.  They're accents and special
  972. .\" characters we don't currently have escapes for.
  973. .if n \{\
  974. .    ds ? ?
  975. .    ds ! !
  976. .    ds q
  977. .\}
  978. .if t \{\
  979. .    ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
  980. .    ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
  981. .    ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
  982. .\}
  983. .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
  984. .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
  985. .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
  986. .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
  987. .ds oe o\h'-(\w'o'u*4/10)'e
  988. .ds Oe O\h'-(\w'O'u*4/10)'E
  989. .if \n(.H>23 .if \n(.V>19 \
  990. \{\
  991. .    ds v \h'-1'\o'\(aa\(ga'
  992. .    ds _ \h'-1'^
  993. .    ds . \h'-1'.
  994. .    ds 3 3
  995. .    ds oe oe
  996. .    ds Oe OE
  997. .\}
  998.  
  999. ############################################################################
  1000. # Documentation
  1001. ############################################################################
  1002.  
  1003. =head1 NAME
  1004.  
  1005. Pod::Man - Convert POD data to formatted *roff input
  1006.  
  1007. =head1 SYNOPSIS
  1008.  
  1009.     use Pod::Man;
  1010.     my $parser = Pod::Man->new (release => $VERSION, section => 8);
  1011.  
  1012.     # Read POD from STDIN and write to STDOUT.
  1013.     $parser->parse_from_filehandle;
  1014.  
  1015.     # Read POD from file.pod and write to file.1.
  1016.     $parser->parse_from_file ('file.pod', 'file.1');
  1017.  
  1018. =head1 DESCRIPTION
  1019.  
  1020. Pod::Man is a module to convert documentation in the POD format (the
  1021. preferred language for documenting Perl) into *roff input using the man
  1022. macro set.  The resulting *roff code is suitable for display on a terminal
  1023. using nroff(1), normally via man(1), or printing using troff(1).  It is
  1024. conventionally invoked using the driver script B<pod2man>, but it can also
  1025. be used directly.
  1026.  
  1027. As a derived class from Pod::Parser, Pod::Man supports the same methods and
  1028. interfaces.  See L<Pod::Parser> for all the details; briefly, one creates a
  1029. new parser with C<Pod::Man-E<gt>new()> and then calls either
  1030. parse_from_filehandle() or parse_from_file().
  1031.  
  1032. new() can take options, in the form of key/value pairs that control the
  1033. behavior of the parser.  See below for details.
  1034.  
  1035. If no options are given, Pod::Man uses the name of the input file with any
  1036. trailing C<.pod>, C<.pm>, or C<.pl> stripped as the man page title, to
  1037. section 1 unless the file ended in C<.pm> in which case it defaults to
  1038. section 3, to a centered title of "User Contributed Perl Documentation", to
  1039. a centered footer of the Perl version it is run with, and to a left-hand
  1040. footer of the modification date of its input (or the current date if given
  1041. STDIN for input).
  1042.  
  1043. Pod::Man assumes that your *roff formatters have a fixed-width font named
  1044. CW.  If yours is called something else (like CR), use the C<fixed> option to
  1045. specify it.  This generally only matters for troff output for printing.
  1046. Similarly, you can set the fonts used for bold, italic, and bold italic
  1047. fixed-width output.
  1048.  
  1049. Besides the obvious pod conversions, Pod::Man also takes care of formatting
  1050. func(), func(n), and simple variable references like $foo or @bar so you
  1051. don't have to use code escapes for them; complex expressions like
  1052. C<$fred{'stuff'}> will still need to be escaped, though.  It also translates
  1053. dashes that aren't used as hyphens into en dashes, makes long dashes--like
  1054. this--into proper em dashes, fixes "paired quotes," makes C++ and PI look
  1055. right, puts a little space between double underbars, makes ALLCAPS a teeny
  1056. bit smaller in troff(1), and escapes stuff that *roff treats as special so
  1057. that you don't have to.
  1058.  
  1059. The recognized options to new() are as follows.  All options take a single
  1060. argument.
  1061.  
  1062. =over 4
  1063.  
  1064. =item center
  1065.  
  1066. Sets the centered page header to use instead of "User Contributed Perl
  1067. Documentation".
  1068.  
  1069. =item date
  1070.  
  1071. Sets the left-hand footer.  By default, the modification date of the input
  1072. file will be used, or the current date if stat() can't find that file (the
  1073. case if the input is from STDIN), and the date will be formatted as
  1074. YYYY-MM-DD.
  1075.  
  1076. =item fixed
  1077.  
  1078. The fixed-width font to use for vertabim text and code.  Defaults to CW.
  1079. Some systems may want CR instead.  Only matters for troff(1) output.
  1080.  
  1081. =item fixedbold
  1082.  
  1083. Bold version of the fixed-width font.  Defaults to CB.  Only matters for
  1084. troff(1) output.
  1085.  
  1086. =item fixeditalic
  1087.  
  1088. Italic version of the fixed-width font (actually, something of a misnomer,
  1089. since most fixed-width fonts only have an oblique version, not an italic
  1090. version).  Defaults to CI.  Only matters for troff(1) output.
  1091.  
  1092. =item fixedbolditalic
  1093.  
  1094. Bold italic (probably actually oblique) version of the fixed-width font.
  1095. Pod::Man doesn't assume you have this, and defaults to CB.  Some systems
  1096. (such as Solaris) have this font available as CX.  Only matters for troff(1)
  1097. output.
  1098.  
  1099. =item release
  1100.  
  1101. Set the centered footer.  By default, this is the version of Perl you run
  1102. Pod::Man under.  Note that some system an macro sets assume that the
  1103. centered footer will be a modification date and will prepend something like
  1104. "Last modified: "; if this is the case, you may want to set C<release> to
  1105. the last modified date and C<date> to the version number.
  1106.  
  1107. =item section
  1108.  
  1109. Set the section for the C<.TH> macro.  The standard section numbering
  1110. convention is to use 1 for user commands, 2 for system calls, 3 for
  1111. functions, 4 for devices, 5 for file formats, 6 for games, 7 for
  1112. miscellaneous information, and 8 for administrator commands.  There is a lot
  1113. of variation here, however; some systems (like Solaris) use 4 for file
  1114. formats, 5 for miscellaneous information, and 7 for devices.  Still others
  1115. use 1m instead of 8, or some mix of both.  About the only section numbers
  1116. that are reliably consistent are 1, 2, and 3.
  1117.  
  1118. By default, section 1 will be used unless the file ends in .pm in which case
  1119. section 3 will be selected.
  1120.  
  1121. =back
  1122.  
  1123. The standard Pod::Parser method parse_from_filehandle() takes up to two
  1124. arguments, the first being the file handle to read POD from and the second
  1125. being the file handle to write the formatted output to.  The first defaults
  1126. to STDIN if not given, and the second defaults to STDOUT.  The method
  1127. parse_from_file() is almost identical, except that its two arguments are the
  1128. input and output disk files instead.  See L<Pod::Parser> for the specific
  1129. details.
  1130.  
  1131. =head1 DIAGNOSTICS
  1132.  
  1133. =over 4
  1134.  
  1135. =item roff font should be 1 or 2 chars, not `%s'
  1136.  
  1137. (F) You specified a *roff font (using C<fixed>, C<fixedbold>, etc.) that
  1138. wasn't either one or two characters.  Pod::Man doesn't support *roff fonts
  1139. longer than two characters, although some *roff extensions do (the canonical
  1140. versions of nroff(1) and troff(1) don't either).
  1141.  
  1142. =item Invalid link %s
  1143.  
  1144. (W) The POD source contained a C<LE<lt>E<gt>> sequence that Pod::Man was
  1145. unable to parse.  You should never see this error message; it probably
  1146. indicates a bug in Pod::Man.
  1147.  
  1148. =item Unknown escape EE<lt>%sE<gt>
  1149.  
  1150. (W) The POD source contained an C<EE<lt>E<gt>> escape that Pod::Man didn't
  1151. know about.  C<EE<lt>%sE<gt>> was printed verbatim in the output.
  1152.  
  1153. =item Unknown sequence %s
  1154.  
  1155. (W) The POD source contained a non-standard interior sequence (something of
  1156. the form C<XE<lt>E<gt>>) that Pod::Man didn't know about.  It was ignored.
  1157.  
  1158. =item Unmatched =back
  1159.  
  1160. (W) Pod::Man encountered a C<=back> command that didn't correspond to an
  1161. C<=over> command.
  1162.  
  1163. =back
  1164.  
  1165. =head1 BUGS
  1166.  
  1167. The lint-like features and strict POD format checking done by B<pod2man> are
  1168. not yet implemented and should be, along with the corresponding C<lax>
  1169. option.
  1170.  
  1171. The NAME section should be recognized specially and index entries emitted
  1172. for everything in that section.  This would have to be deferred until the
  1173. next section, since extraneous things in NAME tends to confuse various man
  1174. page processors.
  1175.  
  1176. The handling of hyphens, en dashes, and em dashes is somewhat fragile, and
  1177. one may get the wrong one under some circumstances.  This should only matter
  1178. for troff(1) output.
  1179.  
  1180. When and whether to use small caps is somewhat tricky, and Pod::Man doesn't
  1181. necessarily get it right.
  1182.  
  1183. Pod::Man doesn't handle font names longer than two characters.  Neither do
  1184. most troff(1) implementations, but GNU troff does as an extension.  It would
  1185. be nice to support as an option for those who want to use it.
  1186.  
  1187. The preamble added to each output file is rather verbose, and most of it is
  1188. only necessary in the presence of EE<lt>E<gt> escapes for non-ASCII
  1189. characters.  It would ideally be nice if all of those definitions were only
  1190. output if needed, perhaps on the fly as the characters are used.
  1191.  
  1192. Some of the automagic applied to file names assumes Unix directory
  1193. separators.
  1194.  
  1195. Pod::Man is excessively slow.
  1196.  
  1197. =head1 SEE ALSO
  1198.  
  1199. L<Pod::Parser|Pod::Parser>, perlpod(1), pod2man(1), nroff(1), troff(1),
  1200. man(1), man(7)
  1201.  
  1202. Ossanna, Joseph F., and Brian W. Kernighan.  "Troff User's Manual,"
  1203. Computing Science Technical Report No. 54, AT&T Bell Laboratories.  This is
  1204. the best documentation of standard nroff(1) and troff(1).  At the time of
  1205. this writing, it's available at http://www.cs.bell-labs.com/cm/cs/cstr.html.
  1206.  
  1207. The man page documenting the man macro set may be man(5) instead of man(7)
  1208. on your system.  Also, please see pod2man(1) for extensive documentation on
  1209. writing manual pages if you've not done it before and aren't familiar with
  1210. the conventions.
  1211.  
  1212. =head1 AUTHOR
  1213.  
  1214. Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the
  1215. original B<pod2man> by Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>.
  1216.  
  1217. =cut
  1218.