From 0e4e3f6e96b9ad39aace3852993d3e7cb5e33891 Mon Sep 17 00:00:00 2001 From: Steve Hay Date: Tue, 22 Jul 2008 08:21:12 +0000 Subject: [PATCH] Upgrade to podlators 2.1.2 p4raw-id: //depot/perl@34153 --- MANIFEST | 2 + Porting/Maintainers.pl | 2 +- lib/Pod/Man.pm | 115 +++++++++++++++++++++++++-------------------- lib/Pod/ParseLink.pm | 32 ++++++------- lib/Pod/Text.pm | 15 +++--- lib/Pod/Text/Color.pm | 12 ++--- lib/Pod/Text/Overstrike.pm | 20 ++++---- lib/Pod/Text/Termcap.pm | 13 ++--- lib/Pod/t/basic.man | 4 +- lib/Pod/t/man-options.t | 43 ++++++++++++++++- lib/Pod/t/man.t | 2 +- lib/Pod/t/pod-spelling.t | 63 +++++++++++++++++++++++++ lib/Pod/t/pod.t | 11 +++++ lib/Pod/t/text.t | 2 + pod/pod2man.PL | 74 +++++++++++++++-------------- pod/pod2text.PL | 24 ++++++---- 16 files changed, 286 insertions(+), 148 deletions(-) create mode 100644 lib/Pod/t/pod-spelling.t create mode 100644 lib/Pod/t/pod.t diff --git a/MANIFEST b/MANIFEST index 6a1bf53..ed17b84 100644 --- a/MANIFEST +++ b/MANIFEST @@ -2600,6 +2600,8 @@ lib/Pod/t/parselink.t podlators test 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 diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index fe746b2..3df80ce 100644 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -765,7 +765,7 @@ package Maintainers; '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, }, diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm index 00b1f1b..9af59bb 100644 --- a/lib/Pod/Man.pm +++ b/lib/Pod/Man.pm @@ -36,10 +36,7 @@ use POSIX qw(strftime); @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 @@ -72,7 +69,9 @@ sub new { 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. @@ -363,6 +362,13 @@ sub format_text { $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) { @@ -849,7 +855,7 @@ sub devise_date { # 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"; @@ -1023,7 +1029,7 @@ sub cmd_head1 { 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 ''; @@ -1271,7 +1277,7 @@ sub parse_from_filehandle { # 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, @@ -1297,19 +1303,13 @@ sub parse_from_filehandle { ############################################################################## # 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 @@ -1353,7 +1353,7 @@ sub preamble_template { .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 \{\ @@ -1367,6 +1367,10 @@ sub preamble_template { . 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. @@ -1431,6 +1435,8 @@ sub preamble_template { .rm #[ #] #H #V #F C ----END OF PREAMBLE---- #`# for cperl-mode + } + return $preamble; } ############################################################################## @@ -1444,6 +1450,10 @@ __END__ 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; @@ -1476,23 +1486,23 @@ 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). +C 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 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, and escapes stuff that *roff treats as special so that -you don't have to. +C. If yours is called something else (like C), use the C +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, 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. @@ -1508,31 +1518,32 @@ Documentation". 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), and the date will be formatted as +C. =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 output. +The fixed-width font to use for verbatim text and code. Defaults to +C. Some systems may want C instead. Only matters for B +output. =item fixedbold -Bold version of the fixed-width font. Defaults to CB. Only matters for -B output. +Bold version of the fixed-width font. Defaults to C. Only matters +for B 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 output. +version). Defaults to C. Only matters for B 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 -output. +Pod::Man doesn't assume you have this, and defaults to C. Some +systems (such as Solaris) have this font available as C. Only matters +for B output. =item name @@ -1574,8 +1585,8 @@ 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. +By default, section 1 will be used unless the file ends in C<.pm> in which +case section 3 will be selected. =item utf8 @@ -1596,8 +1607,8 @@ behavior. =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, 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 @@ -1674,8 +1685,8 @@ mine). =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 -by Russ Allbery . +Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 +Russ Allbery . This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/ParseLink.pm b/lib/Pod/ParseLink.pm index d1ce44b..18dd47e 100644 --- a/lib/Pod/ParseLink.pm +++ b/lib/Pod/ParseLink.pm @@ -1,6 +1,6 @@ # Pod::ParseLink -- Parse an L<> formatting code in POD text. # -# Copyright 2001 by Russ Allbery +# Copyright 2001, 2008 by Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -30,11 +30,7 @@ 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.06; - +$VERSION = 1.07; ############################################################################## # Implementation @@ -99,7 +95,6 @@ sub parselink { } } - ############################################################################## # Module return value and documentation ############################################################################## @@ -112,6 +107,9 @@ __END__ Pod::ParseLink - Parse an LEE formatting code in POD text +=for stopwords +markup Allbery + =head1 SYNOPSIS use Pod::ParseLink; @@ -120,11 +118,11 @@ Pod::ParseLink - Parse an LEE formatting code in POD text =head1 DESCRIPTION This module only provides a single function, parselink(), which takes the -text of an LEE 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 LEE 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, C, or C, +indicating a URL, a link to a POD page, or a link to a Unix manual page. Parsing is implemented per L. For backward compatibility, links where there is no section and name contains spaces, or links where the @@ -146,10 +144,10 @@ If the text of the LEE escape is entirely enclosed in double quotes, 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 EEE 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 EEE 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: LbarEslash> @@ -175,7 +173,7 @@ Russ Allbery . =head1 COPYRIGHT AND LICENSE -Copyright 2001 by Russ Allbery . +Copyright 2001, 2008 Russ Allbery . This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm index d52bb53..18edb70 100644 --- a/lib/Pod/Text.pm +++ b/lib/Pod/Text.pm @@ -1,7 +1,7 @@ # Pod::Text -- Convert POD data to formatted ASCII text. # -# Copyright 1999, 2000, 2001, 2002, 2004, 2006 -# by Russ Allbery +# Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008 +# Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -37,10 +37,7 @@ use Pod::Simple (); # 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 @@ -634,6 +631,9 @@ __END__ Pod::Text - Convert POD data to formatted ASCII text +=for stopwords +alt Allbery Sean Burke's + =head1 SYNOPSIS use Pod::Text; @@ -777,7 +777,8 @@ how to use Pod::Simple. =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2000, 2001, 2002, 2004, 2006 Russ Allbery . +Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008 Russ Allbery +. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/Text/Color.pm b/lib/Pod/Text/Color.pm index 52b96c3..6f8a78f 100644 --- a/lib/Pod/Text/Color.pm +++ b/lib/Pod/Text/Color.pm @@ -1,6 +1,6 @@ # Pod::Text::Color -- Convert POD data to formatted color ASCII text # -# Copyright 1999, 2001, 2004, 2006 by Russ Allbery +# Copyright 1999, 2001, 2004, 2006, 2008 Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -25,10 +25,7 @@ use vars qw(@ISA $VERSION); @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 @@ -97,6 +94,9 @@ __END__ Pod::Text::Color - Convert POD data to formatted color ASCII text +=for stopwords +Allbery + =head1 SYNOPSIS use Pod::Text::Color; @@ -138,7 +138,7 @@ Russ Allbery . =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2001, 2004, 2006 by Russ Allbery . +Copyright 1999, 2001, 2004, 2006, 2008 Russ Allbery . This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/Text/Overstrike.pm b/lib/Pod/Text/Overstrike.pm index e2f7ccd..c11330d 100644 --- a/lib/Pod/Text/Overstrike.pm +++ b/lib/Pod/Text/Overstrike.pm @@ -2,6 +2,8 @@ # # Created by Joe Smith 30-Nov-2000 # (based on Pod::Text::Color by Russ Allbery ) +# Copyright 2000 Joe Smith . +# Copyright 2001, 2004, 2008 Russ Allbery . # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -32,10 +34,7 @@ use vars qw(@ISA $VERSION); @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 @@ -149,6 +148,9 @@ __END__ Pod::Text::Overstrike - Convert POD data to formatted overstrike text +=for stopwords +overstruck Overstruck Allbery + =head1 SYNOPSIS use Pod::Text::Overstrike; @@ -164,11 +166,11 @@ Pod::Text::Overstrike - Convert POD data to formatted overstrike text 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 and I capabilities, such diff --git a/lib/Pod/Text/Termcap.pm b/lib/Pod/Text/Termcap.pm index f60cc95..51d39ae 100644 --- a/lib/Pod/Text/Termcap.pm +++ b/lib/Pod/Text/Termcap.pm @@ -1,6 +1,6 @@ # Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes. # -# Copyright 1999, 2001, 2002, 2004, 2006 by Russ Allbery +# Copyright 1999, 2001, 2002, 2004, 2006, 2008 Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -26,10 +26,7 @@ use vars qw(@ISA $VERSION); @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 @@ -135,6 +132,9 @@ __END__ Pod::Text::Termcap - Convert POD data to ASCII text with format escapes +=for stopwords +ECMA-48 VT100 Allbery + =head1 SYNOPSIS use Pod::Text::Termcap; @@ -175,7 +175,8 @@ Russ Allbery . =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2001, 2002, 2004, 2006 by Russ Allbery . +Copyright 1999, 2001, 2002, 2004, 2006, 2008 Russ Allbery +. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/t/basic.man b/lib/Pod/t/basic.man index 9c2248e..43874b6 100644 --- a/lib/Pod/t/basic.man +++ b/lib/Pod/t/basic.man @@ -7,7 +7,7 @@ other interesting bits. .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)" @@ -20,7 +20,7 @@ Now try again with \fBintermixed\fR \fItext\fR. .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 diff --git a/lib/Pod/t/man-options.t b/lib/Pod/t/man-options.t index 928d754..f00e7d1 100644 --- a/lib/Pod/t/man-options.t +++ b/lib/Pod/t/man-options.t @@ -16,7 +16,7 @@ BEGIN { } unshift (@INC, '../blib/lib'); $| = 1; - print "1..2\n"; + print "1..7\n"; } END { @@ -47,8 +47,12 @@ while () { 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 () { last if /^\.nh/ } + while () { + $accents = 1 if /Accent mark definitions/; + last if /^\.nh/; + } my $output; { local $/; @@ -56,6 +60,14 @@ while () { } 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 () { last if $_ eq "###\n"; @@ -101,3 +113,30 @@ Beyoncé! Beyoncé! Beyoncé!! .PP Older versions did not convert Beyoncé in verbatim. ### + +### +utf8 1 +### +=head1 SEE output with UTF-8 + +This is S. +### +.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> I> +### +.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 +### diff --git a/lib/Pod/t/man.t b/lib/Pod/t/man.t index 6b16217..7071ba8 100644 --- a/lib/Pod/t/man.t +++ b/lib/Pod/t/man.t @@ -347,7 +347,7 @@ Oboy, is this C++ "fun" yet! (guesswork) ### .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) ### diff --git a/lib/Pod/t/pod-spelling.t b/lib/Pod/t/pod-spelling.t new file mode 100644 index 0000000..3ac4f75 --- /dev/null +++ b/lib/Pod/t/pod-spelling.t @@ -0,0 +1,63 @@ +#!/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 = ; + 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++; + } +} diff --git a/lib/Pod/t/pod.t b/lib/Pod/t/pod.t new file mode 100644 index 0000000..ecb37a6 --- /dev/null +++ b/lib/Pod/t/pod.t @@ -0,0 +1,11 @@ +#!/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 (); diff --git a/lib/Pod/t/text.t b/lib/Pod/t/text.t index 05d445a..185e944 100644 --- a/lib/Pod/t/text.t +++ b/lib/Pod/t/text.t @@ -57,6 +57,8 @@ while () { } 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"; diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 6c1570d..c98f8de 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -37,8 +37,7 @@ print OUT <<'!NO!SUBS!'; # pod2man -- Convert POD data to formatted *roff input. # -# Copyright 1999, 2000, 2001, 2004, 2006, 2008 -# Russ Allbery +# Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -98,14 +97,17 @@ __END__ 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] [B<--release>[=I]] -[B<--center>=I] [B<--date>=I] [B<--fixed>=I] -[B<--fixedbold>=I] [B<--fixeditalic>=I] -[B<--fixedbolditalic>=I] [B<--name>=I] [B<--official>] -[B<--lax>] [B<--quotes>=I] [B<--verbose>] -[I [I] ...] + [B<--center>=I] [B<--date>=I] [B<--fixed>=I] + [B<--fixedbold>=I] [B<--fixeditalic>=I] + [B<--fixedbolditalic>=I] [B<--name>=I] [B<--official>] + [B<--lax>] [B<--quotes>=I] [B<--verbose>] + [I [I] ...] pod2man B<--help> @@ -116,22 +118,22 @@ 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 is the file to read for POD source (the POD can be embedded in -code). If I isn't given, it defaults to STDIN. I, if given, -is the file to which to write the formatted output. If I isn't -given, the formatted output is written to STDOUT. Several POD files can be -processed in the same B invocation (saving module load and compile -times) by providing multiple pairs of I and I files on the -command line. +code). If I isn't given, it defaults to C. I, if +given, is the file to which to write the formatted output. If I +isn't given, the formatted output is written to C. Several POD +files can be processed in the same B invocation (saving module +load and compile times) by providing multiple pairs of I and +I 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 for details. -B 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 assumes that your *roff formatters have a fixed-width font +named C. If yours is called something else (like C), 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 @@ -155,30 +157,31 @@ Contributed Perl Documentation", but also see B<--official> below. 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. =item B<--fixed>=I -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. Some systems may want C instead. Only matters for troff(1) +output. =item B<--fixedbold>=I -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. Only matters +for troff(1) output. =item B<--fixeditalic>=I 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. Only matters for troff(1) output. =item B<--fixedbolditalic>=I 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. Some +systems (such as Solaris) have this font available as C. Only matters +for troff(1) output. =item B<-h>, B<--help> @@ -240,8 +243,8 @@ 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. +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> @@ -282,7 +285,7 @@ even/odd paging, at least on some versions of man(7). 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, turn on the F register, as in: troff -man -rF1 perl.1 @@ -326,7 +329,7 @@ The standard sections of a manual page are: =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 @@ -392,10 +395,11 @@ functions. 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 or C 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 diff --git a/pod/pod2text.PL b/pod/pod2text.PL index a978f71..81d29a6 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!'; # pod2text -- Convert POD data to formatted ASCII text. # -# Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery +# Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -111,10 +111,13 @@ __END__ pod2text - Convert POD data to formatted ASCII text +=for stopwords +-aclost --alt Allbery + =head1 SYNOPSIS pod2text [B<-aclost>] [B<--code>] [B<-i> I] S<[B<-q> I]> -S<[B<-w> I]> [I [I ...]] + S<[B<-w> I]> [I [I ...]] pod2text B<-h> @@ -125,12 +128,12 @@ 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 is the file to read for POD source (the POD can be embedded in -code). If I isn't given, it defaults to STDIN. I, if given, -is the file to which to write the formatted output. If I isn't -given, the formatted output is written to STDOUT. Several POD files can be -processed in the same B invocation (saving module load and compile -times) by providing multiple pairs of I and I files on the -command line. +code). If I isn't given, it defaults to C. I, if +given, is the file to which to write the formatted output. If I +isn't given, the formatted output is written to C. Several POD +files can be processed in the same B invocation (saving module +load and compile times) by providing multiple pairs of I and +I files on the command line. =head1 OPTIONS @@ -176,7 +179,7 @@ indented; for the latter, see B<-i> option. =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, know how to convert this to bold or underlined text. @@ -272,7 +275,8 @@ Russ Allbery . =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery . +Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery +. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. -- 2.7.4