diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Pod/Man.pm')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Pod/Man.pm | 1413 |
1 files changed, 0 insertions, 1413 deletions
diff --git a/Master/tlpkg/tlperl/lib/Pod/Man.pm b/Master/tlpkg/tlperl/lib/Pod/Man.pm deleted file mode 100644 index 693e4c46896..00000000000 --- a/Master/tlpkg/tlperl/lib/Pod/Man.pm +++ /dev/null @@ -1,1413 +0,0 @@ -# Pod::Man -- Convert POD data to formatted *roff input. -# $Id: Man.pm,v 1.37 2003/03/30 22:34:11 eagle Exp $ -# -# Copyright 1999, 2000, 2001, 2002, 2003 by Russ Allbery <rra@stanford.edu> -# -# This program is free software; you may redistribute it and/or modify it -# under the same terms as Perl itself. -# -# This module translates POD documentation into *roff markup using the man -# macro set, and is intended for converting POD documents written as Unix -# manual pages to manual pages that can be read by the man(1) command. It is -# a replacement for the pod2man command distributed with versions of Perl -# prior to 5.6. -# -# Perl core hackers, please note that this module is also separately -# maintained outside of the Perl core as part of the podlators. Please send -# me any patches at the address above in addition to sending them to the -# standard Perl mailing lists. - -############################################################################## -# Modules and declarations -############################################################################## - -package Pod::Man; - -require 5.005; - -use Carp qw(carp croak); -use Pod::ParseLink qw(parselink); -use Pod::Parser (); - -use strict; -use subs qw(makespace); -use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION); - -@ISA = qw(Pod::Parser); - -# Don't use the CVS revision as the version, since this module is also in Perl -# core and too many things could munge CVS magic revision strings. This -# number should ideally be the same as the CVS revision in podlators, however. -$VERSION = 1.37; - - -############################################################################## -# Preamble and *roff output tables -############################################################################## - -# The following is the static preamble which starts all *roff output we -# generate. It's completely static except for the font to use as a -# fixed-width font, which is designed by @CFONT@, and the left and right -# quotes to use for C<> text, designated by @LQOUTE@ and @RQUOTE@. $PREAMBLE -# should therefore be run through s/\@CFONT\@/<font>/g before output. -$PREAMBLE = <<'----END OF PREAMBLE----'; -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft @CFONT@ -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` @LQUOTE@ -. ds C' @RQUOTE@ -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -----END OF PREAMBLE---- -#`# for cperl-mode - -# This table is taken nearly verbatim from Tom Christiansen's pod2man. It -# assumes that the standard preamble has already been printed, since that's -# what defines all of the accent marks. Note that some of these are quoted -# with double quotes since they contain embedded single quotes, so use \\ -# uniformly for backslash for readability. -%ESCAPES = ( - 'amp' => '&', # ampersand - 'apos' => "'", # apostrophe - 'lt' => '<', # left chevron, less-than - 'gt' => '>', # right chevron, greater-than - 'quot' => '"', # double quote - 'sol' => '/', # solidus (forward slash) - 'verbar' => '|', # vertical bar - - 'Aacute' => "A\\*'", # capital A, acute accent - 'aacute' => "a\\*'", # small a, acute accent - 'Acirc' => 'A\\*^', # capital A, circumflex accent - 'acirc' => 'a\\*^', # small a, circumflex accent - 'AElig' => '\*(AE', # capital AE diphthong (ligature) - 'aelig' => '\*(ae', # small ae diphthong (ligature) - 'Agrave' => "A\\*`", # capital A, grave accent - 'agrave' => "A\\*`", # small a, grave accent - 'Aring' => 'A\\*o', # capital A, ring - 'aring' => 'a\\*o', # small a, ring - 'Atilde' => 'A\\*~', # capital A, tilde - 'atilde' => 'a\\*~', # small a, tilde - 'Auml' => 'A\\*:', # capital A, dieresis or umlaut mark - 'auml' => 'a\\*:', # small a, dieresis or umlaut mark - 'Ccedil' => 'C\\*,', # capital C, cedilla - 'ccedil' => 'c\\*,', # small c, cedilla - 'Eacute' => "E\\*'", # capital E, acute accent - 'eacute' => "e\\*'", # small e, acute accent - 'Ecirc' => 'E\\*^', # capital E, circumflex accent - 'ecirc' => 'e\\*^', # small e, circumflex accent - 'Egrave' => 'E\\*`', # capital E, grave accent - 'egrave' => 'e\\*`', # small e, grave accent - 'ETH' => '\\*(D-', # capital Eth, Icelandic - 'eth' => '\\*(d-', # small eth, Icelandic - 'Euml' => 'E\\*:', # capital E, dieresis or umlaut mark - 'euml' => 'e\\*:', # small e, dieresis or umlaut mark - 'Iacute' => "I\\*'", # capital I, acute accent - 'iacute' => "i\\*'", # small i, acute accent - 'Icirc' => 'I\\*^', # capital I, circumflex accent - 'icirc' => 'i\\*^', # small i, circumflex accent - 'Igrave' => 'I\\*`', # capital I, grave accent - 'igrave' => 'i\\*`', # small i, grave accent - 'Iuml' => 'I\\*:', # capital I, dieresis or umlaut mark - 'iuml' => 'i\\*:', # small i, dieresis or umlaut mark - 'Ntilde' => 'N\*~', # capital N, tilde - 'ntilde' => 'n\*~', # small n, tilde - 'Oacute' => "O\\*'", # capital O, acute accent - 'oacute' => "o\\*'", # small o, acute accent - 'Ocirc' => 'O\\*^', # capital O, circumflex accent - 'ocirc' => 'o\\*^', # small o, circumflex accent - 'Ograve' => 'O\\*`', # capital O, grave accent - 'ograve' => 'o\\*`', # small o, grave accent - 'Oslash' => 'O\\*/', # capital O, slash - 'oslash' => 'o\\*/', # small o, slash - 'Otilde' => 'O\\*~', # capital O, tilde - 'otilde' => 'o\\*~', # small o, tilde - 'Ouml' => 'O\\*:', # capital O, dieresis or umlaut mark - 'ouml' => 'o\\*:', # small o, dieresis or umlaut mark - 'szlig' => '\*8', # small sharp s, German (sz ligature) - 'THORN' => '\\*(Th', # capital THORN, Icelandic - 'thorn' => '\\*(th', # small thorn, Icelandic - 'Uacute' => "U\\*'", # capital U, acute accent - 'uacute' => "u\\*'", # small u, acute accent - 'Ucirc' => 'U\\*^', # capital U, circumflex accent - 'ucirc' => 'u\\*^', # small u, circumflex accent - 'Ugrave' => 'U\\*`', # capital U, grave accent - 'ugrave' => 'u\\*`', # small u, grave accent - 'Uuml' => 'U\\*:', # capital U, dieresis or umlaut mark - 'uuml' => 'u\\*:', # small u, dieresis or umlaut mark - 'Yacute' => "Y\\*'", # capital Y, acute accent - 'yacute' => "y\\*'", # small y, acute accent - 'yuml' => 'y\\*:', # small y, dieresis or umlaut mark - - 'nbsp' => '\\ ', # non-breaking space - 'shy' => '', # soft (discretionary) hyphen -); - - -############################################################################## -# Static helper functions -############################################################################## - -# Protect leading quotes and periods against interpretation as commands. Also -# protect anything starting with a backslash, since it could expand or hide -# something that *roff would interpret as a command. This is overkill, but -# it's much simpler than trying to parse *roff here. -sub protect { - local $_ = shift; - s/^([.\'\\])/\\&$1/mg; - $_; -} - -# Translate a font string into an escape. -sub toescape { (length ($_[0]) > 1 ? '\f(' : '\f') . $_[0] } - - -############################################################################## -# Initialization -############################################################################## - -# Initialize the object. Here, we also process any additional options passed -# to the constructor or set up defaults if none were given. center is the -# centered title, release is the version number, and date is the date for the -# documentation. Note that we can't know what file name we're processing due -# to the architecture of Pod::Parser, so that *has* to either be passed to the -# constructor or set separately with Pod::Man::name(). -sub initialize { - my $self = shift; - - # Figure out the fixed-width font. If user-supplied, make sure that they - # are the right length. - for (qw/fixed fixedbold fixeditalic fixedbolditalic/) { - if (defined $$self{$_}) { - if (length ($$self{$_}) < 1 || length ($$self{$_}) > 2) { - croak qq(roff font should be 1 or 2 chars,) - . qq( not "$$self{$_}"); - } - } else { - $$self{$_} = ''; - } - } - - # Set the default fonts. We can't be sure what fixed bold-italic is going - # to be called, so default to just bold. - $$self{fixed} ||= 'CW'; - $$self{fixedbold} ||= 'CB'; - $$self{fixeditalic} ||= 'CI'; - $$self{fixedbolditalic} ||= 'CB'; - - # Set up a table of font escapes. First number is fixed-width, second is - # bold, third is italic. - $$self{FONTS} = { '000' => '\fR', '001' => '\fI', - '010' => '\fB', '011' => '\f(BI', - '100' => toescape ($$self{fixed}), - '101' => toescape ($$self{fixeditalic}), - '110' => toescape ($$self{fixedbold}), - '111' => toescape ($$self{fixedbolditalic})}; - - # Extra stuff for page titles. - $$self{center} = 'User Contributed Perl Documentation' - unless defined $$self{center}; - $$self{indent} = 4 unless defined $$self{indent}; - - # We used to try first to get the version number from a local binary, but - # we shouldn't need that any more. Get the version from the running Perl. - # Work a little magic to handle subversions correctly under both the - # pre-5.6 and the post-5.6 version numbering schemes. - if (!defined $$self{release}) { - my @version = ($] =~ /^(\d+)\.(\d{3})(\d{0,3})$/); - $version[2] ||= 0; - $version[2] *= 10 ** (3 - length $version[2]); - for (@version) { $_ += 0 } - $$self{release} = 'perl v' . join ('.', @version); - } - - # Double quotes in things that will be quoted. - for (qw/center date release/) { - $$self{$_} =~ s/\"/\"\"/g if $$self{$_}; - } - - # Figure out what quotes we'll be using for C<> text. - $$self{quotes} ||= '"'; - if ($$self{quotes} eq 'none') { - $$self{LQUOTE} = $$self{RQUOTE} = ''; - } elsif (length ($$self{quotes}) == 1) { - $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes}; - } elsif ($$self{quotes} =~ /^(.)(.)$/ - || $$self{quotes} =~ /^(..)(..)$/) { - $$self{LQUOTE} = $1; - $$self{RQUOTE} = $2; - } else { - croak qq(Invalid quote specification "$$self{quotes}"); - } - - # Double the first quote; note that this should not be s///g as two double - # quotes is represented in *roff as three double quotes, not four. Weird, - # I know. - $$self{LQUOTE} =~ s/\"/\"\"/; - $$self{RQUOTE} =~ s/\"/\"\"/; - - $self->SUPER::initialize; -} - -# For each document we process, output the preamble first. -sub begin_pod { - my $self = shift; - - # Try to figure out the name and section from the file name. - my $section = $$self{section} || 1; - my $name = $$self{name}; - if (!defined $name) { - $name = $self->input_file; - $section = 3 if (!$$self{section} && $name =~ /\.pm\z/i); - $name =~ s/\.p(od|[lm])\z//i; - if ($section !~ /^3/) { - require File::Basename; - $name = uc File::Basename::basename ($name); - } else { - # Assume that we're dealing with a module. We want to figure out - # the full module name from the path to the file, but we don't - # want to include too much of the path into the module name. Lose - # everything up to the first of: - # - # */lib/*perl*/ standard or site_perl module - # */*perl*/lib/ from -Dprefix=/opt/perl - # */*perl*/ random module hierarchy - # - # which works. Also strip off a leading site or site_perl - # component, any OS-specific component, and any version number - # component, and strip off an initial component of "lib" or - # "blib/lib" since that's what ExtUtils::MakeMaker creates. - # splitdir requires at least File::Spec 0.8. - require File::Spec; - my ($volume, $dirs, $file) = File::Spec->splitpath ($name); - my @dirs = File::Spec->splitdir ($dirs); - my $cut = 0; - my $i; - for ($i = 0; $i < scalar @dirs; $i++) { - if ($dirs[$i] eq 'lib' && $dirs[$i + 1] =~ /perl/) { - $cut = $i + 2; - last; - } elsif ($dirs[$i] =~ /perl/) { - $cut = $i + 1; - $cut++ if $dirs[$i + 1] eq 'lib'; - last; - } - } - if ($cut > 0) { - splice (@dirs, 0, $cut); - shift @dirs if ($dirs[0] =~ /^site(_perl)?$/); - shift @dirs if ($dirs[0] =~ /^[\d.]+$/); - shift @dirs if ($dirs[0] =~ /^(.*-$^O|$^O-.*|$^O)$/); - } - shift @dirs if $dirs[0] eq 'lib'; - splice (@dirs, 0, 2) if ($dirs[0] eq 'blib' && $dirs[1] eq 'lib'); - - # Remove empty directories when building the module name; they - # occur too easily on Unix by doubling slashes. - $name = join ('::', (grep { $_ ? $_ : () } @dirs), $file); - } - } - - # If $name contains spaces, quote it; this mostly comes up in the case of - # input from stdin. - $name = '"' . $name . '"' if ($name =~ /\s/); - - # Modification date header. Try to use the modification time of our - # input. - if (!defined $$self{date}) { - my $time = (stat $self->input_file)[9] || time; - my ($day, $month, $year) = (localtime $time)[3,4,5]; - $month++; - $year += 1900; - $$self{date} = sprintf ('%4d-%02d-%02d', $year, $month, $day); - } - - # Now, print out the preamble and the title. The meaning of the arguments - # to .TH unfortunately vary by system; some systems consider the fourth - # argument to be a "source" and others use it as a version number. - # Generally it's just presented as the left-side footer, though, so it - # doesn't matter too much if a particular system gives it another - # interpretation. - # - # The order of date and release used to be reversed in older versions of - # this module, but this order is correct for both Solaris and Linux. - local $_ = $PREAMBLE; - s/\@CFONT\@/$$self{fixed}/; - s/\@LQUOTE\@/$$self{LQUOTE}/; - s/\@RQUOTE\@/$$self{RQUOTE}/; - chomp $_; - my $pversion = $Pod::Parser::VERSION; - print { $self->output_handle } <<"----END OF HEADER----"; -.\\" Automatically generated by Pod::Man v$VERSION, Pod::Parser v$pversion -.\\" -.\\" Standard preamble: -.\\" ======================================================================== -$_ -.\\" ======================================================================== -.\\" -.IX Title "$name $section" -.TH $name $section "$$self{date}" "$$self{release}" "$$self{center}" -----END OF HEADER---- - - # Initialize a few per-file variables. - $$self{INDENT} = 0; # Current indentation level. - $$self{INDENTS} = []; # Stack of indentations. - $$self{INDEX} = []; # Index keys waiting to be printed. - $$self{IN_NAME} = 0; # Whether processing the NAME section. - $$self{ITEMS} = 0; # The number of consecutive =items. - $$self{ITEMTYPES} = []; # Stack of =item types, one per list. - $$self{SHIFTWAIT} = 0; # Whether there is a shift waiting. - $$self{SHIFTS} = []; # Stack of .RS shifts. -} - - -############################################################################## -# Core overrides -############################################################################## - -# Called for each command paragraph. Gets the command, the associated -# paragraph, the line number, and a Pod::Paragraph object. Just dispatches -# the command to a method named the same as the command. =cut is handled -# internally by Pod::Parser. -sub command { - my $self = shift; - my $command = shift; - return if $command eq 'pod'; - return if ($$self{EXCLUDE} && $command ne 'end'); - if ($self->can ('cmd_' . $command)) { - $command = 'cmd_' . $command; - $self->$command (@_); - } else { - my ($text, $line, $paragraph) = @_; - my $file; - ($file, $line) = $paragraph->file_line; - $text =~ s/\n+\z//; - $text = " $text" if ($text =~ /^\S/); - warn qq($file:$line: Unknown command paragraph "=$command$text"\n); - return; - } -} - -# Called for a verbatim paragraph. Gets the paragraph, the line number, and a -# Pod::Paragraph object. Rofficate backslashes, untabify, put a zero-width -# character at the beginning of each line to protect against commands, and -# wrap in .Vb/.Ve. -sub verbatim { - my $self = shift; - return if $$self{EXCLUDE}; - local $_ = shift; - return if /^\s+$/; - s/\s+$/\n/; - my $lines = tr/\n/\n/; - 1 while s/^(.*?)(\t+)/$1 . ' ' x (length ($2) * 8 - length ($1) % 8)/me; - s/\\/\\e/g; - s/-/\\-/g; - s/'/\\(aq/g; - s/^(\s*\S)/'\&' . $1/gme; - $self->makespace; - $self->output (".Vb $lines\n$_.Ve\n"); - $$self{NEEDSPACE} = 1; -} - -# Called for a regular text block. Gets the paragraph, the line number, and a -# Pod::Paragraph object. Perform interpolation and output the results. -sub textblock { - my $self = shift; - return if $$self{EXCLUDE}; - $self->output ($_[0]), return if $$self{VERBATIM}; - - # Parse the tree. collapse knows about references to scalars as well as - # scalars and does the right thing with them. Tidy up any trailing - # whitespace. - my $text = shift; - $text = $self->parse ($text, @_); - $text =~ s/\n\s*$/\n/; - - # Output the paragraph. We also have to handle =over without =item. If - # there's an =over without =item, SHIFTWAIT will be set, and we need to - # handle creation of the indent here. Add the shift to SHIFTS so that it - # will be cleaned up on =back. - $self->makespace; - if ($$self{SHIFTWAIT}) { - $self->output (".RS $$self{INDENT}\n"); - push (@{ $$self{SHIFTS} }, $$self{INDENT}); - $$self{SHIFTWAIT} = 0; - } - $self->output (protect $self->textmapfonts ($text)); - $self->outindex; - $$self{NEEDSPACE} = 1; -} - -# Called for a formatting code. Takes a Pod::InteriorSequence object and -# returns a reference to a scalar. This scalar is the final formatted text. -# It's returned as a reference to an array so that other formatting codes -# above us know that the text has already been processed. -sub sequence { - my ($self, $seq) = @_; - my $command = $seq->cmd_name; - - # We have to defer processing of the inside of an L<> formatting code. If - # this code is nested inside an L<> code, return the literal raw text of - # it. - my $parent = $seq->nested; - while (defined $parent) { - return $seq->raw_text if ($parent->cmd_name eq 'L'); - $parent = $parent->nested; - } - - # Zero-width characters. - return [ '\&' ] if ($command eq 'Z'); - - # C<>, L<>, X<>, and E<> don't apply guesswork to their contents. C<> - # needs some additional special handling. - my $literal = ($command =~ /^[CELX]$/); - local $_ = $self->collapse ($seq->parse_tree, $literal, $command eq 'C'); - - # Handle E<> escapes. Numeric escapes that match one of the supported ISO - # 8859-1 characters don't work at present. - if ($command eq 'E') { - if (/^\d+$/) { - return [ chr ($_) ]; - } elsif (exists $ESCAPES{$_}) { - return [ $ESCAPES{$_} ]; - } else { - my ($file, $line) = $seq->file_line; - warn "$file:$line: Unknown escape E<$_>\n"; - return [ "E<$_>" ]; - } - } - - # For all the other codes, empty content produces no output. - return '' if $_ eq ''; - - # Handle simple formatting codes. - if ($command eq 'B') { - return [ '\f(BS' . $_ . '\f(BE' ]; - } elsif ($command eq 'F' || $command eq 'I') { - return [ '\f(IS' . $_ . '\f(IE' ]; - } elsif ($command eq 'C') { - return [ $self->quote_literal ($_) ]; - } - - # Handle links. - if ($command eq 'L') { - my ($text, $type) = (parselink ($_))[1,4]; - return '' unless $text; - my ($file, $line) = $seq->file_line; - $text = $self->parse ($text, $line); - $text = '<' . $text . '>' if $type eq 'url'; - return [ $text ]; - } - - # Whitespace protection replaces whitespace with "\ ". - if ($command eq 'S') { - s/\s+/\\ /g; - return [ $_ ]; - } - - # Add an index entry to the list of ones waiting to be output. - if ($command eq 'X') { - push (@{ $$self{INDEX} }, $_); - return ''; - } - - # Anything else is unknown. - my ($file, $line) = $seq->file_line; - warn "$file:$line: Unknown formatting code $command<$_>\n"; -} - - -############################################################################## -# Command paragraphs -############################################################################## - -# All command paragraphs take the paragraph and the line number. - -# First level heading. We can't output .IX in the NAME section due to a bug -# in some versions of catman, so don't output a .IX for that section. .SH -# already uses small caps, so remove \s1 and \s-1. Maintain IN_NAME as -# appropriate, but don't leave it set while calling parse() so as to not -# override guesswork on section headings after NAME. -sub cmd_head1 { - my $self = shift; - $$self{IN_NAME} = 0; - local $_ = $self->parse (@_); - s/\s+$//; - s/\\s-?\d//g; - s/\s*\n\s*/ /g; - if ($$self{ITEMS} > 1) { - $$self{ITEMS} = 0; - $self->output (".PD\n"); - } - $self->output ($self->switchquotes ('.SH', $self->mapfonts ($_))); - $self->outindex (($_ eq 'NAME') ? () : ('Header', $_)); - $$self{NEEDSPACE} = 0; - $$self{IN_NAME} = ($_ eq 'NAME'); -} - -# Second level heading. -sub cmd_head2 { - my $self = shift; - local $_ = $self->parse (@_); - s/\s+$//; - s/\s*\n\s*/ /g; - if ($$self{ITEMS} > 1) { - $$self{ITEMS} = 0; - $self->output (".PD\n"); - } - $self->output ($self->switchquotes ('.Sh', $self->mapfonts ($_))); - $self->outindex ('Subsection', $_); - $$self{NEEDSPACE} = 0; -} - -# Third level heading. -sub cmd_head3 { - my $self = shift; - local $_ = $self->parse (@_); - s/\s+$//; - s/\s*\n\s*/ /g; - if ($$self{ITEMS} > 1) { - $$self{ITEMS} = 0; - $self->output (".PD\n"); - } - $self->makespace; - $self->output ($self->textmapfonts ('\f(IS' . $_ . '\f(IE') . "\n"); - $self->outindex ('Subsection', $_); - $$self{NEEDSPACE} = 1; -} - -# Fourth level heading. -sub cmd_head4 { - my $self = shift; - local $_ = $self->parse (@_); - s/\s+$//; - s/\s*\n\s*/ /g; - if ($$self{ITEMS} > 1) { - $$self{ITEMS} = 0; - $self->output (".PD\n"); - } - $self->makespace; - $self->output ($self->textmapfonts ($_) . "\n"); - $self->outindex ('Subsection', $_); - $$self{NEEDSPACE} = 1; -} - -# Start a list. For indents after the first, wrap the outside indent in .RS -# so that hanging paragraph tags will be correct. -sub cmd_over { - my $self = shift; - local $_ = shift; - unless (/^[-+]?\d+\s+$/) { $_ = $$self{indent} } - if (@{ $$self{SHIFTS} } < @{ $$self{INDENTS} }) { - $self->output (".RS $$self{INDENT}\n"); - push (@{ $$self{SHIFTS} }, $$self{INDENT}); - } - push (@{ $$self{INDENTS} }, $$self{INDENT}); - push (@{ $$self{ITEMTYPES} }, 'unknown'); - $$self{INDENT} = ($_ + 0); - $$self{SHIFTWAIT} = 1; -} - -# End a list. If we've closed an embedded indent, we've mangled the hanging -# paragraph indent, so temporarily replace it with .RS and set WEIRDINDENT. -# We'll close that .RS at the next =back or =item. -sub cmd_back { - my $self = shift; - $$self{INDENT} = pop @{ $$self{INDENTS} }; - if (defined $$self{INDENT}) { - pop @{ $$self{ITEMTYPES} }; - } else { - my ($file, $line, $paragraph) = @_; - ($file, $line) = $paragraph->file_line; - warn "$file:$line: Unmatched =back\n"; - $$self{INDENT} = 0; - } - if (@{ $$self{SHIFTS} } > @{ $$self{INDENTS} }) { - $self->output (".RE\n"); - pop @{ $$self{SHIFTS} }; - } - if (@{ $$self{INDENTS} } > 0) { - $self->output (".RE\n"); - $self->output (".RS $$self{INDENT}\n"); - } - $$self{NEEDSPACE} = 1; - $$self{SHIFTWAIT} = 0; -} - -# An individual list item. Emit an index entry for anything that's -# interesting, but don't emit index entries for things like bullets and -# numbers. rofficate bullets too while we're at it (so for nice output, use * -# for your lists rather than o or . or - or some other thing). Newlines in an -# item title are turned into spaces since *roff can't handle them embedded. -sub cmd_item { - my $self = shift; - local $_ = $self->parse (@_); - s/\s+$//; - s/\s*\n\s*/ /g; - my $index; - if (/\w/ && !/^\w[.\)]\s*$/) { - $index = $_; - $index =~ s/^\s*[-*+o.]?(?:\s+|\Z)//; - } - $_ = '*' unless length ($_) > 0; - my $type = $$self{ITEMTYPES}[0]; - unless (defined $type) { - my ($file, $line, $paragraph) = @_; - ($file, $line) = $paragraph->file_line; - $type = 'unknown'; - } - if ($type eq 'unknown') { - $type = /^\*\s*\Z/ ? 'bullet' : 'text'; - $$self{ITEMTYPES}[0] = $type if $$self{ITEMTYPES}[0]; - } - s/^\*\s*\Z/\\\(bu/ if $type eq 'bullet'; - if (@{ $$self{SHIFTS} } == @{ $$self{INDENTS} }) { - $self->output (".RE\n"); - pop @{ $$self{SHIFTS} }; - } - $_ = $self->textmapfonts ($_); - $self->output (".PD 0\n") if ($$self{ITEMS} == 1); - $self->output ($self->switchquotes ('.IP', $_, $$self{INDENT})); - $self->outindex ($index ? ('Item', $index) : ()); - $$self{NEEDSPACE} = 0; - $$self{ITEMS}++; - $$self{SHIFTWAIT} = 0; -} - -# Begin a block for a particular translator. Setting VERBATIM triggers -# special handling in textblock(). -sub cmd_begin { - my $self = shift; - local $_ = shift; - my ($kind) = /^(\S+)/ or return; - if ($kind eq 'man' || $kind eq 'roff') { - $$self{VERBATIM} = 1; - } else { - $$self{EXCLUDE} = 1; - } -} - -# End a block for a particular translator. We assume that all =begin/=end -# pairs are properly closed. -sub cmd_end { - my $self = shift; - $$self{EXCLUDE} = 0; - $$self{VERBATIM} = 0; -} - -# One paragraph for a particular translator. Ignore it unless it's intended -# for man or roff, in which case we output it verbatim. -sub cmd_for { - my $self = shift; - local $_ = shift; - return unless s/^(?:man|roff)\b[ \t]*\n?//; - $self->output ($_); -} - - -############################################################################## -# Escaping and fontification -############################################################################## - -# At this point, we'll have embedded font codes of the form \f(<font>[SE] -# where <font> is one of B, I, or F. Turn those into the right font start or -# end codes. The old pod2man didn't get B<someI<thing> else> right; after I<> -# it switched back to normal text rather than bold. We take care of this by -# using variables as a combined pointer to our current font sequence, and set -# each to the number of current nestings of start tags for that font. Use -# them as a vector to look up what font sequence to use. -# -# \fP changes to the previous font, but only one previous font is kept. We -# don't know what the outside level font is; normally it's R, but if we're -# inside a heading it could be something else. So arrange things so that the -# outside font is always the "previous" font and end with \fP instead of \fR. -# Idea from Zack Weinberg. -sub mapfonts { - my $self = shift; - local $_ = shift; - - my ($fixed, $bold, $italic) = (0, 0, 0); - my %magic = (F => \$fixed, B => \$bold, I => \$italic); - my $last = '\fR'; - s { \\f\((.)(.) } { - my $sequence = ''; - my $f; - if ($last ne '\fR') { $sequence = '\fP' } - ${ $magic{$1} } += ($2 eq 'S') ? 1 : -1; - $f = $$self{FONTS}{($fixed && 1) . ($bold && 1) . ($italic && 1)}; - if ($f eq $last) { - ''; - } else { - if ($f ne '\fR') { $sequence .= $f } - $last = $f; - $sequence; - } - }gxe; - $_; -} - -# Unfortunately, there is a bug in Solaris 2.6 nroff (not present in GNU -# groff) where the sequence \fB\fP\f(CW\fP leaves the font set to B rather -# than R, presumably because \f(CW doesn't actually do a font change. To work -# around this, use a separate textmapfonts for text blocks where the default -# font is always R and only use the smart mapfonts for headings. -sub textmapfonts { - my $self = shift; - local $_ = shift; - - my ($fixed, $bold, $italic) = (0, 0, 0); - my %magic = (F => \$fixed, B => \$bold, I => \$italic); - s { \\f\((.)(.) } { - ${ $magic{$1} } += ($2 eq 'S') ? 1 : -1; - $$self{FONTS}{($fixed && 1) . ($bold && 1) . ($italic && 1)}; - }gxe; - $_; -} - - -############################################################################## -# *roff-specific parsing and magic -############################################################################## - -# Called instead of parse_text, calls parse_text with the right flags. -sub parse { - my $self = shift; - $self->parse_text ({ -expand_seq => 'sequence', - -expand_ptree => 'collapse' }, @_); -} - -# Takes a parse tree, a flag saying whether or not to treat it as literal text -# (not call guesswork on it), and a flag saying whether or not to clean some -# things up for *roff, and returns the concatenation of all of the text -# strings in that parse tree. If the literal flag isn't true, guesswork() -# will be called on all plain scalars in the parse tree. Otherwise, if -# collapse is being called on a C<> code, $cleanup should be set to true and -# some additional cleanup will be done. Assumes that everything in the parse -# tree is either a scalar or a reference to a scalar. -sub collapse { - my ($self, $ptree, $literal, $cleanup) = @_; - - # If we're processing the NAME section, don't do normal guesswork. This - # is because NAME lines are often extracted by utilities like catman that - # require plain text and don't understand *roff markup. We still need to - # escape backslashes and hyphens for *roff (and catman expects \- instead - # of -). - if ($$self{IN_NAME}) { - $literal = 1; - $cleanup = 1; - } - - # Do the collapse of the parse tree as described above. - return join ('', map { - if (ref $_) { - join ('', @$_); - } elsif ($literal) { - if ($cleanup) { - s/\\/\\e/g; - s/-/\\-/g; - s/__/_\\|_/g; - } - $_; - } else { - $self->guesswork ($_); - } - } $ptree->children); -} - -# Takes a text block to perform guesswork on; this is guaranteed not to -# contain any formatting codes. Returns the text block with remapping done. -sub guesswork { - my $self = shift; - local $_ = shift; - - # rofficate backslashes. - s/\\/\\e/g; - - # Ensure double underbars have a tiny space between them. - s/__/_\\|_/g; - - # Leave hyphens only if they're part of regular words and there is only - # one dash at a time. Leave a dash after the first character as a regular - # non-breaking dash, but don't let it mark the rest of the word invalid - # for hyphenation. - s/-/\\-/g; - s{ - ( (?:\G|^|\s) [a-zA-Z] ) ( \\- )? - ( (?: [a-zA-Z]+ \\-)+ ) - ( [a-zA-Z]+ ) (?=\s|\Z) - \b - } { - my ($prefix, $hyphen, $main, $suffix) = ($1, $2, $3, $4); - $hyphen ||= ''; - $main =~ s/\\-/-/g; - $prefix . $hyphen . $main . $suffix; - }egx; - - # Translate -- into a real em dash if it's used like one. - s{ (\s) \\-\\- (\s) } { $1 . '\*(--' . $2 }egx; - s{ (\b[a-zA-Z]+) \\-\\- (\s|\Z|[a-zA-Z]+\b) } { $1 . '\*(--' . $2 }egx; - - # Make all caps a little smaller. Be careful here, since we don't want to - # make @ARGV into small caps, nor do we want to fix the MIME in - # MIME-Version, since it looks weird with the full-height V. - s{ - ( ^ | [\s\(\"\'\`\[\{<>] ) - ( [A-Z] [A-Z] (?: [/A-Z+:\d_\$&] | \\- )* ) - (?= [\s>\}\]\(\)\'\".?!,;] | \\*\(-- | $ ) - } { $1 . '\s-1' . $2 . '\s0' }egx; - - # Italize functions in the form func(). - s{ - ( \b | \\s-1 ) - ( - [A-Za-z_] ([:\w]|\\s-?[01])+ \(\) - ) - } { $1 . '\f(IS' . $2 . '\f(IE' }egx; - - # func(n) is a reference to a manual page. Make it \fIfunc\fR\|(n). - s{ - ( \b | \\s-1 ) - ( [A-Za-z_] (?:[.:\w]|\\-|\\s-?[01])+ ) - ( - \( \d [a-z]* \) - ) - } { $1 . '\f(IS' . $2 . '\f(IE\|' . $3 }egx; - - # Convert simple Perl variable references to a fixed-width font. - s{ - ( \s+ ) - ( [\$\@%] [\w:]+ ) - (?! \( ) - } { $1 . '\f(FS' . $2 . '\f(FE'}egx; - - # Fix up double quotes. - s{ \" ([^\"]+) \" } { '\*(L"' . $1 . '\*(R"' }egx; - - # Make C++ into \*(C+, which is a squinched version. - s{ \b C\+\+ } {\\*\(C+}gx; - - # All done. - $_; -} - -# Handles C<> text, deciding whether to put \*C` around it or not. This is a -# whole bunch of messy heuristics to try to avoid overquoting, originally from -# Barrie Slaymaker. This largely duplicates similar code in Pod::Text. -sub quote_literal { - my $self = shift; - local $_ = shift; - - # A regex that matches the portion of a variable reference that's the - # array or hash index, separated out just because we want to use it in - # several places in the following regex. - my $index = '(?: \[.*\] | \{.*\} )?'; - - # Check for things that we don't want to quote, and if we find any of - # them, return the string with just a font change and no quoting. - m{ - ^\s* - (?: - ( [\'\`\"] ) .* \1 # already quoted - | \` .* \' # `quoted' - | \$+ [\#^]? \S $index # special ($^Foo, $") - | [\$\@%&*]+ \#? [:\'\w]+ $index # plain var or func - | [\$\@%&*]* [:\'\w]+ (?: -> )? \(\s*[^\s,]\s*\) # 0/1-arg func call - | [+-]? ( \d[\d.]* | \.\d+ ) (?: [eE][+-]?\d+ )? # a number - | 0x [a-fA-F\d]+ # a hex constant - ) - \s*\z - }xo && return '\f(FS' . $_ . '\f(FE'; - - # If we didn't return, go ahead and quote the text. - return '\f(FS\*(C`' . $_ . "\\*(C'\\f(FE"; -} - - -############################################################################## -# Output formatting -############################################################################## - -# Make vertical whitespace. -sub makespace { - my $self = shift; - $self->output (".PD\n") if ($$self{ITEMS} > 1); - $$self{ITEMS} = 0; - $self->output ($$self{INDENT} > 0 ? ".Sp\n" : ".PP\n") - if $$self{NEEDSPACE}; -} - -# Output any pending index entries, and optionally an index entry given as an -# argument. Support multiple index entries in X<> separated by slashes, and -# strip special escapes from index entries. -sub outindex { - my ($self, $section, $index) = @_; - my @entries = map { split m%\s*/\s*% } @{ $$self{INDEX} }; - return unless ($section || @entries); - $$self{INDEX} = []; - my @output; - if (@entries) { - push (@output, [ 'Xref', join (' ', @entries) ]); - } - if ($section) { - $index =~ s/\\-/-/g; - $index =~ s/\\(?:s-?\d|.\(..|.)//g; - push (@output, [ $section, $index ]); - } - for (@output) { - my ($type, $entry) = @$_; - $entry =~ s/\"/\"\"/g; - $entry =~ s/\\/\\e/g; - $self->output (".IX $type " . '"' . $entry . '"' . "\n"); - } -} - -# Output text to the output device. -sub output { print { $_[0]->output_handle } $_[1] } - -# Given a command and a single argument that may or may not contain double -# quotes, handle double-quote formatting for it. If there are no double -# quotes, just return the command followed by the argument in double quotes. -# If there are double quotes, use an if statement to test for nroff, and for -# nroff output the command followed by the argument in double quotes with -# embedded double quotes doubled. For other formatters, remap paired double -# quotes to LQUOTE and RQUOTE. -sub switchquotes { - my $self = shift; - my $command = shift; - local $_ = shift; - my $extra = shift; - s/\\\*\([LR]\"/\"/g; - - # We also have to deal with \*C` and \*C', which are used to add the - # quotes around C<> text, since they may expand to " and if they do this - # confuses the .SH macros and the like no end. Expand them ourselves. - # Also separate troff from nroff if there are any fixed-width fonts in use - # to work around problems with Solaris nroff. - my $c_is_quote = ($$self{LQUOTE} =~ /\"/) || ($$self{RQUOTE} =~ /\"/); - my $fixedpat = join ('|', @{ $$self{FONTS} }{'100', '101', '110', '111'}); - $fixedpat =~ s/\\/\\\\/g; - $fixedpat =~ s/\(/\\\(/g; - if (/\"/ || /$fixedpat/) { - s/\"/\"\"/g; - my $nroff = $_; - my $troff = $_; - $troff =~ s/\"\"([^\"]*)\"\"/\`\`$1\'\'/g; - if ($c_is_quote && /\\\*\(C[\'\`]/) { - $nroff =~ s/\\\*\(C\`/$$self{LQUOTE}/g; - $nroff =~ s/\\\*\(C\'/$$self{RQUOTE}/g; - $troff =~ s/\\\*\(C[\'\`]//g; - } - $nroff = qq("$nroff") . ($extra ? " $extra" : ''); - $troff = qq("$troff") . ($extra ? " $extra" : ''); - - # Work around the Solaris nroff bug where \f(CW\fP leaves the font set - # to Roman rather than the actual previous font when used in headings. - # troff output may still be broken, but at least we can fix nroff by - # just switching the font changes to the non-fixed versions. - $nroff =~ s/\Q$$self{FONTS}{100}\E(.*)\\f[PR]/$1/g; - $nroff =~ s/\Q$$self{FONTS}{101}\E(.*)\\f([PR])/\\fI$1\\f$2/g; - $nroff =~ s/\Q$$self{FONTS}{110}\E(.*)\\f([PR])/\\fB$1\\f$2/g; - $nroff =~ s/\Q$$self{FONTS}{111}\E(.*)\\f([PR])/\\f\(BI$1\\f$2/g; - - # Now finally output the command. Only bother with .ie if the nroff - # and troff output isn't the same. - if ($nroff ne $troff) { - return ".ie n $command $nroff\n.el $command $troff\n"; - } else { - return "$command $nroff\n"; - } - } else { - $_ = qq("$_") . ($extra ? " $extra" : ''); - return "$command $_\n"; - } -} - -############################################################################## -# Module return value and documentation -############################################################################## - -1; -__END__ - -=head1 NAME - -Pod::Man - Convert POD data to formatted *roff input - -=head1 SYNOPSIS - - use Pod::Man; - my $parser = Pod::Man->new (release => $VERSION, section => 8); - - # Read POD from STDIN and write to STDOUT. - $parser->parse_from_filehandle; - - # Read POD from file.pod and write to file.1. - $parser->parse_from_file ('file.pod', 'file.1'); - -=head1 DESCRIPTION - -Pod::Man is a module to convert documentation in the POD format (the -preferred language for documenting Perl) into *roff input using the man -macro set. The resulting *roff code is suitable for display on a terminal -using L<nroff(1)>, normally via L<man(1)>, or printing using L<troff(1)>. -It is conventionally invoked using the driver script B<pod2man>, but it can -also be used directly. - -As a derived class from Pod::Parser, Pod::Man supports the same methods and -interfaces. See L<Pod::Parser> for all the details; briefly, one creates a -new parser with C<< Pod::Man->new() >> and then calls either -parse_from_filehandle() or parse_from_file(). - -new() can take options, in the form of key/value pairs that control the -behavior of the parser. See below for details. - -If no options are given, Pod::Man uses the name of the input file with any -trailing C<.pod>, C<.pm>, or C<.pl> stripped as the man page title, to -section 1 unless the file ended in C<.pm> in which case it defaults to -section 3, to a centered title of "User Contributed Perl Documentation", to -a centered footer of the Perl version it is run with, and to a left-hand -footer of the modification date of its input (or the current date if given -STDIN for input). - -Pod::Man assumes that your *roff formatters have a fixed-width font named -CW. If yours is called something else (like CR), use the C<fixed> option to -specify it. This generally only matters for troff output for printing. -Similarly, you can set the fonts used for bold, italic, and bold italic -fixed-width output. - -Besides the obvious pod conversions, Pod::Man also takes care of formatting -func(), func(3), and simple variable references like $foo or @bar so you -don't have to use code escapes for them; complex expressions like -C<$fred{'stuff'}> will still need to be escaped, though. It also translates -dashes that aren't used as hyphens into en dashes, makes long dashes--like -this--into proper em dashes, fixes "paired quotes," makes C++ look right, -puts a little space between double underbars, makes ALLCAPS a teeny bit -smaller in B<troff>, and escapes stuff that *roff treats as special so that -you don't have to. - -The recognized options to new() are as follows. All options take a single -argument. - -=over 4 - -=item center - -Sets the centered page header to use instead of "User Contributed Perl -Documentation". - -=item date - -Sets the left-hand footer. By default, the modification date of the input -file will be used, or the current date if stat() can't find that file (the -case if the input is from STDIN), and the date will be formatted as -YYYY-MM-DD. - -=item fixed - -The fixed-width font to use for vertabim text and code. Defaults to CW. -Some systems may want CR instead. Only matters for B<troff> output. - -=item fixedbold - -Bold version of the fixed-width font. Defaults to CB. Only matters for -B<troff> output. - -=item fixeditalic - -Italic version of the fixed-width font (actually, something of a misnomer, -since most fixed-width fonts only have an oblique version, not an italic -version). Defaults to CI. Only matters for B<troff> output. - -=item fixedbolditalic - -Bold italic (probably actually oblique) version of the fixed-width font. -Pod::Man doesn't assume you have this, and defaults to CB. Some systems -(such as Solaris) have this font available as CX. Only matters for B<troff> -output. - -=item name - -Set the name of the manual page. Without this option, the manual name is -set to the uppercased base name of the file being converted unless the -manual section is 3, in which case the path is parsed to see if it is a Perl -module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted into -a name like C<Pod::Man>. This option, if given, overrides any automatic -determination of the name. - -=item quotes - -Sets the quote marks used to surround CE<lt>> text. If the value is a -single character, it is used as both the left and right quote; if it is two -characters, the first character is used as the left quote and the second as -the right quoted; and if it is four characters, the first two are used as -the left quote and the second two as the right quote. - -This may also be set to the special value C<none>, in which case no quote -marks are added around CE<lt>> text (but the font is still changed for troff -output). - -=item release - -Set the centered footer. By default, this is the version of Perl you run -Pod::Man under. Note that some system an macro sets assume that the -centered footer will be a modification date and will prepend something like -"Last modified: "; if this is the case, you may want to set C<release> to -the last modified date and C<date> to the version number. - -=item section - -Set the section for the C<.TH> macro. The standard section numbering -convention is to use 1 for user commands, 2 for system calls, 3 for -functions, 4 for devices, 5 for file formats, 6 for games, 7 for -miscellaneous information, and 8 for administrator commands. There is a lot -of variation here, however; some systems (like Solaris) use 4 for file -formats, 5 for miscellaneous information, and 7 for devices. Still others -use 1m instead of 8, or some mix of both. About the only section numbers -that are reliably consistent are 1, 2, and 3. - -By default, section 1 will be used unless the file ends in .pm in which case -section 3 will be selected. - -=back - -The standard Pod::Parser method parse_from_filehandle() takes up to two -arguments, the first being the file handle to read POD from and the second -being the file handle to write the formatted output to. The first defaults -to STDIN if not given, and the second defaults to STDOUT. The method -parse_from_file() is almost identical, except that its two arguments are the -input and output disk files instead. See L<Pod::Parser> for the specific -details. - -=head1 DIAGNOSTICS - -=over 4 - -=item roff font should be 1 or 2 chars, not "%s" - -(F) You specified a *roff font (using C<fixed>, C<fixedbold>, etc.) that -wasn't either one or two characters. Pod::Man doesn't support *roff fonts -longer than two characters, although some *roff extensions do (the canonical -versions of B<nroff> and B<troff> don't either). - -=item Invalid link %s - -(W) The POD source contained a C<LE<lt>E<gt>> formatting code that -Pod::Man was unable to parse. You should never see this error message; it -probably indicates a bug in Pod::Man. - -=item Invalid quote specification "%s" - -(F) The quote specification given (the quotes option to the constructor) was -invalid. A quote specification must be one, two, or four characters long. - -=item %s:%d: Unknown command paragraph "%s". - -(W) The POD source contained a non-standard command paragraph (something of -the form C<=command args>) that Pod::Man didn't know about. It was ignored. - -=item %s:%d: Unknown escape EE<lt>%sE<gt> - -(W) The POD source contained an C<EE<lt>E<gt>> escape that Pod::Man didn't -know about. C<EE<lt>%sE<gt>> was printed verbatim in the output. - -=item %s:%d: Unknown formatting code %s - -(W) The POD source contained a non-standard formatting code (something of -the form C<XE<lt>E<gt>>) that Pod::Man didn't know about. It was ignored. - -=item %s:%d: Unmatched =back - -(W) Pod::Man encountered a C<=back> command that didn't correspond to an -C<=over> command. - -=back - -=head1 BUGS - -Eight-bit input data isn't handled at all well at present. The correct -approach would be to map EE<lt>E<gt> escapes to the appropriate UTF-8 -characters and then do a translation pass on the output according to the -user-specified output character set. Unfortunately, we can't send eight-bit -data directly to the output unless the user says this is okay, since some -vendor *roff implementations can't handle eight-bit data. If the *roff -implementation can, however, that's far superior to the current hacked -characters that only work under troff. - -There is currently no way to turn off the guesswork that tries to format -unmarked text appropriately, and sometimes it isn't wanted (particularly -when using POD to document something other than Perl). - -The NAME section should be recognized specially and index entries emitted -for everything in that section. This would have to be deferred until the -next section, since extraneous things in NAME tends to confuse various man -page processors. - -Pod::Man doesn't handle font names longer than two characters. Neither do -most B<troff> implementations, but GNU troff does as an extension. It would -be nice to support as an option for those who want to use it. - -The preamble added to each output file is rather verbose, and most of it is -only necessary in the presence of EE<lt>E<gt> escapes for non-ASCII -characters. It would ideally be nice if all of those definitions were only -output if needed, perhaps on the fly as the characters are used. - -Pod::Man is excessively slow. - -=head1 CAVEATS - -The handling of hyphens and em dashes is somewhat fragile, and one may get -the wrong one under some circumstances. This should only matter for -B<troff> output. - -When and whether to use small caps is somewhat tricky, and Pod::Man doesn't -necessarily get it right. - -=head1 SEE ALSO - -L<Pod::Parser>, L<perlpod(1)>, L<pod2man(1)>, L<nroff(1)>, L<troff(1)>, -L<man(1)>, L<man(7)> - -Ossanna, Joseph F., and Brian W. Kernighan. "Troff User's Manual," -Computing Science Technical Report No. 54, AT&T Bell Laboratories. This is -the best documentation of standard B<nroff> and B<troff>. At the time of -this writing, it's available at -L<http://www.cs.bell-labs.com/cm/cs/cstr.html>. - -The man page documenting the man macro set may be L<man(5)> instead of -L<man(7)> on your system. Also, please see L<pod2man(1)> for extensive -documentation on writing manual pages if you've not done it before and -aren't familiar with the conventions. - -The current version of this module is always available from its web site at -L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the -Perl core distribution as of 5.6.0. - -=head1 AUTHOR - -Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original -B<pod2man> by Tom Christiansen <tchrist@mox.perl.com>. - -=head1 COPYRIGHT AND LICENSE - -Copyright 1999, 2000, 2001, 2002, 2003 by Russ Allbery <rra@stanford.edu>. - -This program is free software; you may redistribute it and/or modify it -under the same terms as Perl itself. - -=cut |