Upgrade to Pod-Parser-1.35.

p4raw-id: //depot/perl@29126

10 files changed, 120 insertions, 24 deletions

diff --git a/MANIFEST b/MANIFEST
index b2460218a0..10fe82f03f 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 49162da4a2..e291617f36 100644
--- a/lib/Pod/Checker.pm
+++ b/lib/Pod/Checker.pm
@@ -82,7 +82,7 @@ C<LE<lt>...LE<lt>...E<gt>...E<gt>>).
 
 =item *
 
-Check for malformed or nonexisting entities C<EE<lt>...E<gt>>.
+Check for malformed or non-existing entities C<EE<lt>...E<gt>>.
 
 =item *
 
@@ -142,7 +142,7 @@ There is no specification of the formatter after the C<=for> command.
 =item * unresolved internal link I<NAME>
 
 The given link to I<NAME> 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<CMD>"
@@ -234,7 +234,7 @@ C<=over>/C<=back> block.
 
 =item * =item type mismatch (I<one> vs. I<two>)
 
-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<first> 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<Pod::Checker> module uses only the B<poderror>
 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<podchecker> (the script). This allows users of B<Pod::Checker> to
-control completely the output behaviour. Users of B<podchecker> (the script)
-get the well-known behaviour.
+control completely the output behavior. Users of B<podchecker> (the script)
+get the well-known behavior.
 
 =cut
 
diff --git a/lib/Pod/ParseUtils.pm b/lib/Pod/ParseUtils.pm
index 878860121d..13d66ab8d2 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 a5fde84850..d242a516af 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<Pod::Parser> 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<Pod::Parser> 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<parse_text()> 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<emit()> method if they
 are objects/references.
 
+=head1 CAVEATS
+
+Please note that POD has the notion of "paragraphs": this is something
+starting I<after> 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<must> be preceded with a blank
+line; C<__END__> is I<not> a blank line.
+
 =head1 SEE ALSO
 
 L<Pod::InputObjects>, L<Pod::Select>
diff --git a/lib/Pod/PlainText.pm b/lib/Pod/PlainText.pm
index 3f5ce90d2b..ec56608ff2 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 1cc14dff4b..321a68ab0d 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 40e517efac..464da247b0 100644
--- a/lib/Pod/Usage.pm
+++ b/lib/Pod/Usage.pm
@@ -212,8 +212,8 @@ to C<STDOUT>, 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 E<lt>bradapp@enteract.comE<gt>
 Based on code for B<Pod::Text::pod2text()> written by
 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
 
-=head1 ACKNOWLEDGEMENTS
+=head1 ACKNOWLEDGMENTS
 
 Steven McDougall E<lt>swmcd@world.std.comE<gt> 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 0000000000..ec0e3a7e50
--- /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 5f6217192c..17f0b0b4c2 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 0000000000..098bc3c628
--- /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<silly> 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
+