Integrate PodParser-1.20, with matching tweaks to lib/Pod/t/latex.t

and lib/Pod/t/utils.t to cater for simpler output text.

p4raw-id: //depot/perl@18224

5 files changed, 55 insertions, 29 deletions

diff --git a/lib/Pod/Checker.pm b/lib/Pod/Checker.pm
index 5aca76c7ac..637c415d9d 100644
--- a/lib/Pod/Checker.pm
+++ b/lib/Pod/Checker.pm
@@ -10,7 +10,7 @@
 package Pod::Checker;
 
 use vars qw($VERSION);
-$VERSION = 1.3;  ## Current version of this package
+$VERSION = 1.40;  ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 use Pod::ParseUtils; ## for hyperlinks and lists
@@ -274,6 +274,11 @@ The NAME section (C<=head1 NAME>) should consist of a single paragraph
 with the script/module name, followed by a dash `-' and a very short
 description of what the thing is good for.
 
+=item * =headI<n> without preceding higher level
+
+For example if there is a C<=head2> in the POD file prior to a
+C<=head1>.
+
 =back
 
 =head2 Hyperlinks
@@ -548,6 +553,7 @@ sub initialize {
     ## Initialize number of errors, and setup an error function to
     ## increment this number and then print to the designated output.
     $self->{_NUM_ERRORS} = 0;
+    $self->{_NUM_WARNINGS} = 0;
     $self->{-quiet} ||= 0;
     # set the error handling subroutine
     $self->errorsub($self->{-quiet} ? sub { 1; } : 'poderror');
@@ -609,6 +615,8 @@ sub poderror {
     ## Increment error count and print message "
     ++($self->{_NUM_ERRORS}) 
         if(!%opts || ($opts{-severity} && $opts{-severity} eq 'ERROR'));
+    ++($self->{_NUM_WARNINGS})
+        if(!%opts || ($opts{-severity} && $opts{-severity} eq 'WARNING'));
     my $out_fh = $self->output_handle() || \*STDERR;
     print $out_fh ($severity, $msg, $line, $file, "\n")
       if($self->{-warnings} || !%opts || $opts{-severity} ne 'WARNING');
@@ -628,6 +636,18 @@ sub num_errors {
 
 ##################################
 
+=item C<$checker-E<gt>num_warnings()>
+
+Set (if argument specified) and retrieve the number of warnings found.
+
+=cut
+
+sub num_warnings {
+   return (@_ > 1) ? ($_[0]->{_NUM_WARNINGS} = $_[1]) : $_[0]->{_NUM_WARNINGS};
+}
+
+##################################
+
 =item C<$checker-E<gt>name()>
 
 Set (if argument specified) and retrieve the canonical name of POD as
@@ -907,17 +927,24 @@ sub command {
             }
         }
         elsif($cmd =~ /^head(\d+)/) {
+            my $hnum = $1;
+            $self->{"_have_head_$hnum"}++; # count head types
+            if($hnum > 1 && !$self->{"_have_head_".($hnum -1)}) {
+              $self->poderror({ -line => $line, -file => $file,
+                   -severity => 'WARNING', 
+                   -msg => "=head$hnum without preceding higher level"});
+            }
             # check whether the previous =head section had some contents
             if(defined $self->{_commands_in_head} &&
               $self->{_commands_in_head} == 0 &&
               defined $self->{_last_head} &&
-              $self->{_last_head} >= $1) {
+              $self->{_last_head} >= $hnum) {
                 $self->poderror({ -line => $line, -file => $file,
                      -severity => 'WARNING', 
                      -msg => "empty section in previous paragraph"});
             }
             $self->{_commands_in_head} = -1;
-            $self->{_last_head} = $1;
+            $self->{_last_head} = $hnum;
             # check if there is an open list
             if(@{$self->{_list_stack}}) {
                 my $list;
diff --git a/lib/Pod/ParseUtils.pm b/lib/Pod/ParseUtils.pm
index db615a57c4..18e9626e0e 100644
--- a/lib/Pod/ParseUtils.pm
+++ b/lib/Pod/ParseUtils.pm
@@ -10,7 +10,7 @@
 package Pod::ParseUtils;
 
 use vars qw($VERSION);
-$VERSION = 0.22;   ## Current version of this package
+$VERSION = 0.30;   ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 =head1 NAME
@@ -284,7 +284,7 @@ sub parse {
     my $self = shift;
     local($_) = $_[0];
     # syntax check the link and extract destination
-    my ($alttext,$page,$node,$type) = (undef,'','','');
+    my ($alttext,$page,$node,$type,$quoted) = (undef,'','','',0);
 
     $self->{_warnings} = [];
 
@@ -311,7 +311,7 @@ sub parse {
     # problem: a lot of people use (), or (1) or the like to indicate
     # man page sections. But this collides with L<func()> that is supposed
     # to point to an internal funtion...
-    my $page_rx = '[\w.]+(?:::[\w.]+)*(?:[(](?:\d\w*|)[)]|)';
+    my $page_rx = '[\w.-]+(?:::[\w.-]+)*(?:[(](?:\d\w*|)[)]|)';
     # page name only
     if(m!^($page_rx)$!o) {
         $page = $1;
@@ -321,6 +321,7 @@ sub parse {
     elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$!o) {
         ($alttext, $page, $node) = ($1, $2, $3);
         $type = 'section';
+        $quoted = 1; #... therefore | and / are allowed
     }
     # alttext and page
     elsif(m!^(.*?)\s*[|]\s*($page_rx)$!o) {
@@ -331,11 +332,13 @@ sub parse {
     elsif(m!^(.*?)\s*[|]\s*(?:/\s*|)"(.+)"$!) {
         ($alttext, $node) = ($1,$2);
         $type = 'section';
+        $quoted = 1;
     }
     # page and "section"
     elsif(m!^($page_rx)\s*/\s*"(.+)"$!o) {
         ($page, $node) = ($1, $2);
         $type = 'section';
+        $quoted = 1;
     }
     # page and item
     elsif(m!^($page_rx)\s*/\s*(.+)$!o) {
@@ -346,6 +349,7 @@ sub parse {
     elsif(m!^/?"(.+)"$!) {
         $node = $1;
         $type = 'section';
+        $quoted = 1;
     }
     # only item
     elsif(m!^\s*/(.+)$!) {
@@ -392,7 +396,7 @@ sub parse {
     if($page =~ /[(]\w*[)]$/) {
         $self->warning("(section) in '$page' deprecated");
     }
-    if($node =~ m:[|/]:) {
+    if(!$quoted && $node =~ m:[|/]:) {
         $self->warning("node '$node' contains non-escaped | or /");
     }
     if($alttext =~ m:[|/]:) {
@@ -422,11 +426,9 @@ sub _construct_text {
         $self->{_text} = $section;
     }
     else {
-        $self->{_text} = (!$section ? '' : 
-            $type eq 'item' ? "the $section entry" :
-                "the section on $section" ) .
-            ($page ? ($section ? ' in ':'') . "the $page$page_ext manpage" :
-                ' elsewhere in this document');
+        $self->{_text} = ($section || '') .
+            (($page && $section) ? ' in ' : '') .
+            "$page$page_ext";
     }
     # for being marked up later
     # use the non-standard markers P<> and Q<>, so that the resulting
@@ -439,11 +441,8 @@ sub _construct_text {
         $self->{_markup} = "Q<$section>";
     }
     else {
-        $self->{_markup} = (!$section ? '' : 
-            $type eq 'item' ? "the Q<$section> entry" :
-                "the section on Q<$section>" ) .
-            ($page ? ($section ? ' in ':'') . "the P<$page>$page_ext manpage" :
-                ' elsewhere in this document');
+        $self->{_markup} = (!$section ? '' : "Q<$section>") .
+            ($page ? ($section ? ' in ':'') . "P<$page>$page_ext" : '');
     }
 }
 
@@ -469,10 +468,10 @@ but without markers (read only). Depending on the link type this is one of
 the following alternatives (the + and * denote the portions of the text
 that are marked up):
 
-  the +perl+ manpage
-  the *$|* entry in the +perlvar+ manpage
-  the section on *OPTIONS* in the +perldoc+ manpage
-  the section on *DESCRIPTION* elsewhere in this document
+  +perl+                    L<perl>
+  *$|* in +perlvar+         L<perlvar/$|>
+  *OPTIONS* in +perldoc+    L<perldoc/"OPTIONS">
+  *DESCRIPTION*             L<"DESCRIPTION">
 
 =cut
 
diff --git a/lib/Pod/Usage.pm b/lib/Pod/Usage.pm
index 9898a97c00..771cff451c 100644
--- a/lib/Pod/Usage.pm
+++ b/lib/Pod/Usage.pm
@@ -506,7 +506,7 @@ sub pod2usage {
              and  $opts{"-output"} == \*STDOUT )
     {
        ## spit out the entire PODs. Might as well invoke perldoc
-       my $progpath = File::Spec->catfile($Config{scriptdir}, "perldoc");
+       my $progpath = File::Spec->catfile($Config{bin}, "perldoc");
        system($progpath, $opts{"-input"});
     }
     else {
diff --git a/lib/Pod/t/latex.t b/lib/Pod/t/latex.t
index dd3323b81d..b35e864c42 100644
--- a/lib/Pod/t/latex.t
+++ b/lib/Pod/t/latex.t
@@ -142,11 +142,11 @@ it refers to \texttt{Pod::LaTeX}: \textsf{test}.
 
 
 
-Standard link: the \emph{Pod::LaTeX} manpage.
+Standard link: \emph{Pod::LaTeX}.
 
 
 
-Now refer to an external section: the section on \textsf{sec} in the \emph{Pod::LaTeX} manpage
+Now refer to an external section: \textsf{sec} in \emph{Pod::LaTeX}
 
 \section{Lists\label{Lists}\index{Lists}}
 
diff --git a/lib/Pod/t/utils.t b/lib/Pod/t/utils.t
index 202ffd9510..4a1b8a14b9 100644
--- a/lib/Pod/t/utils.t
+++ b/lib/Pod/t/utils.t
@@ -27,11 +27,11 @@ my @links = qw{
 };
 
 my @results = (
-	       "the P<name> manpage",
-	       "the Q<ident> entry in the P<name> manpage",
-	       "the section on Q<sec> in the P<name> manpage",
-	       "the section on Q<sec> elsewhere in this document",
-	       "the section on Q<sec> elsewhere in this document",
+	       "P<name>",
+	       "Q<ident> in P<name>",
+	       "Q<sec> in P<name>",
+	       "Q<sec>",
+	       "Q<sec>",
 	       "Q<http://www.perl.org/>",
 	       "Q<text>",
 	       "Q<text>",