lib/Pod/t/pod2html-lib.pl pod2html testing library
lib/Pod/t/pod2latex.t See if Pod::LaTeX works
lib/Pod/t/pod-parser.t podlators test
+lib/Pod/t/pod-spelling.t podlators test
+lib/Pod/t/pod.t podlators test
lib/Pod/t/Select.t See if Pod::Select works
lib/Pod/t/termcap.t podlators test
lib/Pod/t/text-options.t podlators test
'podlators' =>
{
'MAINTAINER' => 'rra',
- 'FILES' => q[lib/Pod/{Man,ParseLink,Text,Text/{Color,Overstrike,Termcap}}.pm pod/pod2man.PL pod/pod2text.PL lib/Pod/t/{basic.*,{man,parselink,text*}.t}],
+ 'FILES' => q[lib/Pod/{Man,ParseLink,Text,Text/{Color,Overstrike,Termcap}}.pm pod/pod2man.PL pod/pod2text.PL lib/Pod/t/{basic.*,{color,filehandle,man*,parselink,pod-parser,pod-spelling,pod,termcap,text*}.t}],
'CPAN' => 1,
},
@ISA = qw(Pod::Simple);
-# 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.17';
+$VERSION = '2.18';
# Set the debugging level. If someone has inserted a debug function into this
# class already, use that. Otherwise, use any Pod::Simple debug function
my $class = shift;
my $self = $class->SUPER::new;
- # Tell Pod::Simple to handle S<> by automatically inserting .
+ # Tell Pod::Simple not to handle S<> by automatically inserting .
+ # Note that this messes up Unicode output by embedding explicit ISO 8859-1
+ # non-breaking spaces that we have to clean up later.
$self->nbsp_for_S (1);
# Tell Pod::Simple to keep whitespace whenever possible.
$text =~ s/([^\x00-\x7F])/$ESCAPES{ord ($1)} || "X"/eg;
}
+ # For Unicode output, unconditionally remap ISO 8859-1 non-breaking spaces
+ # to the correct code point. This is really a bug in Pod::Simple to be
+ # embedding ISO 8859-1 characters in the output stream that we see.
+ if ($$self{utf8} && ASCII) {
+ $text =~ s/\xA0/\xC2\xA0/g;
+ }
+
# Ensure that *roff doesn't convert literal quotes to UTF-8 single quotes,
# but don't mess up our accept escapes.
if ($literal) {
# module, but this order is correct for both Solaris and Linux.
sub preamble {
my ($self, $name, $section, $date) = @_;
- my $preamble = $self->preamble_template;
+ my $preamble = $self->preamble_template (!$$self{utf8});
# Build the index line and make sure that it will be syntactically valid.
my $index = "$name $section";
sub cmd_head2 {
my ($self, $attrs, $text) = @_;
$text = $self->heading_common ($text, $$attrs{start_line});
- $self->output ($self->switchquotes ('.Sh', $self->mapfonts ($text)));
+ $self->output ($self->switchquotes ('.SS', $self->mapfonts ($text)));
$self->outindex ('Subsection', $text);
$$self{NEEDSPACE} = 0;
return '';
# results are pretty poor.
#
# This only works in an ASCII world. What to do in a non-ASCII world is very
-# unclear.
+# unclear -- hopefully we can assume UTF-8 and just leave well enough alone.
@ESCAPES{0xA0 .. 0xFF} = (
"\\ ", undef, undef, undef, undef, undef, undef, undef,
undef, undef, undef, undef, undef, "\\%", undef, undef,
##############################################################################
# The following is the static preamble which starts all *roff output we
-# generate. It's completely static except for the font to use as a
-# fixed-width font, which is designed by @CFONT@, and the left and right
-# quotes to use for C<> text, designated by @LQOUTE@ and @RQUOTE@.
+# generate. Most is static except for the font to use as a fixed-width font,
+# which is designed by @CFONT@, and the left and right quotes to use for C<>
+# text, designated by @LQOUTE@ and @RQUOTE@. However, the second part, which
+# defines the accent marks, is only used if $escapes is set to true.
sub preamble_template {
- return <<'----END OF PREAMBLE----';
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\&\\$1\fR
-.PP
-..
+ my ($self, $accents) = @_;
+ my $preamble = <<'----END OF PREAMBLE----';
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
.el .ds Aq '
.\"
.\" 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
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
..
.\}
+----END OF PREAMBLE----
+
+ if ($accents) {
+ $preamble .= <<'----END OF PREAMBLE----'
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.rm #[ #] #H #V #F C
----END OF PREAMBLE----
#`# for cperl-mode
+ }
+ return $preamble;
}
##############################################################################
Pod::Man - Convert POD data to formatted *roff input
+=for stopwords
+en em ALLCAPS teeny fixedbold fixeditalic fixedbolditalic utf8 UTF-8
+Allbery Sean Burke Ossanna
+
=head1 SYNOPSIS
use Pod::Man;
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).
+C<STDIN> for input).
Pod::Man assumes that your *roff formatters have a fixed-width font named
-CW. If yours is called something else (like CR), use the C<fixed> option to
-specify it. This generally only matters for troff output for printing.
-Similarly, you can set the fonts used for bold, italic, and bold italic
-fixed-width output.
-
-Besides the obvious pod conversions, Pod::Man also takes care of formatting
-func(), func(3), and simple variable references like $foo or @bar so you
-don't have to use code escapes for them; complex expressions like
-C<$fred{'stuff'}> will still need to be escaped, though. It also translates
-dashes that aren't used as hyphens into en dashes, makes long dashes--like
-this--into proper em dashes, fixes "paired quotes," makes C++ look right,
-puts a little space between double underbars, makes ALLCAPS a teeny bit
-smaller in B<troff>, and escapes stuff that *roff treats as special so that
-you don't have to.
+C<CW>. If yours is called something else (like C<CR>), use the C<fixed>
+option to specify it. This generally only matters for troff output for
+printing. Similarly, you can set the fonts used for bold, italic, and
+bold italic fixed-width output.
+
+Besides the obvious pod conversions, Pod::Man also takes care of
+formatting func(), func(3), and simple variable references like $foo or
+@bar so you don't have to use code escapes for them; complex expressions
+like C<$fred{'stuff'}> will still need to be escaped, though. It also
+translates dashes that aren't used as hyphens into en dashes, makes long
+dashes--like this--into proper em dashes, fixes "paired quotes," makes C++
+look right, puts a little space between double underscores, makes ALLCAPS
+a teeny bit smaller in B<troff>, and escapes stuff that *roff treats as
+special so that you don't have to.
The recognized options to new() are as follows. All options take a single
argument.
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.
+case if the input is from C<STDIN>), and the date will be formatted as
+C<YYYY-MM-DD>.
=item fixed
-The fixed-width font to use for vertabim text and code. Defaults to CW.
-Some systems may want CR instead. Only matters for B<troff> output.
+The fixed-width font to use for verbatim text and code. Defaults to
+C<CW>. Some systems may want C<CR> instead. Only matters for B<troff>
+output.
=item fixedbold
-Bold version of the fixed-width font. Defaults to CB. Only matters for
-B<troff> output.
+Bold version of the fixed-width font. Defaults to C<CB>. Only matters
+for B<troff> output.
=item fixeditalic
Italic version of the fixed-width font (actually, something of a misnomer,
since most fixed-width fonts only have an oblique version, not an italic
-version). Defaults to CI. Only matters for B<troff> output.
+version). Defaults to C<CI>. Only matters for B<troff> output.
=item fixedbolditalic
Bold italic (probably actually oblique) version of the fixed-width font.
-Pod::Man doesn't assume you have this, and defaults to CB. Some systems
-(such as Solaris) have this font available as CX. Only matters for B<troff>
-output.
+Pod::Man doesn't assume you have this, and defaults to C<CB>. Some
+systems (such as Solaris) have this font available as C<CX>. Only matters
+for B<troff> output.
=item name
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.
+By default, section 1 will be used unless the file ends in C<.pm> in which
+case section 3 will be selected.
=item utf8
=back
The standard Pod::Simple method parse_file() takes one argument naming the
-POD file to read from. By default, the output is sent to STDOUT, but this
-can be changed with the output_fd() method.
+POD file to read from. By default, the output is sent to C<STDOUT>, but
+this can be changed with the output_fd() method.
The standard Pod::Simple method parse_from_file() takes up to two
arguments, the first being the input file to read POD from and the second
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
-by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
+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.
# Pod::ParseLink -- Parse an L<> formatting code in POD text.
#
-# Copyright 2001 by Russ Allbery <rra@stanford.edu>
+# Copyright 2001, 2008 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.
@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.06;
-
+$VERSION = 1.07;
##############################################################################
# Implementation
}
}
-
##############################################################################
# Module return value and documentation
##############################################################################
Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
+=for stopwords
+markup Allbery
+
=head1 SYNOPSIS
use Pod::ParseLink;
=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.
+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 C<url>, C<pod>, or C<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
it's interpreted as a link to a section for backwards compatibility.
No attempt is made to resolve formatting codes. This must be done after
-calling parselink (since EE<lt>E<gt> formatting codes can be used to escape
-characters that would otherwise be significant to the parser and resolving
-them before parsing would result in an incorrect parse of a formatting code
-like:
+calling parselink() (since EE<lt>E<gt> formatting codes can be used to
+escape characters that would otherwise be significant to the parser and
+resolving them before parsing would result in an incorrect parse of a
+formatting code like:
L<verticalE<verbar>barE<sol>slash>
=head1 COPYRIGHT AND LICENSE
-Copyright 2001 by Russ Allbery <rra@stanford.edu>.
+Copyright 2001, 2008 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.
# Pod::Text -- Convert POD data to formatted ASCII text.
#
-# Copyright 1999, 2000, 2001, 2002, 2004, 2006
-# by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008
+# 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.
# We have to export pod2text for backward compatibility.
@EXPORT = qw(pod2text);
-# 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 = 3.08;
+$VERSION = 3.09;
##############################################################################
# Initialization
Pod::Text - Convert POD data to formatted ASCII text
+=for stopwords
+alt Allbery Sean Burke's
+
=head1 SYNOPSIS
use Pod::Text;
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2000, 2001, 2002, 2004, 2006 Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008 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.
# Pod::Text::Color -- Convert POD data to formatted color ASCII text
#
-# Copyright 1999, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2001, 2004, 2006, 2008 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.
@ISA = qw(Pod::Text);
-# 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.03;
+$VERSION = 2.04;
##############################################################################
# Overrides
Pod::Text::Color - Convert POD data to formatted color ASCII text
+=for stopwords
+Allbery
+
=head1 SYNOPSIS
use Pod::Text::Color;
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2001, 2004, 2006, 2008 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.
#
# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
# (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
+# Copyright 2000 Joe Smith <Joe.Smith@inwap.com>.
+# Copyright 2001, 2004, 2008 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.
@ISA = qw(Pod::Text);
-# 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.00;
+$VERSION = 2.01;
##############################################################################
# Overrides
Pod::Text::Overstrike - Convert POD data to formatted overstrike text
+=for stopwords
+overstruck Overstruck Allbery
+
=head1 SYNOPSIS
use Pod::Text::Overstrike;
Pod::Text::Overstrike is a simple subclass of Pod::Text that highlights
output text using overstrike sequences, in a manner similar to nroff.
-Characters in bold text are overstruck (character, backspace, character) and
-characters in underlined text are converted to overstruck underscores
-(underscore, backspace, character). This format was originally designed for
-hardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT)
-terminals.
+Characters in bold text are overstruck (character, backspace, character)
+and characters in underlined text are converted to overstruck underscores
+(underscore, backspace, character). This format was originally designed
+for hard-copy terminals and/or line printers, yet is readable on soft-copy
+(CRT) terminals.
Overstruck text is best viewed by page-at-a-time programs that take
advantage of the terminal's B<stand-out> and I<underline> capabilities, such
# Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
#
-# Copyright 1999, 2001, 2002, 2004, 2006 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2001, 2002, 2004, 2006, 2008 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.
@ISA = qw(Pod::Text);
-# 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.03;
+$VERSION = 2.04;
##############################################################################
# Overrides
Pod::Text::Termcap - Convert POD data to ASCII text with format escapes
+=for stopwords
+ECMA-48 VT100 Allbery
+
=head1 SYNOPSIS
use Pod::Text::Termcap;
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2001, 2002, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2001, 2002, 2004, 2006, 2008 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.
.ie n .SH "This ""is"" a ""level 1"" heading"
.el .SH "This \f(CWis\fP a ``level 1'' heading"
.IX Header "This is a level 1 heading"
-.Sh "``Level'' ""2 \fIheading\fP"
+.SS "``Level'' ""2 \fIheading\fP"
.IX Subsection "``Level'' ""2 heading"
\fILevel 3 \f(BIheading \f(BIwith \f(CB\*(C`weird \f(CBstuff "" (double quote)\f(CB\*(C'\f(BI\f(BI\fI\fR
.IX Subsection "Level 3 heading with weird stuff """" (double quote)"
.el .SH "This \f(CWis\fP a ``level 1'' heading"
.IX Header "This is a level 1 heading"
Text.
-.Sh "``Level'' 2 \fIheading\fP"
+.SS "``Level'' 2 \fIheading\fP"
.IX Subsection "``Level'' 2 heading"
Text.
.PP
}
unshift (@INC, '../blib/lib');
$| = 1;
- print "1..2\n";
+ print "1..7\n";
}
END {
open (OUT, '> out.tmp') or die "Cannot create out.tmp: $!\n";
$parser->parse_from_file ('tmp.pod', \*OUT);
close OUT;
+ my $accents = 0;
open (TMP, 'out.tmp') or die "Cannot open out.tmp: $!\n";
- while (<TMP>) { last if /^\.nh/ }
+ while (<TMP>) {
+ $accents = 1 if /Accent mark definitions/;
+ last if /^\.nh/;
+ }
my $output;
{
local $/;
}
close TMP;
unlink ('tmp.pod', 'out.tmp');
+ if (($options{utf8} && !$accents) || (!$options{utf8} && $accents)) {
+ print "ok $n\n";
+ } else {
+ print "not ok $n\n";
+ print ($accents ? "Saw accents\n" : "Saw no accents\n");
+ print ($options{utf8} ? "Wanted no accents\n" : "Wanted accents\n");
+ }
+ $n++;
my $expected = '';
while (<DATA>) {
last if $_ eq "###\n";
.PP
Older versions did not convert Beyoncé in verbatim.
###
+
+###
+utf8 1
+###
+=head1 SE<lt>E<gt> output with UTF-8
+
+This is S<non-breaking output>.
+###
+.SH "S<> output with UTF\-8"
+.IX Header "S<> output with UTF-8"
+This is non\-breaking output.
+###
+
+###
+fixed CR
+fixedbold CY
+fixeditalic CW
+fixedbolditalic CX
+###
+=head1 FIXED FONTS
+
+C<foo B<bar I<baz>> I<bay>>
+###
+.SH "FIXED FONTS"
+.IX Header "FIXED FONTS"
+\&\f(CR\*(C`foo \f(CYbar \f(CXbaz\f(CY\f(CR \f(CWbay\f(CR\*(C'\fR
+###
###
.SH "NAME"
"Stuff" (no guesswork)
-.Sh "\s-1THINGS\s0"
+.SS "\s-1THINGS\s0"
.IX Subsection "THINGS"
Oboy, is this \*(C+ \*(L"fun\*(R" yet! (guesswork)
###
--- /dev/null
+#!/usr/bin/perl
+#
+# t/pod-spelling.t -- Test POD spelling.
+
+# Called to skip all tests with a reason.
+sub skip_all {
+ print "1..1\n";
+ print "ok 1 # skip - @_\n";
+ exit;
+}
+
+# Make sure we have prerequisites. hunspell is currently not supported due to
+# lack of support for contractions.
+eval 'use Test::Pod 1.00';
+skip_all "Test::Pod 1.00 required for testing POD" if $@;
+eval 'use Pod::Spell';
+skip_all "Pod::Spell required to test POD spelling" if $@;
+my @spell;
+for my $dir (split ':', $ENV{PATH}) {
+ if (-x "$dir/ispell") {
+ @spell = ("$dir/ispell", '-d', 'american', '-l');
+ }
+ last if @spell;
+}
+skip_all "ispell required to test POD spelling" unless @spell;
+
+# Run the test, one for each POD file.
+$| = 1;
+my @pod = all_pod_files ();
+my $count = scalar @pod;
+print "1..$count\n";
+my $n = 1;
+for my $pod (@pod) {
+ my $child = open (CHILD, '-|');
+ if (not defined $child) {
+ die "Cannot fork: $!\n";
+ } elsif ($child == 0) {
+ my $pid = open (SPELL, '|-', @spell) or die "Cannot run @spell: $!\n";
+ open (POD, '<', $pod) or die "Cannot open $pod: $!\n";
+ my $parser = Pod::Spell->new;
+ $parser->parse_from_filehandle (\*POD, \*SPELL);
+ close POD;
+ close SPELL;
+ exit ($? >> 8);
+ } else {
+ my @words = <CHILD>;
+ close CHILD;
+ if ($? != 0) {
+ print "ok $n # skip - @spell failed\n";
+ } elsif (@words) {
+ for (@words) {
+ s/^\s+//;
+ s/\s+$//;
+ }
+ print "not ok $n\n";
+ print " - Misspelled words found in $pod\n";
+ print " @words\n";
+ } else {
+ print "ok $n\n";
+ }
+ $n++;
+ }
+}
--- /dev/null
+#!/usr/bin/perl
+#
+# t/pod.t -- Test POD formatting.
+
+eval 'use Test::Pod 1.00';
+if ($@) {
+ print "1..1\n";
+ print "ok 1 # skip - Test::Pod 1.00 required for testing POD\n";
+ exit;
+}
+all_pod_files_ok ();
}
if ($output eq $expected) {
print "ok $n\n";
+ } elsif ($n == 4 && $Pod::Simple::VERSION < 3.06) {
+ print "ok $n # skip Pod::Simple S<> parsing bug\n";
} else {
print "not ok $n\n";
print "Expected\n========\n$expected\nOutput\n======\n$output\n";
# pod2man -- Convert POD data to formatted *roff input.
#
-# Copyright 1999, 2000, 2001, 2004, 2006, 2008
-# Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008 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.
pod2man - Convert POD data to formatted *roff input
+=for stopwords
+en em --utf8 UTF-8 overdo markup MT-LEVEL Allbery
+
=head1 SYNOPSIS
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<--name>=I<name>] [B<--official>]
-[B<--lax>] [B<--quotes>=I<quotes>] [B<--verbose>]
-[I<input> [I<output>] ...]
+ [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<--name>=I<name>] [B<--official>]
+ [B<--lax>] [B<--quotes>=I<quotes>] [B<--verbose>]
+ [I<input> [I<output>] ...]
pod2man B<--help>
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. Several POD files can be
-processed in the same B<pod2man> invocation (saving module load and compile
-times) by providing multiple pairs of I<input> and I<output> files on the
-command line.
+code). If I<input> isn't given, it defaults to C<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 C<STDOUT>. Several POD
+files can be processed in the same B<pod2man> invocation (saving module
+load and compile times) by providing multiple pairs of I<input> and
+I<output> files on the command line.
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.
+B<pod2man> assumes that your *roff formatters have a fixed-width font
+named C<CW>. If yours is called something else (like C<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
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.
+C<STDIN>.
=item B<--fixed>=I<font>
-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.
+The fixed-width font to use for verbatim text and code. Defaults to
+C<CW>. Some systems may want C<CR> instead. Only matters for troff(1)
+output.
=item B<--fixedbold>=I<font>
-Bold version of the fixed-width font. Defaults to CB. Only matters for
-troff(1) output.
+Bold version of the fixed-width font. Defaults to C<CB>. Only matters
+for troff(1) output.
=item B<--fixeditalic>=I<font>
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 C<CI>. Only matters for troff(1) output.
=item B<--fixedbolditalic>=I<font>
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.
+Pod::Man doesn't assume you have this, and defaults to C<CB>. Some
+systems (such as Solaris) have this font available as C<CX>. Only matters
+for troff(1) output.
=item B<-h>, B<--help>
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.
+By default, section 1 will be used unless the file ends in C<.pm>, in
+which case section 3 will be selected.
=item B<-u>, B<--utf8>
troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
-To get index entries on stderr, turn on the F register, as in:
+To get index entries on C<STDERR>, turn on the F register, as in:
troff -man -rF1 perl.1
=item NAME
Mandatory section; should be a comma-separated list of programs or functions
-documented by this podpage, such as:
+documented by this POD page, such as:
foo, bar - programs to do something
Exceptions, error return codes, exit statuses, 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.
+C<STDOUT> or C<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.
=item DIAGNOSTICS
# pod2text -- Convert POD data to formatted ASCII text.
#
-# Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008 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.
pod2text - Convert POD data to formatted ASCII text
+=for stopwords
+-aclost --alt Allbery
+
=head1 SYNOPSIS
pod2text [B<-aclost>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
-S<[B<-w> I<width>]> [I<input> [I<output> ...]]
+ S<[B<-w> I<width>]> [I<input> [I<output> ...]]
pod2text B<-h>
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. Several POD files can be
-processed in the same B<pod2text> invocation (saving module load and compile
-times) by providing multiple pairs of I<input> and I<output> files on the
-command line.
+code). If I<input> isn't given, it defaults to C<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 C<STDOUT>. Several POD
+files can be processed in the same B<pod2text> invocation (saving module
+load and compile times) by providing multiple pairs of I<input> and
+I<output> files on the command line.
=head1 OPTIONS
=item B<-o>, B<--overstrike>
-Format the output with overstruck printing. Bold text is rendered as
+Format the output with overstrike printing. Bold text is rendered as
character, backspace, character. Italics and file names are rendered as
underscore, backspace, character. Many pagers, such as B<less>, know how
to convert this to bold or underlined text.
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008 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.
projects / p5sagit/p5-mst-13.2.git / commitdiff