lib/Pod/InputObjects.pm Pod-Parser - define objects for input streams
lib/Pod/LaTeX.pm Convert POD data to LaTeX
lib/Pod/Man.pm Convert POD data to *roff
+lib/Pod/ParseLink.pm Perl an L<> formatting code in POD text
lib/Pod/Parser.pm Pod-Parser - define base class for parsing POD
lib/Pod/ParseUtils.pm Pod-Parser - pod utility functions
lib/Pod/Plainer.pm Pod migration utility module
#
sub clean_data($){
my( $dataref ) = @_;
- my $i;
- for( $i = 0; $i <= $#$dataref; $i++ ){
+ for my $i ( 0..$#{$dataref} ) {
${$dataref}[$i] =~ s/\s+\Z//;
# have a look for all-space lines
# put a title in the HTML file if one wasn't specified
if ($title eq '') {
TITLE_SEARCH: {
- for (my $i = 0; $i < @poddata; $i++) {
+ for my $i ( 0..$#poddata ) {
if ($poddata[$i] =~ /^=head1\s*NAME\b/m) {
for my $para ( @poddata[$i, $i+1] ) {
last TITLE_SEARCH
}
if (!$title and $podfile =~ /\.pod\z/) {
# probably a split pod so take first =head[12] as title
- for (my $i = 0; $i < @poddata; $i++) {
+ for my $i ( 0..$#poddata ) {
last if ($title) = $poddata[$i] =~ /^=head[12]\s*(.*)/;
}
warn "adopted '$title' as title for $podfile\n"
# Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 1.20 2001/07/19 22:51:11 eagle Exp $
+# $Id: Man.pm,v 1.26 2001/11/15 09:02:06 eagle Exp $
#
# Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
#
require 5.004;
use Carp qw(carp croak);
+use Pod::ParseLink qw(parselink);
use Pod::Parser ();
use strict;
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.20;
+$VERSION = 1.26;
##############################################################################
# uniformly for backslash for readability.
%ESCAPES = (
'amp' => '&', # ampersand
+ 'apos' => "'", # apostrophe
'lt' => '<', # left chevron, less-than
'gt' => '>', # right chevron, greater-than
'quot' => '"', # double quote
'Yacute' => "Y\\*'", # capital Y, acute accent
'yacute' => "y\\*'", # small y, acute accent
'yuml' => 'y\\*:', # small y, dieresis or umlaut mark
+
+ 'nbsp' => '\\ ', # non-breaking space
+ 'shy' => '', # soft (discretionary) hyphen
);
$$self{LQUOTE} =~ s/\"/\"\"/;
$$self{RQUOTE} =~ s/\"/\"\"/;
- $$self{INDENT} = 0; # Current indentation level.
- $$self{INDENTS} = []; # Stack of indentations.
- $$self{INDEX} = []; # Index keys waiting to be printed.
- $$self{ITEMS} = 0; # The number of consecutive =items.
+ $$self{INDENT} = 0; # Current indentation level.
+ $$self{INDENTS} = []; # Stack of indentations.
+ $$self{INDEX} = []; # Index keys waiting to be printed.
+ $$self{ITEMS} = 0; # The number of consecutive =items.
+ $$self{NEWINDENT} = 0; # Whether we've seen =over without =item.
$self->SUPER::initialize;
}
$name = $self->input_file;
$section = 3 if (!$$self{section} && $name =~ /\.pm\z/i);
$name =~ s/\.p(od|[lm])\z//i;
- if ($section =~ /^1/) {
+ if ($section !~ /^3/) {
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. Also handle a
- # leading lib/ since that's what ExtUtils::MakeMaker creates.
- for ($name) {
- s%//+%/%g;
- if ( s%^.*?/lib/[^/]*perl[^/]*/%%si
- or s%^.*?/[^/]*perl[^/]*/(?:lib/)?%%si) {
- s%^site(_perl)?/%%s; # site and site_perl
- s%^(.*-$^O|$^O-.*)/%%so; # arch
- s%^\d+\.\d+%%s; # version
+ # Assume that we're dealing with a module. We want to figure out
+ # the full module name from the path to the file, but we don't
+ # want to include too much of the path into the module name. Lose
+ # everything up to the first of:
+ #
+ # */lib/*perl*/ standard or site_perl module
+ # */*perl*/lib/ from -Dprefix=/opt/perl
+ # */*perl*/ random module hierarchy
+ #
+ # which works. Also strip off a leading site or site_perl
+ # component, any OS-specific component, and any version number
+ # component, and strip off an initial component of "lib" or
+ # "blib/lib" since that's what ExtUtils::MakeMaker creates.
+ # splitdir requires at least File::Spec 0.8.
+ require File::Spec;
+ my ($volume, $dirs, $file) = File::Spec->splitpath ($name);
+ my @dirs = File::Spec->splitdir ($dirs);
+ my $cut = 0;
+ my $i;
+ for ($i = 0; $i < scalar @dirs; $i++) {
+ if ($dirs[$i] eq 'lib' && $dirs[$i + 1] =~ /perl/) {
+ $cut = $i + 2;
+ last;
+ } elsif ($dirs[$i] =~ /perl/) {
+ $cut = $i + 1;
+ $cut++ if $dirs[$i + 1] eq 'lib';
+ last;
}
- s%^lib/%%;
- s%/%::%g;
}
+ if ($cut > 0) {
+ splice (@dirs, 0, $cut);
+ shift @dirs if ($dirs[0] =~ /^site(_perl)?$/);
+ shift @dirs if ($dirs[0] =~ /^[\d.]+$/);
+ shift @dirs if ($dirs[0] =~ /^(.*-$^O|$^O-.*)$/);
+ }
+ shift @dirs if $dirs[0] eq 'lib';
+ splice (@dirs, 0, 2) if ($dirs[0] eq 'blib' && $dirs[1] eq 'lib');
+
+ # Remove empty directories when building the module name; they
+ # occur too easily on Unix by doubling slashes.
+ $name = join ('::', (grep { $_ ? $_ : () } @dirs), $file);
}
}
$$self{date} = sprintf ('%4d-%02d-%02d', $year, $month, $day);
}
- # Now, print out the preamble and the title.
+ # Now, print out the preamble and the title. The meaning of the arguments
+ # to .TH unfortunately vary by system; some systems consider the fourth
+ # argument to be a "source" and others use it as a version number.
+ # Generally it's just presented as the left-side footer, though, so it
+ # doesn't matter too much if a particular system gives it another
+ # interpretation.
+ #
+ # The order of date and release used to be reversed in older versions of
+ # this module, but this order is correct for both Solaris and Linux.
local $_ = $PREAMBLE;
s/\@CFONT\@/$$self{fixed}/;
s/\@LQUOTE\@/$$self{LQUOTE}/;
s/\@RQUOTE\@/$$self{RQUOTE}/;
chomp $_;
+ my $pversion = $Pod::Parser::VERSION;
print { $self->output_handle } <<"----END OF HEADER----";
-.\\" Automatically generated by Pod::Man version $VERSION
-.\\" @{[ scalar localtime ]}
+.\\" Automatically generated by Pod::Man v$VERSION, Pod::Parser v$pversion
.\\"
.\\" Standard preamble:
.\\" ========================================================================
.\\" ========================================================================
.\\"
.IX Title "$name $section"
-.TH $name $section "$$self{release}" "$$self{date}" "$$self{center}"
+.TH $name $section "$$self{date}" "$$self{release}" "$$self{center}"
.UC
----END OF HEADER----
-#"# for cperl-mode
# Initialize a few per-file variables.
$$self{INDENT} = 0;
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.
+ # Parse the tree. collapse knows about references to scalars as well as
+ # scalars and does the right thing with them. Tidy up any trailing
+ # whitespace.
my $text = shift;
- $text =~ 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}xg;
- 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 .= ' ' if @items == 2 && $i == 2;
- $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.
$text = $self->parse ($text, @_);
$text =~ s/\n\s*$/\n/;
+
+ # Output the paragraph. We also have to handle =over without =item. If
+ # there's an =over without =item, NEWINDENT will be set, and we need to
+ # handle creation of the indent here. Set WEIRDINDENT so that it will be
+ # cleaned up on =back.
$self->makespace;
+ if ($$self{NEWINDENT}) {
+ $self->output (".RS $$self{INDENT}\n");
+ $$self{WEIRDINDENT} = 1;
+ $$self{NEWINDENT} = 0;
+ }
$self->output (protect $self->textmapfonts ($text));
$self->outindex;
$$self{NEEDSPACE} = 1;
my ($self, $seq) = @_;
my $command = $seq->cmd_name;
+ # We have to defer processing of the inside of an L<> formatting code. If
+ # this sequence is nested inside an L<> sequence, return the literal raw
+ # text of it.
+ my $parent = $seq->nested;
+ while (defined $parent) {
+ return $seq->raw_text if ($parent->cmd_name eq 'L');
+ $parent = $parent->nested;
+ }
+
# Zero-width characters.
if ($command eq 'Z') {
# Workaround to generate a blessable reference, needed by 5.005.
$literal++ if $command eq 'C';
local $_ = $self->collapse ($seq->parse_tree, $literal);
- # Handle E<> escapes.
+ # Handle E<> escapes. Numeric escapes that match one of the supported ISO
+ # 8859-1 characters don't work at present.
if ($command eq 'E') {
if (/^\d+$/) {
return bless \ chr ($_), 'Pod::Man::String';
# Handle links.
if ($command eq 'L') {
- # A bug in lvalue subs in 5.6 requires the temporary variable.
- my $tmp = $self->buildlink ($_);
- return bless \ "$tmp", 'Pod::Man::String';
+ my ($text, $type) = (parselink ($_))[1,4];
+ return '' unless $text;
+ my ($file, $line) = $seq->file_line;
+ $text = $self->parse ($text, $line);
+ $text = '<' . $text . '>' if $type eq 'url';
+ return bless \ "$text", 'Pod::Man::String';
}
# Whitespace protection replaces whitespace with "\ ".
my $self = shift;
local $_ = shift;
unless (/^[-+]?\d+\s+$/) { $_ = $$self{indent} }
- if (@{ $$self{INDENTS} } > 0) {
+ if (@{ $$self{INDENTS} } > 0 && !$$self{WEIRDINDENT}) {
$self->output (".RS $$self{INDENT}\n");
}
push (@{ $$self{INDENTS} }, $$self{INDENT});
$$self{INDENT} = ($_ + 0);
+ $$self{NEWINDENT} = 1;
}
# End a list. If we've closed an embedded indent, we've mangled the hanging
$$self{WEIRDINDENT} = 1;
}
$$self{NEEDSPACE} = 1;
+ $$self{NEWINDENT} = 0;
}
# An individual list item. Emit an index entry for anything that's
$index = $_;
$index =~ s/^\s*[-*+o.]?(?:\s+|\Z)//;
}
+ $_ = '*' unless $_;
s/^\*(\s|\Z)/\\\(bu$1/;
if ($$self{WEIRDINDENT}) {
$self->output (".RE\n");
$self->outindex ($index ? ('Item', $index) : ());
$$self{NEEDSPACE} = 0;
$$self{ITEMS}++;
+ $$self{NEWINDENT} = 0;
}
# Begin a block for a particular translator. Setting VERBATIM triggers
##############################################################################
-# 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+$//;
-
- # If the argument looks like a URL, return it verbatim. This only handles
- # URLs that use the server syntax.
- if (m%^[a-z]+://\S+$%) { return $_ }
-
- # 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 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 {
- if ($section !~ /^".*"$/) { $section = '"' . $section . '"' }
- $text .= 'the section on ' . $section;
- $text .= " in $manpage" if length $manpage;
- }
- $text;
-}
-
-
-##############################################################################
# Escaping and fontification
##############################################################################
if (ref $_) {
$$_;
} else {
- s/\\/\\e/g;
+ s/\\/\\e/g if $literal > 1;
s/-/\\-/g if $literal > 1;
s/__/_\\|_/g if $literal > 1;
$_;
# Ensure double underbars have a tiny space between them.
s/__/_\\|_/g;
+ # Leave hyphens only if they're part of regular words and there is only
+ # one dash at a time. Leave a dash after the first character as a regular
+ # non-breaking dash, but don't let it mark the rest of the word invalid
+ # for hyphenation.
+ s/-/\\-/g;
+ s{
+ ( (?:\G|^|\s) [a-zA-Z] ) ( \\- )?
+ ( (?: [a-zA-Z]+ \\-)+ )
+ ( [a-zA-Z]+ ) (?=\s|\Z)
+ \b
+ } {
+ my ($prefix, $hyphen, $main, $suffix) = ($1, $2, $3, $4);
+ $hyphen ||= '';
+ $main =~ s/\\-/-/g;
+ $prefix . $hyphen . $main . $suffix;
+ }egx;
+
+ # Translate -- into a real em dash if it's used like one.
+ s{ (\s) \\-\\- (\s) } { $1 . '\*(--' . $2 }egx;
+ s{ (\b[a-zA-Z]+) \\-\\- (\s|\Z|[a-zA-Z]+\b) } { $1 . '\*(--' . $2 }egx;
+
# Make all caps a little smaller. Be careful here, since we don't want to
# make @ARGV into small caps, nor do we want to fix the MIME in
# MIME-Version, since it looks weird with the full-height V.
s{
( ^ | [\s\(\"\'\`\[\{<>] )
- ( [A-Z] [A-Z] [/A-Z+:\d_\$&-]* )
- (?: (?= [\s>\}\]\(\)\'\".?!,;] | -- ) | $ )
+ ( [A-Z] [A-Z] (?: [/A-Z+:\d_\$&] | \\- )* )
+ (?= [\s>\}\]\(\)\'\".?!,;] | \\*\(-- | $ )
} { $1 . '\s-1' . $2 . '\s0' }egx;
# Italize functions in the form func().
# func(n) is a reference to a manual page. Make it \fIfunc\fR\|(n).
s{
( \b | \\s-1 )
- ( [A-Za-z_] (?:[-:.\w]|\\s-?[01])+ )
+ ( [A-Za-z_] (?:[.:\w]|\\-|\\s-?[01])+ )
(
\( \d [a-z]* \)
)
(?! \( )
} { $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;
__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.
+.\" 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 ! !
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<pod2man>, but it can also
-be used directly.
+using L<nroff(1)>, normally via L<man(1)>, or printing using L<troff(1)>.
+It is conventionally invoked using the driver script B<pod2man>, but it can
+also be used directly.
As a derived class from Pod::Parser, Pod::Man supports the same methods and
interfaces. See L<Pod::Parser> for all the details; briefly, one creates a
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
+func(), func(3), and simple variable references like $foo or @bar so you
don't have to use code escapes for them; complex expressions like
C<$fred{'stuff'}> will still need to be escaped, though. It also translates
dashes that aren't used as hyphens into en dashes, makes long dashes--like
this--into proper em dashes, fixes "paired quotes," makes C++ 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
+bit smaller in B<troff>, and escapes stuff that *roff treats as special so
that you don't have to.
The recognized options to new() are as follows. All options take a single
=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.
+Some systems may want CR instead. Only matters for B<troff> output.
=item fixedbold
Bold version of the fixed-width font. Defaults to CB. Only matters for
-troff(1) output.
+B<troff> output.
=item fixeditalic
Italic version of the fixed-width font (actually, something of a misnomer,
since most fixed-width fonts only have an oblique version, not an italic
-version). Defaults to CI. Only matters for troff(1) output.
+version). Defaults to CI. Only matters for B<troff> output.
=item fixedbolditalic
Bold italic (probably actually oblique) version of the fixed-width font.
Pod::Man doesn't assume you have this, and defaults to CB. Some systems
-(such as Solaris) have this font available as CX. Only matters for troff(1)
+(such as Solaris) have this font available as CX. Only matters for B<troff>
output.
+=item name
+
+Set the name of the manual page. Without this option, the manual name is
+set to the uppercased base name of the file being converted unless the
+manual section is 3, in which case the path is parsed to see if it is a Perl
+module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted into
+a name like C<Pod::Man>. This option, if given, overrides any automatic
+determination of the name.
+
=item quotes
Sets the quote marks used to surround CE<lt>> text. If the value is a
=item release
Set the centered footer. By default, this is the version of Perl you run
-Pod::Man under. Note that some system macro sets assume that the
+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.
(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).
+versions of B<nroff> and B<troff> don't either).
=item Invalid link %s
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.
+The handling of hyphens and em dashes is somewhat fragile, and one may get
+the wrong one under some circumstances. This should only matter for
+B<troff> output.
When and whether to use small caps is somewhat tricky, and Pod::Man doesn't
necessarily get it right.
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
+most B<troff> implementations, but GNU troff does as an extension. It would
be nice to support as an option for those who want to use it.
The preamble added to each output file is rather verbose, and most of it is
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 SEE ALSO
-L<Pod::Parser|Pod::Parser>, perlpod(1), pod2man(1), nroff(1), troff(1),
-man(1), man(7)
+L<Pod::Parser>, L<perlpod(1)>, L<pod2man(1)>, L<nroff(1)>, L<troff(1)>,
+L<man(1)>, L<man(7)>
Ossanna, Joseph F., and Brian W. Kernighan. "Troff User's Manual,"
Computing Science Technical Report No. 54, AT&T Bell Laboratories. This is
-the best documentation of standard 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 best documentation of standard B<nroff> and B<troff>. At the time of
+this writing, it's available at
+L<http://www.cs.bell-labs.com/cm/cs/cstr.html>.
-The man page documenting the man macro set may be man(5) instead of man(7)
-on your system. Also, please see pod2man(1) for extensive documentation on
-writing manual pages if you've not done it before and aren't familiar with
-the conventions.
+The man page documenting the man macro set may be L<man(5)> instead of
+L<man(7)> on your system. Also, please see L<pod2man(1)> for extensive
+documentation on writing manual pages if you've not done it before and
+aren't familiar with the conventions.
=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>.
+Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
+B<pod2man> by Tom Christiansen <tchrist@mox.perl.com>.
=head1 COPYRIGHT AND LICENSE
--- /dev/null
+# Pod::ParseLink -- Parse an L<> formatting code in POD text.
+# $Id: ParseLink.pm,v 1.1 2001/11/15 07:58:57 eagle Exp $
+#
+# Copyright 2001 by Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+#
+# This module implements parsing of the text of an L<> formatting code as
+# defined in perlpodspec. It should be suitable for any POD formatter. It
+# exports only one function, parselink(), which returns the five-item parse
+# defined in perlpodspec.
+#
+# Perl core hackers, please note that this module is also separately
+# maintained outside of the Perl core as part of the podlators. Please send
+# me any patches at the address above in addition to sending them to the
+# standard Perl mailing lists.
+
+##############################################################################
+# Modules and declarations
+##############################################################################
+
+package Pod::ParseLink;
+
+require 5.004;
+
+use strict;
+use vars qw(@EXPORT @ISA $VERSION);
+
+use Exporter;
+@ISA = qw(Exporter);
+@EXPORT = qw(parselink);
+
+# Don't use the CVS revision as the version, since this module is also in Perl
+# core and too many things could munge CVS magic revision strings. This
+# number should ideally be the same as the CVS revision in podlators, however.
+$VERSION = 1.01;
+
+
+##############################################################################
+# Implementation
+##############################################################################
+
+# Parse the name and section portion of a link into a name and section.
+sub _parse_section {
+ my ($link) = @_;
+ $link =~ s/^\s+//;
+ $link =~ s/\s+$//;
+
+ # If the whole link is enclosed in quotes, interpret it all as a section
+ # even if it contains a slash.
+ return (undef, $1) if (/^"\s*(.*?)\s*"$/);
+
+ # Split into page and section on slash, and then clean up quoting in the
+ # section. If there is no section and the name contains spaces, also
+ # guess that it's an old section link.
+ my ($page, $section) = split (/\s*\/\s*/, $link, 2);
+ $section =~ s/^"\s*(.*?)\s*"$/$1/;
+ if ($page =~ / / && !defined ($section)) {
+ $section = $page;
+ $page = undef;
+ } else {
+ $page = undef unless $page;
+ $section = undef unless $section;
+ }
+ return ($page, $section);
+}
+
+# Infer link text from the page and section.
+sub _infer_text {
+ my ($page, $section) = @_;
+ my $inferred;
+ if ($page && !$section) {
+ $inferred = $page;
+ } elsif (!$page && $section) {
+ $inferred = '"' . $section . '"';
+ } elsif ($page && $section) {
+ $inferred = '"' . $section . '" in ' . $page;
+ }
+ return $inferred;
+}
+
+# Given the contents of an L<> formatting code, parse it into the link text,
+# the possibly inferred link text, the name or URL, the section, and the type
+# of link (pod, man, or url).
+sub parselink {
+ my ($link) = @_;
+ $link =~ s/\s+/ /g;
+ if ($link =~ /\A\w+:[^:\s]\S*\Z/) {
+ return (undef, $link, $link, undef, 'url');
+ } else {
+ my $text;
+ if ($link =~ /\|/) {
+ ($text, $link) = split (/\|/, $link, 2);
+ }
+ my ($name, $section) = _parse_section ($link);
+ my $inferred = $text || _infer_text ($name, $section);
+ my $type = ($name =~ /\(\S*\)/) ? 'man' : 'pod';
+ return ($text, $inferred, $name, $section, $type);
+ }
+}
+
+
+##############################################################################
+# Module return value and documentation
+##############################################################################
+
+# Ensure we evaluate to true.
+1;
+__END__
+
+=head1 NAME
+
+Pod::ParseLink -- Parse an L<> formatting code in POD text
+
+=head1 SYNOPSIS
+
+ use Pod::ParseLink;
+ my ($text, $inferred, $name, $section, $type) = parselink ($link);
+
+=head1 DESCRIPTION
+
+This module only provides a single function, parselink(), which takes the
+text of an LE<lt>E<gt> formatting code and parses it. It returns the anchor
+text for the link (if any was given), the anchor text possibly inferred from
+the name and section, the name or URL, the section if any, and the type of
+link. The type will be one of 'url', 'pod', or 'man', indicating a URL, a
+link to a POD page, or a link to a Unix manual page.
+
+Parsing is implemented per L<perlpodspec>. For backward compatibility,
+links where there is no section and name contains spaces, or links where the
+entirety of the link (except for the anchor text if given) is enclosed in
+double-quotes are interpreted as links to a section (LE<lt>/sectionE<gt>).
+
+The inferred anchor text is implemented per L<perlpodspec>:
+
+ L<name> => L<name|name>
+ L</section> => L<"section"|/section>
+ L<name/section> => L<"section" in name|name/section>
+
+The name may contain embedded EE<lt>E<gt> and ZE<lt>E<gt> formatting codes,
+and the section, anchor text, and inferred anchor text may contain any
+formatting codes. Any double quotes around the name or section are removed
+as part of the parsing, as are any leading or trailing whitespace.
+
+No attempt is made to resolve formatting codes. The caller must be prepared
+to do that either before or after calling parselink(). (This is because
+interpretation of EE<lt>E<gt> formatting codes may vary by formatter.)
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2001 by Russ Allbery <rra@stanford.edu>.
+
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
# Pod::Text -- Convert POD data to formatted ASCII text.
-# $Id: Text.pm,v 2.13 2001/10/20 08:07:21 eagle Exp $
+# $Id: Text.pm,v 2.14 2001/11/15 08:03:18 eagle Exp $
#
# Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
#
use Carp qw(carp croak);
use Exporter ();
+use Pod::ParseLink qw(parselink);
use Pod::Select ();
use strict;
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 2.13;
+$VERSION = 2.14;
##############################################################################
# "divide" added by Tim Jenness.
%ESCAPES = (
'amp' => '&', # ampersand
+ 'apos' => "'", # apostrophe
'lt' => '<', # left chevron, less-than
'gt' => '>', # right chevron, greater-than
'quot' => '"', # double quote
"copy" => "\xA9", # Copyright symbol
"ordf" => "\xAA", # feminine ordinal indicator
"not" => "\xAC", # not sign
- "shy" => "\xAD", # soft hyphen
+ "shy" => '', # soft (discretionary) hyphen
"reg" => "\xAE", # registered trademark
"macr" => "\xAF", # macron, overline
"deg" => "\xB0", # degree sign
"iquest" => "\xBF", # inverted question mark
"times" => "\xD7", # multiplication sign
"divide" => "\xF7", # division sign
+
+ "nbsp" => "\x01", # non-breaking space
);
local $_ = shift;
my $line = shift;
- # Perform a little magic to collapse multiple L<> references. This is
- # here mostly for backwards-compatibility. 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;
-
- # Now actually interpolate and output the paragraph.
+ # Interpolate and output the paragraph.
$_ = $self->interpolate ($_, $line);
s/\s+$/\n/;
if (defined $$self{ITEM}) {
# Calls code, bold, italic, file, and link to handle those types of sequences,
# and handles S<>, E<>, X<>, and Z<> directly.
sub interior_sequence {
- my $self = shift;
- my $command = shift;
- local $_ = shift;
+ local $_;
+ my ($self, $command, $seq);
+ ($self, $command, $_, $seq) = @_;
+
+ # We have to defer processing of the inside of an L<> formatting code. If
+ # this sequence is nested inside an L<> sequence, return the literal raw
+ # text of it.
+ my $parent = $seq->nested;
+ while (defined $parent) {
+ return $seq->raw_text if ($parent->cmd_name eq 'L');
+ $parent = $parent->nested;
+ }
+
+ # Index entries are ignored in plain text.
return '' if ($command eq 'X' || $command eq 'Z');
# Expand escapes into the actual character now, warning if invalid.
# For S<>, compress all internal whitespace and then map spaces to \01.
# When we output the text, we'll map this back.
if ($command eq 'S') {
- s/\s{2,}/ /g;
+ s/\s+/ /g;
tr/ /\01/;
return $_;
}
elsif ($command eq 'C') { return $self->seq_c ($_) }
elsif ($command eq 'F') { return $self->seq_f ($_) }
elsif ($command eq 'I') { return $self->seq_i ($_) }
- elsif ($command eq 'L') { return $self->seq_l ($_) }
+ elsif ($command eq 'L') { return $self->seq_l ($_, $seq) }
else {
my $seq = shift;
my ($file, $line) = $seq->file_line;
return $$self{alt} ? "``$_''" : "$$self{LQUOTE}$_$$self{RQUOTE}";
}
-# The complicated one. Handle links. Since this is plain text, we can't
-# actually make any real links, so this is all to figure out what text we
-# print out.
+# Handle links. Since this is plain text, we can't actually make any real
+# links, so this is all to figure out what text we print out. Most of the
+# work is done by Pod::ParseLink.
sub seq_l {
- 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 (/^([^|]+)\|/) { return $1 }
-
- # Okay, leading and trailing whitespace isn't important; get rid of it.
- s/^\s+//;
- s/\s+$//;
-
- # If the argument looks like a URL, return it verbatim. This only handles
- # URLs that use the server syntax.
- if (m%^[a-z]+://\S+$%) { return $_ }
-
- # 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)>. The latter is an enhancement over the
- # original Pod::Text.
- my ($manpage, $section) = ('', $_);
- if (/^"\s*(.*?)\s*"$/) {
- $section = '"' . $1 . '"';
- } elsif (m/^[-:.\w]+(?:\(\S+\))?$/) {
- ($manpage, $section) = ($_, '');
- } elsif (m%/%) {
- ($manpage, $section) = split (/\s*\/\s*/, $_, 2);
- }
-
- # Now build the actual output text.
- my $text = '';
- if (!length $section) {
- $text = "the $manpage manpage" if length $manpage;
- } elsif ($section =~ /^[:\w]+(?:\(\))?/) {
- $text .= 'the ' . $section . ' entry';
- $text .= (length $manpage) ? " in the $manpage manpage"
- : " elsewhere in this document";
- } else {
- $section =~ s/^\"\s*//;
- $section =~ s/\s*\"$//;
- $text .= 'the section on "' . $section . '"';
- $text .= " in the $manpage manpage" if length $manpage;
- }
- $text;
+ my ($self, $link, $seq) = @_;
+ my ($text, $type) = (parselink ($link))[1,4];
+ my ($file, $line) = $seq->file_line;
+ $text = $self->interpolate ($text, $line);
+ $text = '<' . $text . '>' if $type eq 'url';
+ return $text || '';
}
As a derived class from Pod::Parser, Pod::Text supports the same methods and
interfaces. See L<Pod::Parser> for all the details; briefly, one creates a
-new parser with C<Pod::Text-E<gt>new()> and then calls either
+new parser with C<< Pod::Text->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
The original Pod::Text contained code to do formatting via termcap
sequences, although it wasn't turned on by default and it was problematic to
get it to work at all. This rewrite doesn't even try to do that, but a
-subclass of it does. Look for L<Pod::Text::Termcap|Pod::Text::Termcap>.
+subclass of it does. Look for L<Pod::Text::Termcap>.
=head1 SEE ALSO
-L<Pod::Parser|Pod::Parser>, L<Pod::Text::Termcap|Pod::Text::Termcap>,
-pod2text(1)
+L<Pod::Parser>, L<Pod::Text::Termcap>, L<pod2text(1)>
=head1 AUTHOR
-Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the
-original Pod::Text by Tom Christiansen E<lt>tchrist@mox.perl.comE<gt> and
-its conversion to Pod::Parser by Brad Appleton
-E<lt>bradapp@enteract.comE<gt>.
+Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
+Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to
+Pod::Parser by Brad Appleton <bradapp@enteract.com>.
=head1 COPYRIGHT AND LICENSE
# Pod::Text::Color -- Convert POD data to formatted color ASCII text
-# $Id: Color.pm,v 1.1 2001/10/20 08:08:39 eagle Exp $
+# $Id: Color.pm,v 1.2 2001/11/15 08:04:18 eagle Exp $
#
# Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>
#
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.01;
+$VERSION = 1.02;
##############################################################################
=head1 SEE ALSO
-L<Pod::Text|Pod::Text>, L<Pod::Parser|Pod::Parser>
+L<Pod::Text>, L<Pod::Parser>
=head1 AUTHOR
# Pod::Text::Overstrike -- Convert POD data to formatted overstrike text
-# $Id: Overstrike.pm,v 1.3 2001/10/20 08:11:29 eagle Exp $
+# $Id: Overstrike.pm,v 1.4 2001/11/15 08:04:18 eagle Exp $
#
# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
# (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.03;
+$VERSION = 1.04;
##############################################################################
=head1 SEE ALSO
-L<Pod::Text|Pod::Text>, L<Pod::Parser|Pod::Parser>
+L<Pod::Text>, L<Pod::Parser>
=head1 AUTHOR
# Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
-# $Id: Termcap.pm,v 1.2 2001/10/20 08:09:30 eagle Exp $
+# $Id: Termcap.pm,v 1.3 2001/11/15 08:04:18 eagle Exp $
#
# Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>
#
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.02;
+$VERSION = 1.03;
##############################################################################
=head1 SEE ALSO
-L<Pod::Text|Pod::Text>, L<Pod::Parser|Pod::Parser>
+L<Pod::Text>, L<Pod::Parser>
=head1 AUTHOR
print OUT <<'!NO!SUBS!';
# pod2man -- Convert POD data to formatted *roff input.
-# $Id: pod2man.PL,v 1.7 2001/10/20 08:24:15 eagle Exp $
+# $Id: pod2man.PL,v 1.8 2001/11/05 04:55:47 eagle Exp $
#
# Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
#
Getopt::Long::config ('bundling_override');
GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s',
'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
- 'fixedbolditalic=s', 'official|o', 'quotes|q=s', 'lax|l',
- 'help|h', 'verbose|v') or exit 1;
+ 'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s',
+ 'lax|l', 'help|h', 'verbose|v') or exit 1;
pod2usage (0) if $options{help};
# Official sets --center, but don't override things explicitly set.
pod2man [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>]
-[B<--quotes>=I<quotes>] [B<--verbose>] [I<input> [I<output>] ...]
+[B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
+[B<--lax>] [B<--quotes>=I<quotes>] [B<--verbose>]
+[I<input> [I<output>] ...]
pod2man B<--help>
Don't complain when required sections are missing. Not currently used, as
POD checking functionality is not yet implemented in Pod::Man.
+=item B<-n> I<name>, B<--name>=I<name>
+
+Set the name of the manual page to I<name>. Without this option, the manual
+name is set to the uppercased base name of the file being converted unless
+the manual section is 3, in which case the path is parsed to see if it is a
+Perl module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted
+into a name like C<Pod::Man>. This option, if given, overrides any
+automatic determination of the name.
+
+Note that this option is probably not useful when converting multiple POD
+files at once. The convention for Unix man pages for commands is for the
+man page title to be in all-uppercase even if the command isn't.
+
=item B<-o>, B<--official>
Set the default header to indicate that this page is part of the standard
Try out *LOTS* of different ways of specifying references:
- Reference the the section entry in the manpage manpage
+ Reference the "section" in manpage
- Reference the the section entry in the manpage manpage
+ Reference the "section" in manpage
- Reference the the section entry in the manpage manpage
+ Reference the "section" in manpage
- Reference the the section entry in the manpage manpage
+ Reference the "section" in manpage
- Reference the the section on "manpage/section"
+ Reference the "manpage/section"
- Reference the the section entry in the "manpage" manpage
+ Reference the "section" in "manpage"
- Reference the the section on "section" in the manpage manpage
+ Reference the "section" in manpage
- Reference the the section entry in the manpage manpage
+ Reference the "section" in manpage
- Reference the the section entry in the manpage manpage
+ Reference the "section" in manpage
Now try it using the new "|" stuff ...
specifed than standard input is read.
pod2usage invokes the pod2usage() function in the Pod::Usage module.
- Please see the pod2usage() entry in the Pod::Usage manpage.
+ Please see "pod2usage()" in Pod::Usage.
SEE ALSO
- the Pod::Usage manpage, the pod2text(1) manpage
+ Pod::Usage, pod2text(1)
AUTHOR
Brad Appleton <bradapp@enteract.com>
-man Print the manual page and exit.
-section *section-spec*
- Specify a section to include in the output. See the section on
- "SECTION SPECIFICATIONS" in the Pod::Parser manpage for the
- format to use for *section-spec*. This option may be given
- multiple times on the command line.
+ Specify a section to include in the output. See "SECTION
+ SPECIFICATIONS" in Pod::Parser for the format to use for
+ *section-spec*. This option may be given multiple times on the
+ command line.
*file* The pathname of a file from which to select sections of pod
documentation (defaults to standard input).
are given than all pod sections encountered are output.
podselect invokes the podselect() function exported by Pod::Select
- Please see the podselect() entry in the Pod::Select manpage for more
- details.
+ Please see "podselect()" in Pod::Select for more details.
SEE ALSO
- the Pod::Parser manpage and the Pod::Select manpage
+ Pod::Parser and Pod::Select
AUTHOR
Brad Appleton <bradapp@enteract.com>
https://perl5.git.perl.org / perl5.git / commitdiff