From 267d554123ae974ccd717e77510a6c3e0691dab2 Mon Sep 17 00:00:00 2001 From: Steve Peters Date: Fri, 27 Oct 2006 13:29:05 +0000 Subject: [PATCH] Upgrade to Pod-Parser-1.35. p4raw-id: //depot/perl@29126 --- MANIFEST | 2 ++ lib/Pod/Checker.pm | 12 ++++++------ lib/Pod/ParseUtils.pm | 16 +++++++++------- lib/Pod/Parser.pm | 21 ++++++++++++++++----- lib/Pod/PlainText.pm | 17 +++++++++++++++++ lib/Pod/Select.pm | 6 +++--- lib/Pod/Usage.pm | 13 ++++++++++--- t/pod/p2u_data.pl | 18 ++++++++++++++++++ t/pod/testcmp.pl | 3 +++ t/pod/twice.t | 36 ++++++++++++++++++++++++++++++++++++ 10 files changed, 120 insertions(+), 24 deletions(-) create mode 100644 t/pod/p2u_data.pl create mode 100644 t/pod/twice.t diff --git a/MANIFEST b/MANIFEST index b246021..10fe82f 100644 --- a/MANIFEST +++ b/MANIFEST @@ -3542,6 +3542,7 @@ t/pod/nested_seqs.t Test nested interior sequences t/pod/nested_seqs.xr Expected results for nested_seqs.t t/pod/oneline_cmds.t Test single paragraph ==cmds t/pod/oneline_cmds.xr Expected results for oneline_cmds.t +t/pod/p2u_data.pl Test Pod::Usage t/pod/plainer.t Test Pod::Plainer t/pod/pod2usage2.t Test Pod::Usage t/pod/pod2usage.t Test Pod::Usage @@ -3556,6 +3557,7 @@ t/pod/testcmp.pl Module to compare output against expected results t/pod/testp2pt.pl Module to test Pod::PlainText for a given file t/pod/testpchk.pl Module to test Pod::Checker for a given file t/pod/testpods/lib/Pod/Stuff.pm Sample data for find.t +t/pod/twice.t Test Pod::Parser t/README Instructions for regression tests t/run/exit.t Test perl's exit status. t/run/fresh_perl.t Tests that require a fresh perl. diff --git a/lib/Pod/Checker.pm b/lib/Pod/Checker.pm index 49162da..e291617 100644 --- a/lib/Pod/Checker.pm +++ b/lib/Pod/Checker.pm @@ -82,7 +82,7 @@ C...LE...E...E>). =item * -Check for malformed or nonexisting entities C...E>. +Check for malformed or non-existing entities C...E>. =item * @@ -142,7 +142,7 @@ There is no specification of the formatter after the C<=for> command. =item * unresolved internal link I The given link to I does not have a matching node in the current -POD. This also happend when a single word node name is not enclosed in +POD. This also happened when a single word node name is not enclosed in C<"">. =item * Unknown command "I" @@ -234,7 +234,7 @@ C<=over>/C<=back> block. =item * =item type mismatch (I vs. I) -A list started with e.g. a bulletted C<=item> and continued with a +A list started with e.g. a bullet-like C<=item> and continued with a numbered one. This is obviously inconsistent. For most translators the type of the I C<=item> determines the type of the list. @@ -282,7 +282,7 @@ C<=head1>. =head2 Hyperlinks -There are some warnings wrt. malformed hyperlinks. +There are some warnings with respect to malformed hyperlinks: =over 4 @@ -332,8 +332,8 @@ Since PodParser-1.24 the B module uses only the B method to print errors and warnings. The summary output (e.g. "Pod syntax OK") has been dropped from the module and has been included in B (the script). This allows users of B to -control completely the output behaviour. Users of B (the script) -get the well-known behaviour. +control completely the output behavior. Users of B (the script) +get the well-known behavior. =cut diff --git a/lib/Pod/ParseUtils.pm b/lib/Pod/ParseUtils.pm index 8788601..13d66ab 100644 --- a/lib/Pod/ParseUtils.pm +++ b/lib/Pod/ParseUtils.pm @@ -10,7 +10,7 @@ package Pod::ParseUtils; use vars qw($VERSION); -$VERSION = 1.33; ## Current version of this package +$VERSION = 1.35; ## Current version of this package require 5.005; ## requires this Perl version or later =head1 NAME @@ -356,6 +356,13 @@ sub parse { $node = $1; $type = 'item'; } + + # non-standard: Hyperlink with alt-text - doesn't remove protocol prefix, maybe it should? + elsif(m!^ \s* (.*?) \s* [|] \s* (\w+:[^:\s] [^\s|]*?) \s* $!ix) { + ($alttext,$node) = ($1,$2); + $type = 'hyperlink'; + } + # non-standard: Hyperlink elsif(m!^(\w+:[^:\s]\S*)$!i) { $node = $1; @@ -370,11 +377,6 @@ sub parse { elsif(m!^(.*?)\s*[|]\s*/(.+)$!) { ($alttext, $node) = ($1,$2); } - # nonstandard: alttext and hyperlink - elsif(m!^(.*?)\s*[|]\s*(\w+:[^:\s]\S*)$!) { - ($alttext, $node) = ($1,$2); - $type = 'hyperlink'; - } # must be an item or a "malformed" section (without "") else { $node = $_; @@ -792,7 +794,7 @@ sub nodes { Look for a node or index entry named C<$name> in the object. Returns the unique id of the node (i.e. the second element of the array -stored in the node arry) or undef if not found. +stored in the node array) or undef if not found. =cut diff --git a/lib/Pod/Parser.pm b/lib/Pod/Parser.pm index a5fde84..d242a51 100644 --- a/lib/Pod/Parser.pm +++ b/lib/Pod/Parser.pm @@ -10,7 +10,7 @@ package Pod::Parser; use vars qw($VERSION); -$VERSION = 1.32; ## Current version of this package +$VERSION = 1.35; ## Current version of this package require 5.005; ## requires this Perl version or later ############################################################################# @@ -140,7 +140,7 @@ to avoid name collisions. For the most part, the B base class should be able to do most of the input parsing for you and leave you free to worry about -how to intepret the commands and translate the result. +how to interpret the commands and translate the result. Note that all we have described here in this quick overview is the simplest most straightforward use of B to do stream-based @@ -651,7 +651,7 @@ them in simple bottom-up order. The parameter C<$text> is a string or block of text to be parsed for interior sequences; and the parameter C<$line_num> is the -line number curresponding to the beginning of C<$text>. +line number corresponding to the beginning of C<$text>. B will parse the given text into a parse-tree of "nodes." and interior-sequences. Each "node" in the parse tree is either a @@ -844,7 +844,7 @@ sub parse_text { $seq->append($expand_text ? &$xtext_sub($self,$_,$seq) : $_); } ## Keep track of line count - $line += tr/\n//; + $line += s/\r*\n//; ## Remember the "current" sequence $seq = $seq_stack[-1]; } @@ -1156,7 +1156,10 @@ sub parse_from_file { my $self = shift; my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : (); my ($infile, $outfile) = @_; - my ($in_fh, $out_fh) = (gensym(), gensym()) if ($] < 5.006); + my ($in_fh, $out_fh); + if ($] < 5.006) { + ($in_fh, $out_fh) = (gensym(), gensym()); + } my ($close_input, $close_output) = (0, 0); local *myData = $self; local *_; @@ -1761,6 +1764,14 @@ the children (most likely from left to right) by formatting them if they are text-strings, or by calling their B method if they are objects/references. +=head1 CAVEATS + +Please note that POD has the notion of "paragraphs": this is something +starting I a blank (read: empty) line, with the single exception +of the file start, which is also starting a paragraph. That means that +especially a command (e.g. C<=head1>) I be preceded with a blank +line; C<__END__> is I a blank line. + =head1 SEE ALSO L, L diff --git a/lib/Pod/PlainText.pm b/lib/Pod/PlainText.pm index 3f5ce90..ec56608 100644 --- a/lib/Pod/PlainText.pm +++ b/lib/Pod/PlainText.pm @@ -303,6 +303,23 @@ sub cmd_head2 { } } +# third level heading - not strictly perlpodspec compliant +sub cmd_head3 { + my $self = shift; + local $_ = shift; + s/\s+$//; + $_ = $self->interpolate ($_, shift); + if ($$self{alt}) { + $self->output ("\n= $_ =\n"); + } else { + $self->output (' ' x ($$self{indent}) . $_ . "\n"); + } +} + +# fourth level heading - not strictly perlpodspec compliant +# just like head3 +*cmd_head4 = \&cmd_head3; + # Start a list. sub cmd_over { my $self = shift; diff --git a/lib/Pod/Select.pm b/lib/Pod/Select.pm index 1cc14df..321a68a 100644 --- a/lib/Pod/Select.pm +++ b/lib/Pod/Select.pm @@ -10,7 +10,7 @@ package Pod::Select; use vars qw($VERSION); -$VERSION = 1.30; ## Current version of this package +$VERSION = 1.35; ## Current version of this package require 5.005; ## requires this Perl version or later ############################################################################# @@ -505,7 +505,7 @@ sub is_selected { ## Keep track of current sections levels and headings $_ = $paragraph; - if (/^=((?:sub)*)(?:head(?:ing)?|sec(?:tion)?)(\d*)\s+(.*)\s*$/) + if (/^=((?:sub)*)(?:head(?:ing)?|sec(?:tion)?)(\d*)\s+(.*?)\s*$/) { ## This is a section heading command my ($level, $heading) = ($2, $3); @@ -575,7 +575,7 @@ are used. All other arguments should correspond to the names of input files containing POD sections. A file name of "-" or "<&STDIN" will -be interpeted to mean standard input (which is the default if no +be interpreted to mean standard input (which is the default if no filenames are given). =cut diff --git a/lib/Pod/Usage.pm b/lib/Pod/Usage.pm index 40e517e..464da24 100644 --- a/lib/Pod/Usage.pm +++ b/lib/Pod/Usage.pm @@ -212,8 +212,8 @@ to C, just in case the user wants to pipe the output to a pager =item * If program usage has been explicitly requested by the user, it is often -desireable to exit with a status of 1 (as opposed to 0) after issuing -the user-requested usage message. It is also desireable to give a +desirable to exit with a status of 1 (as opposed to 0) after issuing +the user-requested usage message. It is also desirable to give a more verbose description of program usage in this case. =back @@ -413,7 +413,7 @@ Brad Appleton Ebradapp@enteract.comE Based on code for B written by Tom Christiansen Etchrist@mox.perl.comE -=head1 ACKNOWLEDGEMENTS +=head1 ACKNOWLEDGMENTS Steven McDougall Eswmcd@world.std.comE for his help and patience with re-writing this manpage. @@ -534,6 +534,9 @@ sub pod2usage { elsif ($opts{"-verbose"} >= 2 && $opts{"-verbose"} != 99) { $parser->select('.*'); } + elsif ($opts{"-verbose"} >= 2 && $opts{"-verbose"} != 99) { + $parser->select('.*'); + } elsif ($opts{"-verbose"} == 99) { $parser->select( $opts{"-sections"} ); $opts{"-verbose"} = 1; @@ -548,6 +551,10 @@ sub pod2usage { ## spit out the entire PODs. Might as well invoke perldoc my $progpath = File::Spec->catfile($Config{scriptdir}, "perldoc"); system($progpath, $opts{"-input"}); + if($?) { + # RT16091: fall back to more if perldoc failed + system($ENV{PAGER} || 'more', $opts{"-input"}); + } } else { $parser->parse_from_file($opts{"-input"}, $opts{"-output"}); diff --git a/t/pod/p2u_data.pl b/t/pod/p2u_data.pl new file mode 100644 index 0000000..ec0e3a7 --- /dev/null +++ b/t/pod/p2u_data.pl @@ -0,0 +1,18 @@ +use Pod::Usage; +pod2usage(-verbose => 2, -exit => 17, -input => \*DATA); + +__DATA__ +=head1 NAME + +Test + +=head1 SYNOPSIS + +perl podusagetest.pl + +=head1 DESCRIPTION + +This is a test. + +=cut + diff --git a/t/pod/testcmp.pl b/t/pod/testcmp.pl index 5f62171..17f0b0b 100644 --- a/t/pod/testcmp.pl +++ b/t/pod/testcmp.pl @@ -65,6 +65,9 @@ sub testcmp( $ $ ; $) { defined($f2text = <$fh2>) and chomp($f2text); ++$line; last unless ( defined($f1text) and defined($f2text) ); + # kill any extra line endings + $f1text =~ s/[\r\n]+$//s; + $f2text =~ s/[\r\n]+$//s; $diffs = (ref $cmplines) ? &$cmplines($f1text, $f2text) : ($f1text ne $f2text); last if $diffs; diff --git a/t/pod/twice.t b/t/pod/twice.t new file mode 100644 index 0000000..098bc3c --- /dev/null +++ b/t/pod/twice.t @@ -0,0 +1,36 @@ +use strict; +use Test; +use File::Spec; + +BEGIN { plan tests => 1 } + +use Pod::Parser; +use Carp; +$SIG{__DIE__} = \&Carp::confess; + +eval {require IO::String;}; +skip($@ ? 'no IO::String' : '', sub { + { + my $pod_string = 'some I text'; + my $handle = IO::String->new( \$pod_string ); + my $parser = Pod::Parser->new(); + $parser->parse_from_file( $0, $handle ); + } + # free the reference + { + my $parser = Pod::Parser->new(); + $parser->parse_from_file( $0, File::Spec->devnull ); + } + 1; +}); + +exit 0; + +__END__ + +=head1 EXAMPLE + +This test makes sure the parse_from_file is re-entrant + +=cut + -- 2.7.4