--- /dev/null
+# Pod::Man -- Convert POD data to formatted *roff input.
+# $Id: Man.pm,v 0.5 1999/09/25 19:49:49 eagle Exp $
+#
+# Copyright 1999 by Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the same terms as Perl itself.
+#
+# This module is intended to be a replacement for pod2man, and attempts to
+# match its output except for some specific circumstances where other
+# decisions seemed to produce better output. It uses Pod::Parser and is
+# designed to be very easy to subclass.
+
+############################################################################
+# Modules and declarations
+############################################################################
+
+package Pod::Man;
+
+require 5.004;
+
+use Carp qw(carp croak);
+use Pod::Parser ();
+
+use strict;
+use subs qw(makespace);
+use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
+
+@ISA = qw(Pod::Parser);
+
+($VERSION = (split (' ', q$Revision: 0.5 $ ))[1]) =~ s/\.(\d)$/.0$1/;
+
+
+############################################################################
+# 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@. $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 Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.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. | will give a
+.\" real vertical bar. \*(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-|\(bv\*(Tr
+.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` `
+. ds C' '
+'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.
+.bd B 3
+. \" 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----
+
+# 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
+ 'lt' => '<', # left chevron, less-than
+ 'gt' => '>', # right chevron, greater-than
+ 'quot' => '"', # double quote
+
+ '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
+);
+
+
+############################################################################
+# Static helper functions
+############################################################################
+
+# Protect leading quotes and periods against interpretation as commands.
+sub protect { local $_ = shift; s/^([.\'])/\\&$1/mg; $_ }
+
+# 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 `` and ''.
+sub switchquotes {
+ my $command = shift;
+ local $_ = shift;
+ my $extra = shift;
+ s/\\\*\([LR]\"/\"/g;
+ if (/\"/) {
+ s/\"/\"\"/g;
+ my $troff = $_;
+ $troff =~ s/\"\"([^\"]*)\"\"/\`\`$1\'\'/g;
+ s/\"/\"\"/g if $extra;
+ $troff =~ s/\"/\"\"/g if $extra;
+ $_ = qq("$_") . ($extra ? " $extra" : '');
+ $troff = qq("$troff") . ($extra ? " $extra" : '');
+ return ".if n $command $_\n.el $command $troff\n";
+ } else {
+ $_ = qq("$_") . ($extra ? " $extra" : '');
+ return "$command $_\n";
+ }
+}
+
+# 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 "roff font should be 1 or 2 chars, 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.
+ if (!defined $$self{release}) {
+ my ($version, $patch) = ($] =~ /^(.{5})(\d{2})?/);
+ $$self{release} = "perl $version";
+ $$self{release} .= ", patch $patch" if $patch;
+ }
+
+ # Double quotes in things that will be quoted.
+ for (qw/center date release/) { $$self{$_} =~ s/\"/\"\"/g }
+
+ $$self{INDENT} = 0; # Current indentation level.
+ $$self{INDENTS} = []; # Stack of indentations.
+ $$self{INDEX} = []; # Index keys waiting to be printed.
+
+ $self->SUPER::initialize;
+}
+
+# For each document we process, output the preamble first. Note that the
+# fixed width font is a global default; once we interpolate it into the
+# PREAMBLE, it ain't ever changing. Maybe fix this later.
+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$/i);
+ $name =~ s/\.p(od|[lm])$//i;
+ if ($section =~ /^1/) {
+ require File::Basename;
+ $name = uc File::Basename::basename ($name);
+ } else {
+ # Lose everything up to the first of
+ # */lib/*perl* standard or site_perl module
+ # */*perl*/lib from -D prefix=/opt/perl
+ # */*perl*/ random module hierarchy
+ # which works. Should be fixed to use File::Spec.
+ for ($name) {
+ s%//+%/%g;
+ if ( s%^.*?/lib/[^/]*perl[^/]*/%%i
+ or s%^.*?/[^/]*perl[^/]*/(?:lib/)?%%i) {
+ s%^site(_perl)?/%%; # site and site_perl
+ s%^(.*-$^O|$^O-.*)/%%o; # arch
+ s%^\d+\.\d+%%; # version
+ }
+ s%/%::%g;
+ }
+ }
+ }
+
+ # 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} = join ('-', $year, $month, $day);
+ }
+
+ # Now, print out the preamble and the title.
+ $PREAMBLE =~ s/\@CFONT\@/$$self{fixed}/;
+ chomp $PREAMBLE;
+ print { $self->output_handle } <<"----END OF HEADER----";
+.\\" Automatically generated by Pod::Man version $VERSION
+.\\" @{[ scalar localtime ]}
+.\\"
+.\\" Standard preamble:
+.\\" ======================================================================
+$PREAMBLE
+.\\" ======================================================================
+.\\"
+.IX Title "$name $section"
+.TH $name $section "$$self{release}" "$$self{date}" "$$self{center}"
+.UC
+----END OF HEADER----
+#"# for cperl-mode
+
+ # Initialize a few per-file variables.
+ $$self{INDENT} = 0;
+ $$self{NEEDSPACE} = 0;
+}
+
+
+############################################################################
+# 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');
+ $command = 'cmd_' . $command;
+ $self->$command (@_);
+}
+
+# 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/^(\s*\S)/'\&' . $1/gme;
+ $self->makespace if $$self{NEEDSPACE};
+ $self->output (".Vb $lines\n$_.Ve\n");
+ $$self{NEEDSPACE} = 0;
+}
+
+# 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};
+
+ # Perform a little magic to collapse multiple L<> references. We'll
+ # just rewrite the whole thing into actual text at this part, bypassing
+ # the whole internal sequence parsing thing.
+ s{
+ (L< # A link of the form L</something>.
+ /
+ (
+ [:\w]+ # The item has to be a simple word...
+ (\(\))? # ...or simple function.
+ )
+ >
+ (
+ ,?\s+(and\s+)? # Allow lots of them, conjuncted.
+ L<
+ /
+ ( [:\w]+ ( \(\) )? )
+ >
+ )+
+ )
+ } {
+ local $_ = $1;
+ s{ L< / ([^>]+ ) } {$1}g;
+ my @items = split /(?:,?\s+(?:and\s+)?)/;
+ my $string = "the ";
+ my $i;
+ for ($i = 0; $i < @items; $i++) {
+ $string .= $items[$i];
+ $string .= ", " if @items > 2 && $i != $#items;
+ $string .= " and " if ($i == $#items - 1);
+ }
+ $string .= " entries elsewhere in this document";
+ $string;
+ }gex;
+
+ # Parse the tree and output it. collapse knows about references to
+ # scalars as well as scalars and does the right thing with them.
+ local $_ = $self->parse (@_);
+ s/\n\s*$/\n/;
+ $self->makespace if $$self{NEEDSPACE};
+ $self->output (protect $self->mapfonts ($_));
+ $self->outindex;
+ $$self{NEEDSPACE} = 1;
+}
+
+# Called for an interior sequence. 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 so that other interior sequences above us
+# know that the text has already been processed.
+sub sequence {
+ my ($self, $seq) = @_;
+ my $command = $seq->cmd_name;
+
+ # Zero-width characters.
+ if ($command eq 'Z') { return bless \ '\&', 'Pod::Man::String' }
+
+ # C<>, L<>, X<>, and E<> don't apply guesswork to their contents.
+ local $_ = $self->collapse ($seq->parse_tree, $command =~ /^[CELX]$/);
+
+ # Handle E<> escapes.
+ if ($command eq 'E') {
+ if (exists $ESCAPES{$_}) {
+ return bless \ "$ESCAPES{$_}", 'Pod::Man::String';
+ } else {
+ carp "Unknown escape E<$1>";
+ return bless \ "E<$_>", 'Pod::Man::String';
+ }
+ }
+
+ # For all the other sequences, empty content produces no output.
+ return '' if $_ eq '';
+
+ # Handle formatting sequences.
+ if ($command eq 'B') {
+ return bless \ ('\f(BS' . $_ . '\f(BE'), 'Pod::Man::String';
+ } elsif ($command eq 'F') {
+ return bless \ ('\f(IS' . $_ . '\f(IE'), 'Pod::Man::String';
+ } elsif ($command eq 'I') {
+ return bless \ ('\f(IS' . $_ . '\f(IE'), 'Pod::Man::String';
+ } elsif ($command eq 'C') {
+ s/-/\\-/g;
+ s/__/_\\|_/g;
+ return bless \ ('\f(FS\*(C`' . $_ . "\\*(C'\\f(FE"),
+ 'Pod::Man::String';
+ }
+
+ # Handle links.
+ if ($command eq 'L') {
+ return bless \ ($self->buildlink ($_)), 'Pod::Man::String';
+ }
+
+ # Whitespace protection replaces whitespace with "\ ".
+ if ($command eq 'S') {
+ s/\s+/\\ /g;
+ return bless \ "$_", 'Pod::Man::String';
+ }
+
+ # 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.
+ carp "Unknown sequence $command<$_>";
+}
+
+
+############################################################################
+# 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 any E<> sequences that would cause
+# them.
+sub cmd_head1 {
+ my $self = shift;
+ local $_ = $self->parse (@_);
+ s/\s+$//;
+ s/\\s-?\d//g;
+ $self->output (switchquotes ('.SH', $self->mapfonts ($_)));
+ $self->outindex (($_ eq 'NAME') ? () : ('Header', $_));
+ $$self{NEEDSPACE} = 0;
+}
+
+# Second level heading.
+sub cmd_head2 {
+ my $self = shift;
+ local $_ = $self->parse (@_);
+ s/\s+$//;
+ $self->output (switchquotes ('.Sh', $self->mapfonts ($_)));
+ $self->outindex ('Subsection', $_);
+ $$self{NEEDSPACE} = 0;
+}
+
+# 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{INDENTS} } > 0) {
+ $self->output (".RS $$self{INDENT}\n");
+ }
+ push (@{ $$self{INDENTS} }, $$self{INDENT});
+ $$self{INDENT} = ($_ + 0);
+}
+
+# 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} };
+ unless (defined $$self{INDENT}) {
+ carp "Unmatched =back";
+ $$self{INDENT} = 0;
+ }
+ if ($$self{WEIRDINDENT}) {
+ $self->output (".RE\n");
+ $$self{WEIRDINDENT} = 0;
+ }
+ if (@{ $$self{INDENTS} } > 0) {
+ $self->output (".RE\n");
+ $self->output (".RS $$self{INDENT}\n");
+ $$self{WEIRDINDENT} = 1;
+ }
+ $$self{NEEDSPACE} = 1;
+}
+
+# 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).
+sub cmd_item {
+ my $self = shift;
+ local $_ = $self->parse (@_);
+ s/\s+$//;
+ my $index;
+ if (/\w/ && !/^\w[.\)]\s*$/) {
+ $index = $_;
+ $index =~ s/^\s*[-*+o.]?\s*//;
+ }
+ s/^\*(\s|\Z)/\\\(bu$1/;
+ if ($$self{WEIRDINDENT}) {
+ $self->output (".RE\n");
+ $$self{WEIRDINDENT} = 0;
+ }
+ $_ = $self->mapfonts ($_);
+ $self->output (switchquotes ('.Ip', $_, $$self{INDENT}));
+ $self->outindex ($index ? ('Item', $index) : ());
+ $$self{NEEDSPACE} = 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;
+ my $line = shift;
+ return unless s/^(?:man|roff)\b[ \t]*\n?//;
+ $self->output ($_);
+}
+
+
+############################################################################
+# Link handling
+############################################################################
+
+# Handle links. We can't actually make real hyperlinks, so this is all to
+# figure out what text and formatting we print out.
+sub buildlink {
+ my $self = shift;
+ local $_ = shift;
+
+ # Smash whitespace in case we were split across multiple lines.
+ s/\s+/ /g;
+
+ # If we were given any explicit text, just output it.
+ if (m{ ^ ([^|]+) \| }x) { return $1 }
+
+ # Okay, leading and trailing whitespace isn't important.
+ s/^\s+//;
+ s/\s+$//;
+
+ # Default to using the whole content of the link entry as a section
+ # name. Note that L<manpage/> forces a manpage interpretation, as does
+ # something looking like L<manpage(section)>. Do the same thing to
+ # L<manpage(section)> as we would to manpage(section) without the L<>;
+ # see guesswork(). If we've added italics, don't add the "manpage"
+ # text; markup is sufficient.
+ my ($manpage, $section) = ('', $_);
+ if (/^"\s*(.*?)\s*"$/) {
+ $section = '"' . $1 . '"';
+ } elsif (m{ ^ [-:.\w]+ (?: \( \S+ \) )? $ }x) {
+ ($manpage, $section) = ($_, '');
+ $manpage =~ s/^([^\(]+)\(/'\f(IS' . $1 . '\f(IE\|('/e;
+ } elsif (m%/%) {
+ ($manpage, $section) = split (/\s*\/\s*/, $_, 2);
+ if ($manpage =~ /^[-:.\w]+(?:\(\S+\))?$/) {
+ $manpage =~ s/^([^\(]+)\(/'\f(IS' . $1 . '\f(IE\|'/e;
+ }
+ $section =~ s/^\"\s*//;
+ $section =~ s/\s*\"$//;
+ }
+ if ($manpage && $manpage !~ /\\f\(IS/) {
+ $manpage = "the $manpage manpage";
+ }
+
+ # Now build the actual output text.
+ my $text = '';
+ if (!length ($section) && !length ($manpage)) {
+ carp "Invalid link $_";
+ } elsif (!length ($section)) {
+ $text = $manpage;
+ } elsif ($section =~ /^[:\w]+(?:\(\))?/) {
+ $text .= 'the ' . $section . ' entry';
+ $text .= (length $manpage) ? " in $manpage"
+ : " elsewhere in this document";
+ } else {
+ $text .= 'the section on "' . $section . '"';
+ $text .= " in $manpage" if length $manpage;
+ }
+ $text;
+}
+
+
+############################################################################
+# 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. B<someI<thing> else> should map to \fBsome\f(BIthing\fB
+# else\fR. The old pod2man didn't get this right; the second \fB was \fR,
+# so nested sequences didn't work right. 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.
+sub mapfonts {
+ 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
+############################################################################
+
+# 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 and a flag saying whether or not to treat it as literal
+# text (not call guesswork on it), 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.
+# Assumes that everything in the parse tree is either a scalar or a
+# reference to a scalar.
+sub collapse {
+ my ($self, $ptree, $literal) = @_;
+ if ($literal) {
+ return join ('', map {
+ if (ref $_) {
+ $$_;
+ } else {
+ s/\\/\\e/g;
+ $_;
+ }
+ } $ptree->children);
+ } else {
+ return join ('', map {
+ ref ($_) ? $$_ : $self->guesswork ($_)
+ } $ptree->children);
+ }
+}
+
+# Takes a text block to perform guesswork on; this is guaranteed not to
+# contain any interior sequences. 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;
+
+ # 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' . $3 }egx;
+
+ # Turn PI into a pretty pi.
+ s{ (?: \\s-1 | \b ) PI (?: \\s0 | \b ) } {\\*\(PI}gx;
+
+ # Italize functions in the form func().
+ s{
+ \b
+ (
+ [:\w]+ (?:\\s-1)? \(\)
+ )
+ } { '\f(IS' . $1 . '\f(IE' }egx;
+
+ # func(n) is a reference to a manual page. Make it \fIfunc\fR\|(n).
+ s{
+ \b
+ (\w[-:.\w]+ (?:\\s-1)?)
+ (
+ \( [^\)] \)
+ )
+ } { '\f(IS' . $1 . '\f(IE\|' . $2 }egx;
+
+ # Convert simple Perl variable references to a fixed-width font.
+ s{
+ ( \s+ )
+ ( [\$\@%] [\w:]+ )
+ (?! \( )
+ } { $1 . '\f(FS' . $2 . '\f(FE'}egx;
+
+ # Translate -- into a real em dash if it's used like one and fix up
+ # dashes, but keep hyphens hyphens.
+ s{ (\G|^|.) (-+) (\b|.) } {
+ my ($pre, $dash, $post) = ($1, $2, $3);
+ if (length ($dash) == 1) {
+ ($pre =~ /[a-zA-Z]/) ? "$pre-$post" : "$pre\\-$post";
+ } elsif (length ($dash) == 2
+ && ((!$pre && !$post)
+ || ($pre =~ /\w/ && !$post)
+ || ($pre eq ' ' && $post eq ' ')
+ || ($pre eq '=' && $post ne '=')
+ || ($pre ne '=' && $post eq '='))) {
+ "$pre\\*(--$post";
+ } else {
+ $pre . ('\-' x length $dash) . $post;
+ }
+ }egxs;
+
+ # 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.
+ $_;
+}
+
+
+############################################################################
+# Output formatting
+############################################################################
+
+# Make vertical whitespace.
+sub makespace {
+ my $self = shift;
+ $self->output ($$self{INDENT} > 0 ? ".Sp\n" : ".PP\n");
+}
+
+# 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) {
+ my $output = '.IX Xref "'
+ . join (' ', map { s/\"/\"\"/; $_ } @entries)
+ . '"' . "\n";
+ }
+ if ($section) {
+ $index =~ s/\"/\"\"/;
+ $index =~ s/\\-/-/g;
+ $index =~ s/\\(?:s-?\d|.\(..|.)//g;
+ $output .= ".IX $section " . '"' . $index . '"' . "\n";
+ }
+ $self->output ($output);
+}
+
+# Output text to the output device.
+sub output { print { $_[0]->output_handle } $_[1] }
+
+__END__
+
+.\" These are some extra bits of roff that I don't want to lose track of
+.\" but that have been removed from the preamble to make it a bit shorter
+.\" since they're not currently being used. They're accents and special
+.\" characters we don't currently have escapes for.
+.if n \{\
+. ds ? ?
+. ds ! !
+. ds q
+.\}
+.if t \{\
+. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+. 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'
+.\}
+.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+.ds oe o\h'-(\w'o'u*4/10)'e
+.ds Oe O\h'-(\w'O'u*4/10)'E
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds v \h'-1'\o'\(aa\(ga'
+. ds _ \h'-1'^
+. ds . \h'-1'.
+. ds 3 3
+. ds oe oe
+. ds Oe OE
+.\}
+
+############################################################################
+# Documentation
+############################################################################
+
+=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 nroff(1), normally via man(1), or printing using troff(1). It is
+conventionally invoked using the driver script B<pod2roff>, 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-E<gt>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(n), 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++ and PI look
+right, puts a little space between double underbars, makes ALLCAPS a teeny
+bit smaller in troff(1), 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 troff(1) output.
+
+=item fixedbold
+
+Bold version of the fixed-width font. Defaults to CB. Only matters for
+troff(1) 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 troff(1) 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 troff(1)
+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 nroff(1) and troff(1) don't either).
+
+=item Invalid link %s
+
+(W) The POD source contained a C<LE<lt>E<gt>> sequence that Pod::Man was
+unable to parse. You should never see this error message; it probably
+indicates a bug in Pod::Man.
+
+=item 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 Unknown sequence %s
+
+(W) The POD source contained a non-standard interior sequence (something of
+the form C<XE<lt>E<gt>>) that Pod::Man didn't know about. It was ignored.
+
+=item Unmatched =back
+
+(W) Pod::Man encountered a C<=back> command that didn't correspond to an
+C<=over> command.
+
+=back
+
+=head1 BUGS
+
+The lint-like features and strict POD format checking done by B<pod2man> are
+not yet implemented and should be, along with the corresponding C<lax>
+option.
+
+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.
+
+The handling of hyphens, en dashes, and em dashes is somewhat fragile, and
+one may get the wrong one under some circumstances. This should only matter
+for troff(1) output.
+
+When and whether to use small caps is somewhat tricky, and Pod::Man doesn't
+necessarily get it right.
+
+Pod::Man doesn't handle font names longer than two characters. Neither do
+most troff(1) 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.
+
+Some of the automagic applied to file names assumes Unix directory
+separators.
+
+Pod::Man is excessively slow.
+
+=head1 NOTES
+
+The intention is for this module and its driver script to eventually replace
+B<pod2man> in Perl core.
+
+=head1 SEE ALSO
+
+L<Pod::Parser|Pod::Parser>, perlpod(1), pod2roff(1), nroff(1), troff(1),
+man(1), 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 nroff(1) and troff(1). At the time of
+this writing, it's available at http://www.cs.bell-labs.com/cm/cs/cstr.html.
+
+The man page documenting the man macro set may be man(5) instead of man(7)
+on your system. Also, please see pod2roff(1) for extensive documentation on
+writing manual pages if you've not done it before and aren't familiar with
+the conventions.
+
+=head1 AUTHOR
+
+Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the
+original B<pod2man> by Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>.
+
+=cut
# Table of supported E<> escapes
############################################################################
-# This table is taken near verbatim from Pod::Text in Pod::Parser,
+# This table is taken near verbatim from Pod::PlainText in Pod::Parser,
# which got it near verbatim from the original Pod::Text. It is therefore
# credited to Tom Christiansen, and I'm glad I didn't have to write it. :)
%ESCAPES = (
# Pod::Text::Color -- Convert POD data to formatted color ASCII text
-# $Id: Color.pm,v 0.1 1999/06/13 02:41:06 eagle Exp $
+# $Id: Color.pm,v 0.5 1999/09/20 10:15:16 eagle Exp $
#
# Copyright 1999 by Russ Allbery <rra@stanford.edu>
#
@ISA = qw(Pod::Text);
# Use the CVS revision of this file as its version number.
-($VERSION = (split (' ', q$Revision: 0.1 $ ))[1]) =~ s/\.(\d)$/.0$1/;
+($VERSION = (split (' ', q$Revision: 0.5 $ ))[1]) =~ s/\.(\d)$/.0$1/;
############################################################################
=head1 DESCRIPTION
-Pod::Text::Color is a simple subclass of Pod::Text that highlights
-output text using ANSI color escape sequences. Apart from the color, it in
-all ways functions like Pod::Text. See L<Pod::Text> for details
-and available options.
+Pod::Text::Color is a simple subclass of Pod::Text that highlights output
+text using ANSI color escape sequences. Apart from the color, it in all
+ways functions like Pod::Text. See L<Pod::Text> for details and available
+options.
+
+Term::ANSIColor is used to get colors and therefore must be installed to use
+this module.
+
+=head1 BUGS
+
+This is just a basic proof of concept. It should be seriously expanded to
+support configurable coloration via options passed to the constructor, and
+B<pod2text> should be taught about those.
=head1 SEE ALSO
# Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
-# $Id: Termcap.pm,v 0.1 1999/06/13 02:41:06 eagle Exp $
+# $Id: Termcap.pm,v 0.4 1999/09/20 10:17:45 eagle Exp $
#
# Copyright 1999 by Russ Allbery <rra@stanford.edu>
#
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.
#
-# This is a simple subclass of Pod::Text that overrides a few key
-# methods to output the right termcap escape sequences for formatted text
-# on the current terminal type.
+# This is a simple subclass of Pod::Text that overrides a few key methods to
+# output the right termcap escape sequences for formatted text on the
+# current terminal type.
############################################################################
# Modules and declarations
use Pod::Text ();
use POSIX ();
use Term::Cap;
+
use strict;
use vars qw(@ISA $VERSION);
@ISA = qw(Pod::Text);
# Use the CVS revision of this file as its version number.
-($VERSION = (split (' ', q$Revision: 0.1 $ ))[1]) =~ s/\.(\d)$/.0$1/;
+($VERSION = (split (' ', q$Revision: 0.4 $ ))[1]) =~ s/\.(\d)$/.0$1/;
############################################################################
=head1 DESCRIPTION
-Pod::Text::Termcap is a simple subclass of Pod::Text that highlights
-output text using the correct termcap escape sequences for the current
-terminal. Apart from the format codes, it in all ways functions like
-Pod::Text. See L<Pod::Text> for details and available options.
+Pod::Text::Termcap is a simple subclass of Pod::Text that highlights output
+text using the correct termcap escape sequences for the current terminal.
+Apart from the format codes, it in all ways functions like Pod::Text. See
+L<Pod::Text> for details and available options.
=head1 SEE ALSO
# have to mention them as if they were shell variables, not
# %Config entries. Thus you write
# $startperl
-# $man3ext
# to ensure Configure will look for $Config{startperl}.
# This forces PL files to create target in same directory as PL file.
print OUT <<"!GROK!THIS!";
$Config{startperl}
eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
- if \$running_under_some_shell;
-
-\$DEF_PM_SECTION = '$Config{man3ext}' || '3';
+ if \$running_under_some_shell;
!GROK!THIS!
# In the following, perl variables are not expanded during extraction.
print OUT <<'!NO!SUBS!';
-=head1 NAME
-
-pod2man - translate embedded Perl pod directives into man pages
-
-=head1 SYNOPSIS
-
-B<pod2man>
-[ B<--section=>I<manext> ]
-[ B<--release=>I<relpatch> ]
-[ B<--center=>I<string> ]
-[ B<--date=>I<string> ]
-[ B<--fixed=>I<font> ]
-[ B<--official> ]
-[ B<--lax> ]
-I<inputfile>
-
-=head1 DESCRIPTION
-
-B<pod2man> converts its input file containing embedded pod directives (see
-L<perlpod>) into nroff source suitable for viewing with nroff(1) or
-troff(1) using the man(7) macro set.
-
-Besides the obvious pod conversions, B<pod2man> also takes care of
-func(), func(n), 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. Other nagging
-little roffish things that it catches include translating the minus in
-something like foo-bar, making a long dash--like this--into a real em
-dash, fixing up "paired quotes", putting a little space after the
-parens in something like func(), making C++ and PI look right, making
-double underbars have a little tiny space between them, making ALLCAPS
-a teeny bit smaller in troff(1), and escaping backslashes so you don't
-have to.
-
-=head1 OPTIONS
-
-=over 8
-
-=item center
-
-Set the centered header to a specific string. The default is
-"User Contributed Perl Documentation", unless the C<--official> flag is
-given, in which case the default is "Perl Programmers Reference Guide".
-
-=item date
-
-Set the left-hand footer string to this value. By default,
-the modification date of the input file will be used.
-
-=item fixed
-
-The fixed font to use for code refs. Defaults to CW.
-
-=item official
-
-Set the default header to indicate that this page is of
-the standard release in case C<--center> is not given.
-
-=item release
-
-Set the centered footer. By default, this is the current
-perl release.
-
-=item section
-
-Set the section for the C<.TH> macro. The standard conventions on
-sections are 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. This works
-best if you put your Perl man pages in a separate tree, like
-F</usr/local/perl/man/>. By default, section 1 will be used
-unless the file ends in F<.pm> in which case section 3 will be selected.
-
-=item lax
-
-Don't complain when required sections aren't present.
-
-=back
-
-=head1 Anatomy of a Proper Man Page
-
-For those not sure of the proper layout of a man page, here's
-an example of the skeleton of a proper man page. Head of the
-major headers should be setout as a C<=head1> directive, and
-are historically written in the rather startling ALL UPPER CASE
-format, although this is not mandatory.
-Minor headers may be included using C<=head2>, and are
-typically in mixed case.
-
-=over 10
-
-=item NAME
+# pod2man -- Convert POD data to formatted *roff input.
+#
+# Copyright 1999 by Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the same terms as Perl itself.
+#
+# The driver script for Pod::Man. This script is expected to eventually
+# replace pod2man in the standard Perl distribution.
+
+require 5.004;
+
+use Getopt::Long qw(GetOptions);
+use Pod::Man ();
+use Pod::Usage qw(pod2usage);
+
+use strict;
+use vars;
+
+# Parse our options, trying to retain backwards compatibility with pod2man
+# but allowing short forms as well. --lax is currently ignored.
+my %options;
+Getopt::Long::config ('bundling');
+GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s',
+ 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
+ 'fixedbolditalic=s', 'official|o', 'lax|l', 'help|h') or exit 1;
+pod2usage (0) if $options{help};
+
+# Official sets --center, but don't override things explicitly set.
+if ($options{official} && !defined $options{center}) {
+ $options{center} = 'Perl Programmers Reference Guide';
+}
-Mandatory section; should be a comma-separated list of programs or
-functions documented by this podpage, such as:
+# Initialize and run the formatter.
+my $parser = Pod::Man->new (\%options);
+$parser->parse_from_file (@ARGV);
- foo, bar - programs to do something
+__END__
-=item SYNOPSIS
+=head1 NAME
-A short usage summary for programs and functions, which
-may someday be deemed mandatory.
+pod2man - Convert POD data to formatted *roff input
-=item DESCRIPTION
+=head1 SYNOPSIS
-Long drawn out discussion of the program. It's a good idea to break this
-up into subsections using the C<=head2> directives, like
+pod2txt [B<--section>=I<manext>] [B<--release>=I<version>]
+[B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>]
+[B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
+[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] [I<input>
+[I<output>]]
- =head2 A Sample Subection
+pod2txt B<--help>
- =head2 Yet Another Sample Subection
+=head1 DESCRIPTION
-=item OPTIONS
+B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
+from POD source. The resulting *roff code is suitable for display on a
+terminal using nroff(1), normally via man(1), or printing using troff(1).
+
+I<input> is the file to read for POD source (the POD can be embedded in
+code). If I<input> isn't given, it defaults to STDIN. I<output>, if given,
+is the file to which to write the formatted output. If I<output> isn't
+given, the formatted output is written to STDOUT.
+
+B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be
+used to set the headers and footers to use; if not given, Pod::Man will
+assume various defaults. See below or L<Pod::Man> for details.
+
+B<pod2man> assumes that your *roff formatters have a fixed-width font named
+CW. If yours is called something else (like CR), use B<--fixed> 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, and therefore pod2man also
+takes care of formatting func(), func(n), 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," and
+takes care of several other troff-specific tweaks. See L<Pod::Man> for
+complete information.
-Some people make this separate from the description.
+=head1 OPTIONS
-=item RETURN VALUE
+=over 4
-What the program or function returns if successful.
+=item B<-c> I<string>, B<--center>=I<string>
-=item ERRORS
+Sets the centered page header to I<string>. The default is "User
+Contributed Perl Documentation", but also see B<--official> below.
-Exceptions, return codes, exit stati, and errno settings.
+=item B<-d> I<string>, B<--date>=I<string>
-=item EXAMPLES
+Set the left-hand footer string to this value. By default, the modification
+date of the input file will be used, or the current date if input comes from
+STDIN.
-Give some example uses of the program.
+=item B<--fixed>=I<font>
-=item ENVIRONMENT
+The fixed-width font to use for vertabim text and code. Defaults to CW.
+Some systems may want CR instead. Only matters for troff(1) output.
-Envariables this program might care about.
+=item B<--fixedbold>=I<font>
-=item FILES
+Bold version of the fixed-width font. Defaults to CB. Only matters for
+troff(1) output.
-All files used by the program. You should probably use the FE<lt>E<gt>
-for these.
+=item B<--fixeditalic>=I<font>
-=item SEE ALSO
+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 troff(1) output.
-Other man pages to check out, like man(1), man(7), makewhatis(8), or catman(8).
+=item B<--fixedbolditalic>=I<font>
-=item NOTES
+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 troff(1)
+output.
-Miscellaneous commentary.
+=item B<-h>, B<--help>
-=item CAVEATS
+Print out usage information.
-Things to take special care with; sometimes called WARNINGS.
+=item B<-l>, B<--lax>
-=item DIAGNOSTICS
+Don't complain when required sections are missing. Not currently used, as
+POD checking functionality is not yet implemented in Pod::Man.
-All possible messages the program can print out--and
-what they mean.
+=item B<-o>, B<--official>
-=item BUGS
+Set the default header to indicate that this page is part of the standard
+Perl release, if B<--center> is not also given.
-Things that are broken or just don't work quite right.
+=item B<-r>, B<--release>
-=item RESTRICTIONS
+Set the centered footer. By default, this is the version of Perl you run
+B<pod2man> 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 B<--release> to
+the last modified date and B<--date> to the version number.
-Bugs you don't plan to fix :-)
+=item B<-s>, B<--section>
-=item AUTHOR
+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.
-Who wrote it (or AUTHORS if multiple).
+By default, section 1 will be used unless the file ends in .pm in which case
+section 3 will be selected.
-=item HISTORY
+=back
-Programs derived from other sources sometimes have this, or
-you might keep a modification log here.
+=head1 DIAGNOSTICS
-=back
+If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Parser> for
+information about what those errors might mean.
=head1 EXAMPLES
pod2man program > program.1
- pod2man some_module.pm > /usr/perl/man/man3/some_module.3
+ pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
pod2man --section=7 note.pod > note.7
-=head1 DIAGNOSTICS
+If you would like to print out a lot of man page continuously, you probably
+want to set the C and D registers to set contiguous page numbering and
+even/odd paging, at least on some versions of man(7).
-The following diagnostics are generated by B<pod2man>. Items
-marked "(W)" are non-fatal, whereas the "(F)" errors will cause
-B<pod2man> to immediately exit with a non-zero status.
+ troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
-=over 4
+To get index entries on stderr, turn on the F register, as in:
-=item bad option in paragraph %d of %s: ``%s'' should be [%s]<%s>
+ troff -man -rF1 perl.1
-(W) If you start include an option, you should set it off
-as bold, italic, or code.
+The indexing merely outputs messages via C<.tm> for each major page,
+section, subsection, item, and any C<XE<lt>E<gt>> directives. See
+L<Pod::Man> for more details.
-=item can't open %s: %s
+=head1 BUGS
-(F) The input file wasn't available for the given reason.
+Lots of this documentation is duplicated from L<Pod::Man>.
-=item Improper man page - no dash in NAME header in paragraph %d of %s
+POD checking and the corresponding B<--lax> option don't work yet.
-(W) The NAME header did not have an isolated dash in it. This is
-considered important.
+=head1 NOTES
-=item Invalid man page - no NAME line in %s
+For those not sure of the proper layout of a man page, here are some notes
+on writing a proper man page.
-(F) You did not include a NAME header, which is essential.
+The name of the program being documented is conventionally written in bold
+(using BE<lt>E<gt>) wherever it occurs, as are all program options.
+Arguments should be written in italics (IE<lt>E<gt>). Functions are
+traditionally written in italics; if you write a function as function(),
+Pod::Man will take care of this for you. Literal code or commands should
+be in CE<lt>E<gt>. References to other man pages should be in the form
+C<manpage(section)>, and Pod::Man will automatically format those
+appropriately. As an exception, it's traditional not to use this form when
+referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead.
-=item roff font should be 1 or 2 chars, not `%s' (F)
+References to other programs or functions are normally in the form of man
+page references so that cross-referencing tools can provide the user with
+links and the like. It's possible to overdo this, though, so be careful not
+to clutter your documentation with too much markup.
-(F) The font specified with the C<--fixed> option was not
-a one- or two-digit roff font.
+The major headers should be set out using a C<=head1> directive, and are
+historically written in the rather startling ALL UPPER CASE format, although
+this is not mandatory. Minor headers may be included using C<=head2>, and
+are typically in mixed case.
-=item %s is missing required section: %s
+The standard sections of a manual page are:
-(W) Required sections include NAME, DESCRIPTION, and if you're
-using a section starting with a 3, also a SYNOPSIS. Actually,
-not having a NAME is a fatal.
+=over 4
-=item Unknown escape: %s in %s
+=item NAME
-(W) An unknown HTML entity (probably for an 8-bit character) was given via
-a C<EE<lt>E<gt>> directive. Besides amp, lt, gt, and quot, recognized
-entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave, agrave,
-Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute, eacute,
-Ecirc, ecirc, Egrave, egrave, ETH, eth, Euml, euml, Iacute, iacute, Icirc,
-icirc, Igrave, igrave, Iuml, iuml, Ntilde, ntilde, Oacute, oacute, Ocirc,
-ocirc, Ograve, ograve, Oslash, oslash, Otilde, otilde, Ouml, ouml, szlig,
-THORN, thorn, Uacute, uacute, Ucirc, ucirc, Ugrave, ugrave, Uuml, uuml,
-Yacute, yacute, and yuml.
+Mandatory section; should be a comma-separated list of programs or functions
+documented by this podpage, such as:
-=item Unmatched =back
+ foo, bar - programs to do something
-(W) You have a C<=back> without a corresponding C<=over>.
+Manual page indexers are often extremely picky about the format of this
+section, so don't put anything in it except this line. A single dash, and
+only a single dash, should separate the list of programs or functions from
+the description. Functions should not be qualified with C<()> or the like.
+The description should ideally fit on a single line, even if a man program
+replaces the dash with a few tabs.
-=item Unrecognized pod directive: %s
+=item SYNOPSIS
-(W) You specified a pod directive that isn't in the known list of
-C<=head1>, C<=head2>, C<=item>, C<=over>, C<=back>, or C<=cut>.
+A short usage summary for programs and functions. This section is mandatory
+for section 3 pages.
+=item DESCRIPTION
-=back
+Extended description and discussion of the program or functions, or the body
+of the documentation for man pages that document something else. If
+particularly long, it's a good idea to break this up into subsections
+C<=head2> directives like:
-=head1 NOTES
+ =head2 Normal Usage
-If you would like to print out a lot of man page continuously, you
-probably want to set the C and D registers to set contiguous page
-numbering and even/odd paging, at least on some versions of man(7).
-Settting the F register will get you some additional experimental
-indexing:
+ =head2 Advanced Features
- troff -man -rC1 -rD1 -rF1 perl.1 perldata.1 perlsyn.1 ...
+ =head2 Writing Configuration Files
-The indexing merely outputs messages via C<.tm> for each
-major page, section, subsection, item, and any C<XE<lt>E<gt>>
-directives.
+or whatever is appropriate for your documentation.
+=item OPTIONS
-=head1 RESTRICTIONS
+Detailed description of each of the command-line options taken by the
+program. This should be separate from the description for the use of things
+like L<Pod::Usage|Pod::Usage>. This is normally presented as a list, with
+each option as a separate C<=item>. The specific option string should be
+enclosed in BE<lt>E<gt>. Any values that the option takes should be
+enclosed in IE<lt>E<gt>. For example, the section for the option
+B<--section>=I<manext> would be introduced with:
-None at this time.
+ =item B<--section>=I<manext>
-=head1 BUGS
+Synonymous options (like both the short and long forms) are separated by a
+comma and a space on the same C<=item> line, or optionally listed as their
+own item with a reference to the canonical name. For example, since
+B<--section> can also be written as B<-s>, the above would be:
-The =over and =back directives don't really work right. They
-take absolute positions instead of offsets, don't nest well, and
-making people count is suboptimal in any event.
+ =item B<-s> I<manext>, B<--section>=I<manext>
-=head1 AUTHORS
+(Writing the short option first is arguably easier to read, since the long
+option is long enough to draw the eye to it anyway and the short option can
+otherwise get lost in visual noise.)
-Original prototype by Larry Wall, but so massively hacked over by
-Tom Christiansen such that Larry probably doesn't recognize it anymore.
+=item RETURN VALUE
-=cut
+What the program or function returns, if successful. This section can be
+omitted for programs whose precise exit codes aren't important, provided
+they return 0 on success as is standard. It should always be present for
+functions.
-$/ = "";
-$cutting = 1;
-@Indices = ();
-
-# We try first to get the version number from a local binary, in case we're
-# running an installed version of Perl to produce documentation from an
-# uninstalled newer version's pod files.
-if ($^O ne 'plan9' and $^O ne 'dos' and $^O ne 'os2' and $^O ne 'MSWin32') {
- my $perl = (-x './perl' && -f './perl' ) ?
- './perl' :
- ((-x '../perl' && -f '../perl') ?
- '../perl' :
- '');
- ($version,$patch) = `$perl -e 'print $]'` =~ /^(\d\.\d{3})(\d{2})?/ if $perl;
-}
-# No luck; we'll just go with the running Perl's version
-($version,$patch) = $] =~ /^(.{5})(\d{2})?/ unless $version;
-$DEF_RELEASE = "perl $version";
-$DEF_RELEASE .= ", patch $patch" if $patch;
-
-
-sub makedate {
- my $secs = shift;
- my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime($secs);
- my $mname = (qw{Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec})[$mon];
- $year += 1900;
- return "$mday/$mname/$year";
-}
+=item ERRORS
-use Getopt::Long;
-
-$DEF_SECTION = 1;
-$DEF_CENTER = "User Contributed Perl Documentation";
-$STD_CENTER = "Perl Programmers Reference Guide";
-$DEF_FIXED = 'CW';
-$DEF_LAX = 0;
-
-sub usage {
- warn "$0: @_\n" if @_;
- die <<EOF;
-usage: $0 [options] podpage
-Options are:
- --section=manext (default "$DEF_SECTION")
- --release=relpatch (default "$DEF_RELEASE")
- --center=string (default "$DEF_CENTER")
- --date=string (default "$DEF_DATE")
- --fixed=font (default "$DEF_FIXED")
- --official (default NOT)
- --lax (default NOT)
-EOF
-}
+Exceptions, error return codes, exit stati, and errno settings. Typically
+used for function documentation; program documentation uses DIAGNOSTICS
+instead. The general rule of thumb is that errors printed to STDOUT or
+STDERR and intended for the end user are documented in DIAGNOSTICS while
+errors passed internal to the calling program and intended for other
+programmers are documented in ERRORS. When documenting a function that sets
+errno, a full list of the possible errno values should be given here.
-$uok = GetOptions( qw(
- section=s
- release=s
- center=s
- date=s
- fixed=s
- official
- lax
- help));
+=item DIAGNOSTICS
-$DEF_DATE = makedate((stat($ARGV[0]))[9] || time());
+All possible messages the program can print out--and what they mean. You
+may wish to follow the same documentation style as the Perl documentation;
+see perldiag(1) for more details (and look at the POD source as well).
-usage("Usage error!") unless $uok;
-usage() if $opt_help;
-usage("Need one and only one podpage argument") unless @ARGV == 1;
+If applicable, please include details on what the user should do to correct
+the error; documenting an error as indicating "the input buffer is too
+small" without telling the user how to increase the size of the input buffer
+(or at least telling them that it isn't possible) aren't very useful.
-$section = $opt_section || ($ARGV[0] =~ /\.pm$/
- ? $DEF_PM_SECTION : $DEF_SECTION);
-$RP = $opt_release || $DEF_RELEASE;
-$center = $opt_center || ($opt_official ? $STD_CENTER : $DEF_CENTER);
-$lax = $opt_lax || $DEF_LAX;
+=item EXAMPLES
-$CFont = $opt_fixed || $DEF_FIXED;
+Give some example uses of the program or function. Don't skimp; users often
+find this the most useful part of the documentation. The examples are
+generally given as verbatim paragraphs.
-if (length($CFont) == 2) {
- $CFont_embed = "\\f($CFont";
-}
-elsif (length($CFont) == 1) {
- $CFont_embed = "\\f$CFont";
-}
-else {
- die "roff font should be 1 or 2 chars, not `$CFont_embed'";
-}
+Don't just present an example without explaining what it does. Adding a
+short paragraph saying what the example will do can increase the value of
+the example immensely.
-$date = $opt_date || $DEF_DATE;
+=item ENVIRONMENT
-for (qw{NAME DESCRIPTION}) {
-# for (qw{NAME DESCRIPTION AUTHOR}) {
- $wanna_see{$_}++;
-}
-$wanna_see{SYNOPSIS}++ if $section =~ /^3/;
+Environment variables that the program cares about, normally presented as a
+list using C<=over>, C<=item>, and C<=back>. For example:
+ =over 6
-$name = @ARGV ? $ARGV[0] : "<STDIN>";
-$Filename = $name;
-if ($section =~ /^1/) {
- require File::Basename;
- $name = uc File::Basename::basename($name);
-}
-$name =~ s/\.(pod|p[lm])$//i;
-
-# Lose everything up to the first of
-# */lib/*perl* standard or site_perl module
-# */*perl*/lib from -D prefix=/opt/perl
-# */*perl*/ random module hierarchy
-# which works.
-$name =~ s-//+-/-g;
-if ($name =~ s-^.*?/lib/[^/]*perl[^/]*/--i
- or $name =~ s-^.*?/[^/]*perl[^/]*/lib/--i
- or $name =~ s-^.*?/[^/]*perl[^/]*/--i) {
- # Lose ^site(_perl)?/.
- $name =~ s-^site(_perl)?/--;
- # Lose ^arch/. (XXX should we use Config? Just for archname?)
- $name =~ s~^(.*-$^O|$^O-.*)/~~o;
- # Lose ^version/.
- $name =~ s-^\d+\.\d+/--;
-}
+ =item HOME
-# Translate Getopt/Long to Getopt::Long, etc.
-$name =~ s(/)(::)g;
-
-if ($name ne 'something') {
- FCHECK: {
- open(F, "< $ARGV[0]") || die "can't open $ARGV[0]: $!";
- while (<F>) {
- next unless /^=\b/;
- if (/^=head1\s+NAME\s*$/) { # an /m would forgive mistakes
- $_ = <F>;
- unless (/\s*-+\s+/) {
- $oops++;
- warn "$0: Improper man page - no dash in NAME header in paragraph $. of $ARGV[0]\n"
- } else {
- my @n = split /\s+-+\s+/;
- if (@n != 2) {
- $oops++;
- warn "$0: Improper man page - malformed NAME header in paragraph $. of $ARGV[0]\n"
- }
- else {
- %namedesc = @n;
- }
- }
- last FCHECK;
- }
- next if /^=cut\b/; # DB_File and Net::Ping have =cut before NAME
- next if /^=pod\b/; # It is OK to have =pod before NAME
- die "$0: Invalid man page - 1st pod line is not NAME in $ARGV[0]\n" unless $lax;
- }
- die "$0: Invalid man page - no documentation in $ARGV[0]\n" unless $lax;
- }
- close F;
-}
+ Used to determine the user's home directory. F<.foorc> in this
+ directory is read for configuration details, if it exists.
-print <<"END";
-.rn '' }`
-''' \$RCSfile\$\$Revision\$\$Date\$
-'''
-''' \$Log\$
-'''
-.de Sh
-.br
-.if t .Sp
-.ne 5
-.PP
-\\fB\\\\\$1\\fR
-.PP
-..
-.de Sp
-.if t .sp .5v
-.if n .sp
-..
-.de Ip
-.br
-.ie \\\\n(.\$>=3 .ne \\\\\$3
-.el .ne 3
-.IP "\\\\\$1" \\\\\$2
-..
-.de Vb
-.ft $CFont
-.nf
-.ne \\\\\$1
-..
-.de Ve
-.ft R
-
-.fi
-..
-'''
-'''
-''' Set up \\*(-- to give an unbreakable dash;
-''' string Tr holds user defined translation string.
-''' Bell System Logo is used as a dummy character.
-'''
-.tr \\(*W-|\\(bv\\*(Tr
-.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" ""
-''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of
-''' \\*(L" and \\*(R", except that they are used on ".xx" lines,
-''' such as .IP and .SH, which do another additional levels of
-''' double-quote interpretation
-.ds M" """
-.ds S" """
-.ds N" """""
-.ds T" """""
-.ds L' '
-.ds R' '
-.ds M' '
-.ds S' '
-.ds N' '
-.ds T' '
-'br\\}
-.el\\{\\
-.ds -- \\(em\\|
-.tr \\*(Tr
-.ds L" ``
-.ds R" ''
-.ds M" ``
-.ds S" ''
-.ds N" ``
-.ds T" ''
-.ds L' `
-.ds R' '
-.ds M' `
-.ds S' '
-.ds N' `
-.ds T' '
-.ds PI \\(*p
-'br\\}
-END
-
-print <<'END';
-.\" If the F register is turned on, we'll generate
-.\" index entries out stderr for the following things:
-.\" TH Title
-.\" SH Header
-.\" Sh Subsection
-.\" Ip Item
-.\" X<> Xref (embedded
-.\" Of course, you have to process the output yourself
-.\" in some meaninful fashion.
-.if \nF \{
-.de IX
-.tm Index:\\$1\t\\n%\t"\\$2"
-..
-.nr % 0
-.rr F
-.\}
-END
-
-print <<"END";
-.TH $name $section "$date" "$RP" "$center"
-.UC
-END
-
-push(@Indices, qq{.IX Title "$name $section"});
-
-while (($name, $desc) = each %namedesc) {
- for ($name, $desc) { s/^\s+//; s/\s+$//; }
- push(@Indices, qq(.IX Name "$name - $desc"\n));
-}
+ =back
-print <<'END';
-.if n .hy 0
-.if n .na
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.de CQ \" put $1 in typewriter font
-END
-print ".ft $CFont\n";
-print <<'END';
-'if n "\c
-'if t \\&\\$1\c
-'if n \\&\\$1\c
-'if n \&"
-\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
-'.ft R
-..
-.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
-. \" AM - accent mark definitions
-.bd B 3
-. \" 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 ? ?
-. ds ! !
-. ds /
-. ds q
-.\}
-.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 ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
-. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-. 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'
-.\}
-. \" 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 v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
-.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
-.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
-.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
-.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
-.ds oe o\h'-(\w'o'u*4/10)'e
-.ds Oe O\h'-(\w'O'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 v \h'-1'\o'\(aa\(ga'
-. ds _ \h'-1'^
-. ds . \h'-1'.
-. ds 3 3
-. 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
-. ds oe oe
-. ds Oe OE
-.\}
-.rm #[ #] #H #V #F C
-END
-
-$indent = 0;
-
-$begun = "";
-
-# Unrolling [^-=A-Z>]|[A-Z](?!<)|[-=](?![A-Z]<)[\x00-\xFF] gives: // MRE pp 165.
-my $nonest = q{(?x) # Turn on /x mode.
- (?: # Group
- [^-=A-Z>]* # Anything that isn't a dash, equal sign or
- # closing hook isn't special. Eat as much as
- # we can.
- (?: # Group.
- (?: # Group.
- [-=] # We want to recognize -> and =>.
- (?![A-Z]<) # So, as long as it isn't followed by markup
- [\x00-\xFF] # anything may follow - and =
- |
- [A-Z] # Capitals are fine too,
- (?!<) # But not if they start markup.
- ) # End of special sequences.
- [^-=A-Z>]* # Followed by zero or more non-special chars.
- )* # And we can repeat this as often as we can.
- )}; # That's all folks.
-
-while (<>) {
- if ($cutting) {
- next unless /^=/;
- $cutting = 0;
- }
- if ($begun) {
- if (/^=end\s+$begun/) {
- $begun = "";
- }
- elsif ($begun =~ /^(roff|man)$/) {
- print STDOUT $_;
- }
- next;
- }
- chomp;
-
- # Translate verbatim paragraph
-
- if (/^\s/) {
- @lines = split(/\n/);
- for (@lines) {
- 1 while s
- {^( [^\t]* ) \t ( \t* ) }
- { $1 . ' ' x (8 - (length($1)%8) + 8 * (length($2))) }ex;
- s/\\/\\e/g;
- s/\A/\\&/s;
- }
- $lines = @lines;
- makespace() unless $verbatim++;
- print ".Vb $lines\n";
- print join("\n", @lines), "\n";
- print ".Ve\n";
- $needspace = 0;
- next;
- }
-
- $verbatim = 0;
-
- if (/^=for\s+(\S+)\s*/s) {
- if ($1 eq "man" or $1 eq "roff") {
- print STDOUT $',"\n\n";
- } else {
- # ignore unknown for
- }
- next;
- }
- elsif (/^=begin\s+(\S+)\s*/s) {
- $begun = $1;
- if ($1 eq "man" or $1 eq "roff") {
- print STDOUT $'."\n\n";
- }
- next;
- }
-
- # check for things that'll hosed our noremap scheme; affects $_
- init_noremap();
-
- if (!/^=item/) {
-
- # trofficate backslashes; must do it before what happens below
- s/\\/noremap('\\e')/ge;
-
- # protect leading periods and quotes against *roff
- # mistaking them for directives
- s/^(?:[A-Z]<)?[.']/\\&$&/gm;
-
- # first hide the escapes in case we need to
- # intuit something and get it wrong due to fmting
-
- 1 while s/([A-Z]<$nonest>)/noremap($1)/ge;
-
- # func() is a reference to a perl function
- s{
- \b
- (
- [:\w]+ \(\)
- )
- } {I<$1>}gx;
-
- # func(n) is a reference to a perl function or a man page
- s{
- ([:\w]+)
- (
- \( [^\051]+ \)
- )
- } {I<$1>\\|$2}gx;
-
- # convert simple variable references
- s/(\s+)([\$\@%&*][\w:]+)(?!\()/${1}C<$2>/g;
-
- if (m{ (
- [\-\w]+
- \(
- [^\051]*?
- [\@\$,]
- [^\051]*?
- \)
- )
- }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/)
- {
- warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [LCI]<$1>\n";
- $oops++;
- }
-
- while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) {
- warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [CB]<$1>\n";
- $oops++;
- }
-
- # put it back so we get the <> processed again;
- clear_noremap(0); # 0 means leave the E's
-
- } else {
- # trofficate backslashes
- s/\\/noremap('\\e')/ge;
-
- }
-
- # need to hide E<> first; they're processed in clear_noremap
- s/(E<[^<>]+>)/noremap($1)/ge;
-
-
- $maxnest = 10;
- while ($maxnest-- && /[A-Z]</) {
-
- # can't do C font here
- s/([BI])<($nonest)>/font($1) . $2 . font('R')/eg;
-
- # files and filelike refs in italics
- s/F<($nonest)>/I<$1>/g;
-
- # no break -- usually we want C<> for this
- s/S<($nonest)>/nobreak($1)/eg;
-
- # LREF: a la HREF L<show this text|man/section>
- s:L<([^|>]+)\|[^>]+>:$1:g;
-
- # LREF: a manpage(3f)
- s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g;
-
- # LREF: an =item on another manpage
- s{
- L<
- ([^/]+)
- /
- (
- [:\w]+
- (\(\))?
- )
- >
- } {the C<$2> entry in the I<$1> manpage}gx;
-
- # LREF: an =item on this manpage
- s{
- ((?:
- L<
- /
- (
- [:\w]+
- (\(\))?
- )
- >
- (,?\s+(and\s+)?)?
- )+)
- } { internal_lrefs($1) }gex;
-
- # LREF: a =head2 (head1?), maybe on a manpage, maybe right here
- # the "func" can disambiguate
- s{
- L<
- (?:
- ([a-zA-Z]\S+?) /
- )?
- "?(.*?)"?
- >
- }{
- do {
- $1 # if no $1, assume it means on this page.
- ? "the section on I<$2> in the I<$1> manpage"
- : "the section on I<$2>"
- }
- }gesx; # s in case it goes over multiple lines, so . matches \n
-
- s/Z<>/\\&/g;
-
- # comes last because not subject to reprocessing
- s/C<($nonest)>/noremap("${CFont_embed}${1}\\fR")/eg;
- }
-
- if (s/^=//) {
- $needspace = 0; # Assume this.
-
- s/\n/ /g;
-
- ($Cmd, $_) = split(' ', $_, 2);
-
- $dotlevel = 1;
- if ($Cmd eq 'head1') {
- $dotlevel = 1;
- }
- elsif ($Cmd eq 'head2') {
- $dotlevel = 1;
- }
- elsif ($Cmd eq 'item') {
- $dotlevel = 2;
- }
-
- if (defined $_) {
- &escapes($dotlevel);
- s/"/""/g;
- }
-
- clear_noremap(1);
-
- if ($Cmd eq 'cut') {
- $cutting = 1;
- }
- elsif ($Cmd eq 'head1') {
- s/\s+$//;
- delete $wanna_see{$_} if exists $wanna_see{$_};
- print qq{.SH "$_"\n};
- push(@Indices, qq{.IX Header "$_"\n});
- }
- elsif ($Cmd eq 'head2') {
- print qq{.Sh "$_"\n};
- push(@Indices, qq{.IX Subsection "$_"\n});
- }
- elsif ($Cmd eq 'over') {
- push(@indent,$indent);
- $indent += ($_ + 0) || 5;
- if ($#indent > 0) {
- print ".RS ", $indent[$#indent] - $indent[$#indent - 1], "\n";
- }
- }
- elsif ($Cmd eq 'back') {
- $indent = pop(@indent);
- warn "$0: Unmatched =back in paragraph $. of $ARGV\n" unless defined $indent;
- if ($#indent >= 0) {
- print ".RE\n";
- }
- $needspace = 1;
- }
- elsif ($Cmd eq 'item') {
- s/^\*( |$)/\\(bu$1/g;
- # if you know how to get ":s please do
- s/\\\*\(L"([^"]+?)\\\*\(R"/'$1'/g;
- s/\\\*\(L"([^"]+?)""/'$1'/g;
- s/[^"]""([^"]+?)""[^"]/'$1'/g;
- # here do something about the $" in perlvar?
- print STDOUT qq{.Ip "$_" $indent-$indent[$#indent]\n};
- push(@Indices, qq{.IX Item "$_"\n});
- }
- elsif ($Cmd eq 'pod') {
- # this is just a comment
- }
- else {
- warn "$0: Unrecognized pod directive in paragraph $. of $ARGV: $Cmd\n";
- }
- }
- else {
- if ($needspace) {
- &makespace;
- }
- &escapes(0);
- clear_noremap(1);
- print $_, "\n";
- $needspace = 1;
- }
-}
+Since environment variables are normally in all uppercase, no additional
+special formatting is generally needed; they're glaring enough as it is.
-print <<"END";
+=item FILES
-.rn }` ''
-END
+All files used by the program or function, normally presented as a list, and
+what it uses them for. File names should be enclosed in FE<lt>E<gt>. It's
+particularly important to document files that will be potentially modified.
-if (%wanna_see && !$lax) {
- @missing = keys %wanna_see;
- warn "$0: $Filename is missing required section"
- . (@missing > 1 && "s")
- . ": @missing\n";
- $oops++;
-}
+=item CAVEATS
-foreach (@Indices) { print "$_\n"; }
+Things to take special care with, sometimes called WARNINGS.
-exit;
-#exit ($oops != 0);
+=item BUGS
-#########################################################################
+Things that are broken or just don't work quite right.
-sub nobreak {
- my $string = shift;
- $string =~ s/ /\\ /g;
- $string;
-}
+=item RESTRICTIONS
-sub escapes {
- my $indot = shift;
-
- s/X<(.*?)>/mkindex($1)/ge;
-
- # translate the minus in foo-bar into foo\-bar for roff
- s/([^0-9a-z-])-([^-])/$1\\-$2/g;
-
- # make -- into the string version \*(-- (defined above)
- s/\b--\b/\\*(--/g;
- s/"--([^"])/"\\*(--$1/g; # should be a better way
- s/([^"])--"/$1\\*(--"/g;
-
- # fix up quotes; this is somewhat tricky
- my $dotmacroL = 'L';
- my $dotmacroR = 'R';
- if ( $indot == 1 ) {
- $dotmacroL = 'M';
- $dotmacroR = 'S';
- }
- elsif ( $indot >= 2 ) {
- $dotmacroL = 'N';
- $dotmacroR = 'T';
- }
- if (!/""/) {
- s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge;
- s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge;
- }
-
- #s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
- #s/(?:(?!")(?:.)--(?:"))|(?:(?:")--(?!")(?:.))/\\*(--/g;
-
-
- # make sure that func() keeps a bit a space tween the parens
- ### s/\b\(\)/\\|()/g;
- ### s/\b\(\)/(\\|)/g;
-
- # make C++ into \*C+, which is a squinched version (defined above)
- s/\bC\+\+/\\*(C+/g;
-
- # make double underbars have a little tiny space between them
- s/__/_\\|_/g;
-
- # PI goes to \*(PI (defined above)
- s/\bPI\b/noremap('\\*(PI')/ge;
-
- # make all caps a teeny bit smaller, but don't muck with embedded code literals
- my $hidCFont = font('C');
- if ($Cmd !~ /^head1/) { # SH already makes smaller
- # /g isn't enough; 1 while or we'll be off
-
-# 1 while s{
-# (?!$hidCFont)(..|^.|^)
-# \b
-# (
-# [A-Z][\/A-Z+:\-\d_$.]+
-# )
-# (s?)
-# \b
-# } {$1\\s-1$2\\s0}gmox;
-
- 1 while s{
- (?!$hidCFont)(..|^.|^)
- (
- \b[A-Z]{2,}[\/A-Z+:\-\d_\$]*\b
- )
- } {
- $1 . noremap( '\\s-1' . $2 . '\\s0' )
- }egmox;
-
- }
-}
+Bugs you don't plan to fix. :-)
-# make troff just be normal, but make small nroff get quoted
-# decided to just put the quotes in the text; sigh;
-sub ccvt {
- local($_,$prev) = @_;
- noremap(qq{.CQ "$_" \n\\&});
-}
+=item NOTES
-sub makespace {
- if ($indent) {
- print ".Sp\n";
- }
- else {
- print ".PP\n";
- }
-}
+Miscellaneous commentary.
-sub mkindex {
- my ($entry) = @_;
- my @entries = split m:\s*/\s*:, $entry;
- push @Indices, ".IX Xref " . join ' ', map {qq("$_")} @entries;
- return '';
-}
+=item SEE ALSO
-sub font {
- local($font) = shift;
- return '\\f' . noremap($font);
-}
+Other man pages to check out, like man(1), man(7), makewhatis(8), or
+catman(8). Normally a simple list of man pages separated by commas, or a
+paragraph giving the name of a reference work. Man page references, if they
+use the standard C<name(section)> form, don't have to be enclosed in
+LE<lt>E<gt>, but other things in this section probably should be when
+appropriate. You may need to use the C<LE<lt>...|...E<gt>> syntax to keep
+B<pod2man> and B<pod2text> from being too verbose; see perlpod(1).
-sub noremap {
- local($thing_to_hide) = shift;
- $thing_to_hide =~ tr/\000-\177/\200-\377/;
- return $thing_to_hide;
-}
+If the package has a web site, include a URL here.
-sub init_noremap {
- # escape high bit characters in input stream
- s/([\200-\377])/"E<".ord($1).">"/ge;
-}
+=item AUTHOR
-sub clear_noremap {
- my $ready_to_print = $_[0];
-
- tr/\200-\377/\000-\177/;
-
- # trofficate backslashes
- # s/(?!\\e)(?:..|^.|^)\\/\\e/g;
-
- # now for the E<>s, which have been hidden until now
- # otherwise the interative \w<> processing would have
- # been hosed by the E<gt>
- s {
- E<
- (
- ( \d + )
- | ( [A-Za-z]+ )
- )
- >
- } {
- do {
- defined $2
- ? chr($2)
- :
- exists $HTML_Escapes{$3}
- ? do { $HTML_Escapes{$3} }
- : do {
- warn "$0: Unknown escape in paragraph $. of $ARGV: ``$&''\n";
- "E<$1>";
- }
- }
- }egx if $ready_to_print;
-}
+Who wrote it (use AUTHORS for multiple people). Including your current
+e-mail address (or some e-mail address to which bug reports should be sent)
+so that users have a way of contacting you is a good idea. Remember that
+program documentation tends to roam the wild for far longer than you expect
+and pick an e-mail address that's likely to last if possible.
-sub internal_lrefs {
- local($_) = shift;
- local $trailing_and = s/and\s+$// ? "and " : "";
-
- s{L</([^>]+)>}{$1}g;
- my(@items) = split( /(?:,?\s+(?:and\s+)?)/ );
- my $retstr = "the ";
- my $i;
- for ($i = 0; $i <= $#items; $i++) {
- $retstr .= "C<$items[$i]>";
- $retstr .= ", " if @items > 2 && $i != $#items;
- $retstr .= " and " if $i+2 == @items;
- }
-
- $retstr .= " entr" . ( @items > 1 ? "ies" : "y" )
- . " elsewhere in this document";
- # terminal space to avoid words running together (pattern used
- # strips terminal spaces)
- $retstr .= " " if length $trailing_and;
- $retstr .= $trailing_and;
-
- return $retstr;
+=item HISTORY
-}
+Programs derived from other sources sometimes have this, or you might keep a
+modification log here.
-BEGIN {
-%HTML_Escapes = (
- 'amp' => '&', # ampersand
- 'lt' => '<', # left chevron, less-than
- 'gt' => '>', # right chevron, greater-than
- 'quot' => '"', # double quote
-
- "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
-);
-}
+=back
+
+In addition, some systems use CONFORMING TO to note conformance to relevant
+standards and MT-LEVEL to note safeness for use in threaded programs or
+signal handlers. These headings are primarily useful when documenting parts
+of a C library. Documentation of object-oriented libraries or modules may
+use CONSTRUCTORS and METHODS sections for detailed documentation of the
+parts of the library and save the DESCRIPTION section for an overview; other
+large modules may use FUNCTIONS for similar reasons. Some people use
+OVERVIEW to summarize the description if it's quite long. Sometimes there's
+an additional COPYRIGHT section at the bottom, for licensing terms.
+AVAILABILITY is sometimes added, giving the canonical download site for the
+software or a URL for updates.
+
+Section ordering varies, although NAME should I<always> be the first section
+(you'll break some man page systems otherwise), and NAME, SYNOPSIS,
+DESCRIPTION, and OPTIONS generally always occur first and in that order if
+present. In general, SEE ALSO, AUTHOR, and similar material should be left
+for last. Some systems also move WARNINGS and NOTES to last. The order
+given above should be reasonable for most purposes.
+
+Finally, as a general note, try not to use an excessive amount of markup.
+As documented here and in L<Pod::Man>, you can safely leave Perl variables,
+function names, man page references, and the like unadorned by markup and
+the POD translators will figure it out for you. This makes it much easier
+to later edit the documentation. Note that many existing translators
+(including this one currently) will do the wrong thing with e-mail addresses
+or URLs when wrapped in LE<lt>E<gt>, so don't do that.
+
+For additional information that may be more accurate for your specific
+system, see either man(5) or man(7) depending on your system manual section
+numbering conventions.
+
+=head1 SEE ALSO
+
+L<Pod::Man|Pod::Man>, L<Pod::Parser|Pod::Parser>, man(1), nroff(1),
+troff(1), man(7)
+
+The man page documenting the an macro set may be man(5) instead of man(7) on
+your system.
+
+=head1 AUTHOR
+
+Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the
+original B<pod2man> by Larry Wall and Tom Christiansen. Large portions of
+this documentation, particularly the sections on the anatomy of a proper man
+page, are taken from the B<pod2man> documentation by Tom.
+=cut
!NO!SUBS!
close OUT or die "Can't close $file: $!";
print OUT <<"!GROK!THIS!";
$Config{startperl}
eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
- if \$running_under_some_shell;
+ if \$running_under_some_shell;
!GROK!THIS!
# In the following, perl variables are not expanded during extraction.
print OUT <<'!NO!SUBS!';
-$ID = q$Id: pod2text,v 0.1 1999/06/13 02:42:18 eagle Exp $;
-
# pod2text -- Convert POD data to formatted ASCII text.
-# Copyright 1999 by Russ Allbery <rra@stanford.edu>
+#
+# Copyright 1999 by Russ Allbery <rra@stanford.edu>
#
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.
#
-# The driver script for Pod::Text, Pod::Text::Termcap, and
-# Pod::Text::Color, invoked by perldoc -t among other things.
+# The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
+# invoked by perldoc -t among other things.
require 5.004;
}
}
-# Parse our options. Use the same names as Pod::Text for simplicity,
-# and default to sentence boundaries turned off for compatibility.
+# Parse our options. Use the same names as Pod::Text for simplicity, and
+# default to sentence boundaries turned off for compatibility.
my %options;
$options{termcap} = -t STDOUT;
$options{sentence} = 0;
my $formatter = 'Pod::Text';
if ($options{color}) {
$formatter = 'Pod::Text::Color';
+ eval { require Term::ANSIColor };
+ if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
require Pod::Text::Color;
} elsif ($options{termcap}) {
$formatter = 'Pod::Text::Termcap';
=head1 DESCRIPTION
-B<pod2text> is a front-end for Pod::Text and its subclasses. It uses
-them to generate formatted ASCII text from POD source. It can optionally
-use either termcap sequences or ANSI color escape sequences to format the
-text.
+B<pod2text> is a front-end for Pod::Text and its subclasses. It uses them
+to generate formatted ASCII text from POD source. It can optionally use
+either termcap sequences or ANSI color escape sequences to format the text.
I<input> is the file to read for POD source (the POD can be embedded in
code). If I<input> isn't given, it defaults to STDIN. I<output>, if given,
is the file to which to write the formatted output. If I<output> isn't
given, the formatted output is written to STDOUT.
+B<pod2text> defaults to trying to use Pod::Text::Termcap if STDOUT is a tty.
+To explicitly say not to attempt termcap escape sequences, use
+B<--notermcap>.
+
=head1 OPTIONS
=over 4
Set the number of spaces to indent regular text, and the default indentation
for C<=over> blocks. Defaults to 4 spaces if this option isn't given.
+=item B<-h>, B<--help>
+
+Print out usage information and exit.
+
=item B<-l>, B<--loose>
Print a blank line after a C<=head1> heading. Normally, no blank line is
-printed after C<=head1>, although one is still printed after C<=head2>.
-This is the default because it's the expected formatting for manual pages;
-if you're formatting arbitrary text documents, using this option is
-recommended.
+printed after C<=head1>, although one is still printed after C<=head2>,
+because this is the expected formatting for manual pages; if you're
+formatting arbitrary text documents, using this option is recommended.
=item B<-s>, B<--sentence>
-Assume each sentence ends in two spaces and try to preserve that spacing.
+Assume each sentence ends with two spaces and try to preserve that spacing.
Without this option, all consecutive whitespace in non-verbatim paragraphs
is compressed into a single space.
formatting the output. Output will be wrapped at two columns less than the
width of your terminal device. Using this option requires that your system
have a termcap file somewhere where Term::Cap can find it. With this
-option, the output of B<pod2text> will contain terminal control sequences for
-your current terminal type.
+option, the output of B<pod2text> will contain terminal control sequences
+for your current terminal type.
=item B<-w>, B<--width=>I<width>, B<->I<width>
=back
+=head1 DIAGNOSTICS
+
+If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for
+information about what those errors might mean. Internally, it can also
+produce the following diagnostics:
+
+=over 4
+
+=item -c (--color) requires Term::ANSIColor be installed
+
+(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
+loaded.
+
+=item Unknown option: %s
+
+(F) An unknown command line option was given.
+
+=back
+
+In addition, other L<Getopt::Long|Getopt::Long> error messages may result
+from invalid command-line options.
+
=head1 ENVIRONMENT
=over 4
=back
-=head1 DIAGNOSTICS
-
-If B<pod2text> fails with POD errors, see L<Pod::Text> and
-L<Pod::Parser> for information about what those errors might mean.
-
=head1 SEE ALSO
L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>,
projects / p5sagit/p5-mst-13.2.git / commitdiff