Update to Pod::Parser 1.17, from Brad Appleton.

p4raw-id: //depot/perl@6578

25 files changed, 613 insertions, 275 deletions

diff --git a/lib/Pod/Checker.pm b/lib/Pod/Checker.pm
index ae32677db1..37ed68f873 100644
--- a/lib/Pod/Checker.pm
+++ b/lib/Pod/Checker.pm
@@ -10,7 +10,7 @@
 package Pod::Checker;
 
 use vars qw($VERSION);
-$VERSION = 1.098;  ## Current version of this package
+$VERSION = 1.2;  ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 use Pod::ParseUtils; ## for hyperlinks and lists
@@ -44,7 +44,8 @@ This function can take a hash of options:
 
 =item B<-warnings> =E<gt> I<val>
 
-Turn warnings on/off. See L<"Warnings">.
+Turn warnings on/off. I<val> is usually 1 for on, but higher values
+trigger additional warnings. See L<"Warnings">.
 
 =back
 
@@ -212,11 +213,15 @@ There is some whitespace on a seemingly empty line. POD is very sensitive
 to such things, so this is flagged. B<vi> users switch on the B<list>
 option to avoid this problem.
 
+=begin _disabled_
+
 =item * file does not start with =head
 
 The file starts with a different POD directive than head.
 This is most probably something you do not want.
 
+=end _disabled_
+
 =item * No numeric argument for =over
 
 The C<=over> command is supposed to have a numeric argument (the
@@ -243,7 +248,8 @@ type of the I<first> C<=item> determines the type of the list.
 
 Angle brackets not written as C<E<lt>ltE<gt>> and C<E<lt>gtE<gt>>
 can potentially cause errors as they could be misinterpreted as
-markup commands.
+markup commands. This is only printed when the -warnings level is
+greater than 1.
 
 =item * Unknown entity
 
@@ -273,11 +279,41 @@ 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 * Hyperlinks
+=back
+
+=head2 Hyperlinks
+
+There are some warnings wrt. malformed hyperlinks.
+
+=over 4
+
+=item * collapsing newlines to blanks
+
+A hyperlink LE<lt>...E<gt> spans more than one line. This may indicate
+and error.
 
-There are some warnings wrt. hyperlinks:
-Leading/trailing whitespace, newlines in hyperlinks,
-brackets C<()>.
+=item * ignoring leading/trailing whitespace in link
+
+There is whitespace at the beginning or the end of the contents of 
+LE<lt>...E<gt>.
+
+=item * (section) in '$page' deprecated
+
+There is a section detected in the page name of LE<lt>...E<gt>, e.g.
+C<LE<gt>passwd(2)E<gt>>. POD hyperlinks may point to POD documents only.
+Please write C<CE<lt>passwd(2)E<gt>> instead. Some formatters are able
+to expand this to appropriate code. For links to (builtin) functions,
+please say C<LE<lt>perlfunc/mkdirE<gt>>, without ().
+
+=item * alternative text/node '%s' contains non-escaped | or /
+
+The characters C<|> and C</> are special in the LE<lt>...E<gt> context.
+Although the hyperlink parser does its best to determine which "/" is
+text and which is a delimiter in case of doubt, one ought to escape
+these literal characters like this:
+
+  /     E<sol>
+  |     E<verbar>
 
 =back
 
@@ -307,7 +343,6 @@ use strict;
 use Carp;
 use Exporter;
 use Pod::Parser;
-require VMS::Filespec if $^O eq 'VMS';
 
 use vars qw(@ISA @EXPORT);
 @ISA = qw(Pod::Parser);
@@ -471,7 +506,6 @@ sub podchecker( $ ; $ % ) {
 
     ## Now create a pod checker
     my $checker = new Pod::Checker(%options);
-    $checker->parseopts(-process_cut_cmd => 1, -warnings => 1);
 
     ## Now check the pod document for errors
     $checker->parse_from_file($infile, $outfile);
@@ -486,6 +520,27 @@ sub podchecker( $ ; $ % ) {
 ## Method definitions begin here
 ##-------------------------------
 
+##################################
+
+=over 4
+
+=item C<Pod::Checker-E<gt>new( %options )>
+
+Return a reference to a new Pod::Checker object that inherits from
+Pod::Parser and is used for calling the required methods later. The
+following options are recognized:
+
+C<-warnings =E<gt> num>
+  Print warnings if C<num> is true. The higher the value of C<num>,
+the more warnings are printed. Currently there are only levels 1 and 2.
+
+C<-quiet =E<gt> num>
+  If C<num> is true, do not print any errors/warnings. This is useful
+when Pod::Checker is used to munge POD code into plain text from within
+POD formatters.
+
+=cut
+
 ## sub new {
 ##     my $this = shift;
 ##     my $class = ref($this) || $this;
@@ -501,7 +556,9 @@ 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->errorsub('poderror'); # set the error handling subroutine
+    $self->{-quiet} ||= 0;
+    # set the error handling subroutine
+    $self->errorsub($self->{-quiet} ? sub { 1; } : 'poderror');
     $self->{_commands} = 0; # total number of POD commands encountered
     $self->{_list_stack} = []; # stack for nested lists
     $self->{_have_begin} = ''; # stores =begin
@@ -511,12 +568,11 @@ sub initialize {
     # print warnings?
     $self->{-warnings} = 1 unless(defined $self->{-warnings});
     $self->{_current_head1} = ''; # the current =head1 block
+    $self->parseopts(-process_cut_cmd => 1, -warnings => $self->{-warnings});
 }
 
 ##################################
 
-=over 4
-
 =item C<$checker-E<gt>poderror( @args )>
 
 =item C<$checker-E<gt>poderror( {%opts}, @args )>
@@ -547,7 +603,6 @@ The error level, should be 'WARNING' or 'ERROR'.
 sub poderror {
     my $self = shift;
     my %opts = (ref $_[0]) ? %{shift()} : ();
-    $opts{-file} = VMS::Filespec::unixify($opts{-file}) if (exists($opts{-file}) && $^O eq 'VMS');
 
     ## Retrieve options
     chomp( my $msg  = ($opts{-msg} || "")."@_" );
@@ -562,7 +617,7 @@ sub poderror {
     ## Increment error count and print message "
     ++($self->{_NUM_ERRORS}) 
         if(!%opts || ($opts{-severity} && $opts{-severity} eq 'ERROR'));
-    my $out_fh = $self->output_handle();
+    my $out_fh = $self->output_handle() || \*STDERR;
     print $out_fh ($severity, $msg, $line, $file, "\n")
       if($self->{-warnings} || !%opts || $opts{-severity} ne 'WARNING');
 }
@@ -672,7 +727,6 @@ sub end_pod {
     ## print the number of errors found
     my $self   = shift;
     my $infile = $self->input_file();
-    $infile = VMS::Filespec::unixify($infile) if $^O eq 'VMS';
     my $out_fh = $self->output_handle();
 
     if(@{$self->{_list_stack}}) {
@@ -691,12 +745,15 @@ sub end_pod {
     my %nodes;
     foreach($self->node()) {
         $nodes{$_} = 1;
-        if(/^(\S+)\s+/) {
+        if(/^(\S+)\s+\S/) {
             # we have more than one word. Use the first as a node, too.
             # This is used heavily in perlfunc.pod
             $nodes{$1} ||= 2; # derived node
         }
     }
+    foreach($self->idx()) {
+        $nodes{$_} = 3; # index node
+    }
     foreach($self->hyperlink()) {
         my ($line,$link) = @$_;
         # _TODO_ what if there is a link to the page itself by the name,
@@ -746,14 +803,17 @@ sub command {
        $self->poderror({ -line => $line, -file => $file, -severity => 'ERROR',
                          -msg => "Unknown command '$cmd'" });
     }
-    else {
-        # found a valid command
-        if(!$self->{_commands}++ && $cmd !~ /^head/) {
-            $self->poderror({ -line => $line, -file => $file,
-                 -severity => 'WARNING', 
-                 -msg => "file does not start with =head" });
-        }
-        ## check syntax of particular command
+    else { # found a valid command
+        $self->{_commands}++; # delete this line if below is enabled again
+
+        ##### following check disabled due to strong request
+        #if(!$self->{_commands}++ && $cmd !~ /^head/) {
+        #    $self->poderror({ -line => $line, -file => $file,
+        #         -severity => 'WARNING', 
+        #         -msg => "file does not start with =head" });
+        #}
+
+        # check syntax of particular command
         if($cmd eq 'over') {
             # check for argument
             $arg = $self->interpolate_and_check($paragraph, $line,$file);
@@ -1005,12 +1065,13 @@ sub _check_ptree {
         unless(ref) {
             my $count;
             # count the unescaped angle brackets
+            # complain only when warning level is greater than 1
             my $i = $_;
             if($count = $i =~ tr/<>/<>/) {
                 $self->poderror({ -line => $line, -file => $file,
                      -severity => 'WARNING', 
                      -msg => "$count unescaped <> in paragraph" })
-                if($self->{-warnings});
+                if($self->{-warnings} && $self->{-warnings}>1);
             }
             $text .= $i;
             next;
diff --git a/lib/Pod/Find.pm b/lib/Pod/Find.pm
index 8de197b71d..fb0f6b8dd1 100644
--- a/lib/Pod/Find.pm
+++ b/lib/Pod/Find.pm
@@ -13,8 +13,9 @@
 package Pod::Find;
 
 use vars qw($VERSION);
-$VERSION = 0.12;   ## Current version of this package
-require  5.005;    ## requires this Perl version or later
+$VERSION = 0.21;   ## Current version of this package
+require  5.005;   ## requires this Perl version or later
+use Carp;
 
 #############################################################################
 
@@ -32,12 +33,38 @@ Pod::Find - find POD documents in directory trees
 
   print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n";
 
+  $location = pod_where( { -inc => 1 }, "Pod::Find" );
+
 =head1 DESCRIPTION
 
-B<Pod::Find> provides a function B<pod_find> that searches for POD
-documents in a given set of files and directories. It returns a hash
-with the file names as keys and the POD name as value. The POD name
-is derived from the file name and its position in the directory tree.
+B<Pod::Find> provides a set of functions to locate POD files.  Note that
+no function is exported by default to avoid pollution of your namespace,
+so be sure to specify them in the B<use> statement if you need them:
+
+  use Pod::Find qw(pod_find);
+
+=cut
+
+use strict;
+#use diagnostics;
+use Exporter;
+use File::Spec;
+use File::Find;
+use Cwd;
+
+use vars qw(@ISA @EXPORT_OK $VERSION);
+@ISA = qw(Exporter);
+@EXPORT_OK = qw(&pod_find &simplify_name &pod_where &contains_pod);
+
+# package global variables
+my $SIMPLIFY_RX;
+
+=head2 C<pod_find( { %opts } , @directories )>
+
+The function B<pod_find> searches for POD documents in a given set of
+files and/or directories. It returns a hash with the file names as keys
+and the POD name as value. The POD name is derived from the file name
+and its position in the directory tree.
 
 E.g. when searching in F<$HOME/perl5lib>, the file
 F<$HOME/perl5lib/MyModule.pm> would get the POD name I<MyModule>,
@@ -51,73 +78,39 @@ A warning is printed if more than one POD file with the same POD name
 is found, e.g. F<CPAN.pm> in different directories. This usually
 indicates duplicate occurrences of modules in the I<@INC> search path.
 
-The function B<simplify_name> is equivalent to B<basename>, but also
-strips Perl-like extensions (.pm, .pl, .pod) and extensions like
-F<.bat>, F<.cmd> on Win32 and OS/2, respectively.
-
-Note that neither B<pod_find> nor B<simplify_name> are exported by
-default so be sure to specify them in the B<use> statement if you need
-them:
-
-  use Pod::Find qw(pod_find simplify_name);
-
-=head1 OPTIONS
-
-The first argument for B<pod_find> may be a hash reference with options.
-The rest are either directories that are searched recursively or files.
-The POD names of files are the plain basenames with any Perl-like extension
-(.pm, .pl, .pod) stripped.
+B<OPTIONS> The first argument for B<pod_find> may be a hash reference
+with options. The rest are either directories that are searched
+recursively or files.  The POD names of files are the plain basenames
+with any Perl-like extension (.pm, .pl, .pod) stripped.
 
 =over 4
 
-=item B<-verbose>
+=item C<-verbose =E<gt> 1>
 
 Print progress information while scanning.
 
-=item B<-perl>
+=item C<-perl =E<gt> 1>
 
 Apply Perl-specific heuristics to find the correct PODs. This includes
 stripping Perl-like extensions, omitting subdirectories that are numeric
 but do I<not> match the current Perl interpreter's version id, suppressing
 F<site_perl> as a module hierarchy name etc.
 
-=item B<-script>
+=item C<-script =E<gt> 1>
 
 Search for PODs in the current Perl interpreter's installation 
 B<scriptdir>. This is taken from the local L<Config|Config> module.
 
-=item B<-inc>
+=item C<-inc =E<gt> 1>
 
 Search for PODs in the current Perl interpreter's I<@INC> paths. This
-automatically considers paths specified in the C<PERL5LIB> environment.
+automatically considers paths specified in the C<PERL5LIB> environment
+as this is prepended to I<@INC> by the Perl interpreter itself.
 
 =back
 
-=head1 AUTHOR
-
-Marek Rouchal E<lt>marek@saftsack.fs.uni-bayreuth.deE<gt>,
-heavily borrowing code from Nick Ing-Simmons' PodToHtml.
-
-=head1 SEE ALSO
-
-L<Pod::Parser>, L<Pod::Checker>
-
 =cut
 
-use strict;
-#use diagnostics;
-use Exporter;
-use File::Spec;
-use File::Find;
-use Cwd;
-
-use vars qw(@ISA @EXPORT_OK $VERSION);
-@ISA = qw(Exporter);
-@EXPORT_OK = qw(&pod_find &simplify_name);
-
-# package global variables
-my $SIMPLIFY_RX;
-
 # return a hash of the POD files found
 # first argument may be a hashref (options),
 # rest is a list of directories to search recursively
@@ -222,27 +215,14 @@ sub _check_and_extract_name {
 
     # check extension or executable flag
     # this involves testing the .bat extension on Win32!
-    unless($file =~ /\.(pod|pm|plx?)\z/i || (-f $file && -x _ && -T _)) {
-        return undef;
+    unless(-f $file && -T _ && ($file =~ /\.(pod|pm|plx?)\z/i || -x _ )) {
+      return undef;
     }
 
-    # check for one line of POD
-    unless(open(POD,"<$file")) {
-        warn "Error: $file is unreadable: $!\n";
-        return undef;
-    }
-    local $/ = undef;
-    my $pod = <POD>;
-    close(POD);
-    unless($pod =~ /\n=(head\d|pod|over|item)\b/) {
-        warn "No POD in $file, skipping.\n"
-            if($verbose);
-        return;
-    }
-    undef $pod;
+    return undef unless contains_pod($file,$verbose);
 
     # strip non-significant path components
-    # _TODO_ what happens on e.g. Win32?
+    # TODO what happens on e.g. Win32?
     my $name = $file;
     if(defined $root_rx) {
         $name =~ s!$root_rx!!s;
@@ -256,6 +236,14 @@ sub _check_and_extract_name {
     $name;
 }
 
+=head2 C<simplify_name( $str )>
+
+The function B<simplify_name> is equivalent to B<basename>, but also
+strips Perl-like extensions (.pm, .pl, .pod) and extensions like
+F<.bat>, F<.cmd> on Win32 and OS/2, respectively.
+
+=cut
+
 # basic simplification of the POD name:
 # basename & strip extension
 sub simplify_name {
@@ -274,5 +262,180 @@ sub _simplify {
     $_[0] =~ s/\.(bat|exe|cmd)\z//i if($^O =~ /win|os2/i);
 }
 
+# contribution from Tim Jenness <t.jenness@jach.hawaii.edu>
+
+=head2 C<pod_where( { %opts }, $pod )>
+
+Returns the location of a pod document given a search directory
+and a module (e.g. C<File::Find>) or script (e.g. C<perldoc>) name.
+
+Options:
+
+=over 4
+
+=item C<-inc =E<gt> 1>
+
+Search @INC for the pod and also the C<scriptdir> defined in the
+L<Config|Config> module.
+
+=item C<-dirs =E<gt> [ $dir1, $dir2, ... ]>
+
+Reference to an array of search directories. These are searched in order
+before looking in C<@INC> (if B<-inc>). Current directory is used if
+none are specified.
+
+=item C<-verbose =E<gt> 1>
+
+List directories as they are searched
+
+=back
+
+Returns the full path of the first occurence to the file.
+Package names (eg 'A::B') are automatically converted to directory
+names in the selected directory. (eg on unix 'A::B' is converted to
+'A/B'). Additionally, '.pm', '.pl' and '.pod' are appended to the
+search automatically if required.
+
+A subdirectory F<pod/> is also checked if it exists in any of the given
+search directories. This ensures that e.g. L<perlfunc|perlfunc> is
+found.
+
+It is assumed that if a module name is supplied, that that name
+matches the file name. Pods are not opened to check for the 'NAME'
+entry.
+
+A check is made to make sure that the file that is found does 
+contain some pod documentation.
+
+=cut
+
+sub pod_where {
+
+  # default options
+  my %options = (
+         '-inc' => 0,
+         '-verbose' => 0,
+         '-dirs' => [ '.' ],
+        );
+
+  # Check for an options hash as first argument
+  if (defined $_[0] && ref($_[0]) eq 'HASH') {
+    my $opt = shift;
+
+    # Merge default options with supplied options
+    %options = (%options, %$opt);
+  }
+
+  # Check usage
+  carp 'Usage: pod_where({options}, $pod)' unless (scalar(@_));
+
+  # Read argument
+  my $pod = shift;
+
+  # Split on :: and then join the name together using File::Spec
+  my @parts = split (/::/, $pod);
+
+  # Get full directory list
+  my @search_dirs = @{ $options{'-dirs'} };
+
+  if ($options{'-inc'}) {
+
+    require Config;
+
+    # Add @INC
+    push (@search_dirs, @INC) if $options{'-inc'};
+
+    # Add location of pod documentation for perl man pages (eg perlfunc)
+    # This is a pod directory in the private install tree
+    #my $perlpoddir = File::Spec->catdir($Config::Config{'installprivlib'},
+    #					'pod');
+    #push (@search_dirs, $perlpoddir)
+    #  if -d $perlpoddir;
+
+    # Add location of binaries such as pod2text
+    push (@search_dirs, $Config::Config{'scriptdir'})
+      if -d $Config::Config{'scriptdir'};
+  }
+
+  # Loop over directories
+  Dir: foreach my $dir ( @search_dirs ) {
+
+    # Don't bother if cant find the directory
+    if (-d $dir) {
+      warn "Looking in directory $dir\n" 
+        if $options{'-verbose'};
+
+      # Now concatenate this directory with the pod we are searching for
+      my $fullname = File::Spec->catfile($dir, @parts);
+      warn "Filename is now $fullname\n"
+        if $options{'-verbose'};
+
+      # Loop over possible extensions
+      foreach my $ext ('', '.pod', '.pm', '.pl') {
+        my $fullext = $fullname . $ext;
+        if (-f $fullext && 
+         contains_pod($fullext, $options{'-verbose'}) ) {
+          warn "FOUND: $fullext\n" if $options{'-verbose'};
+          return $fullext;
+        }
+      }
+    } else {
+      warn "Directory $dir does not exist\n"
+        if $options{'-verbose'};
+      next Dir;
+    }
+    if(-d File::Spec->catdir($dir,'pod')) {
+      $dir = File::Spec->catdir($dir,'pod');
+      redo Dir;
+    }
+  }
+  # No match;
+  return undef;
+}
+
+=head2 C<contains_pod( $file , $verbose )>
+
+Returns true if the supplied filename (not POD module) contains some pod
+information.
+
+=cut
+
+sub contains_pod {
+  my $file = shift;
+  my $verbose = 0;
+  $verbose = shift if @_;
+
+  # check for one line of POD
+  unless(open(POD,"<$file")) {
+    warn "Error: $file is unreadable: $!\n";
+    return undef;
+  }
+  
+  local $/ = undef;
+  my $pod = <POD>;
+  close(POD) || die "Error closing $file: $!\n";
+  unless($pod =~ /\n=(head\d|pod|over|item)\b/s) {
+    warn "No POD in $file, skipping.\n"
+      if($verbose);
+    return 0;
+  }
+
+  return 1;
+}
+
+=head1 AUTHOR
+
+Marek Rouchal E<lt>marek@saftsack.fs.uni-bayreuth.deE<gt>,
+heavily borrowing code from Nick Ing-Simmons' PodToHtml.
+
+Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt> provided
+C<pod_where> and C<contains_pod>.
+
+=head1 SEE ALSO
+
+L<Pod::Parser>, L<Pod::Checker>, L<perldoc>
+
+=cut
+
 1;
 
diff --git a/lib/Pod/InputObjects.pm b/lib/Pod/InputObjects.pm
index 6bc329b0cf..9c89413222 100644
--- a/lib/Pod/InputObjects.pm
+++ b/lib/Pod/InputObjects.pm
@@ -11,7 +11,7 @@
 package Pod::InputObjects;
 
 use vars qw($VERSION);
-$VERSION = 1.12;  ## Current version of this package
+$VERSION = 1.13;  ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 #############################################################################
@@ -42,7 +42,7 @@ are defined:
 
 =begin __PRIVATE__
 
-=item B<Pod::InputSource>
+=item package B<Pod::InputSource>
 
 An object corresponding to a source of POD input text. It is mostly a
 wrapper around a filehandle or C<IO::Handle>-type object (or anything
@@ -51,23 +51,23 @@ additional information relevant to the parsing of PODs.
 
 =end __PRIVATE__
 
-=item B<Pod::Paragraph>
+=item package B<Pod::Paragraph>
 
 An object corresponding to a paragraph of POD input text. It may be a
 plain paragraph, a verbatim paragraph, or a command paragraph (see
 L<perlpod>).
 
-=item B<Pod::InteriorSequence>
+=item package B<Pod::InteriorSequence>
 
 An object corresponding to an interior sequence command from the POD
 input text (see L<perlpod>).
 
-=item B<Pod::ParseTree>
+=item package B<Pod::ParseTree>
 
 An object corresponding to a tree of parsed POD text. Each "node" in
 a parse-tree (or I<ptree>) is either a text-string or a reference to
 a B<Pod::InteriorSequence> object. The nodes appear in the parse-tree
-in they order in which they were parsed from  left-to-right.
+in the order in which they were parsed from left-to-right.
 
 =back
 
@@ -232,7 +232,7 @@ It has the following methods/attributes:
 
 ##---------------------------------------------------------------------------
 
-=head2 B<new()>
+=head2 Pod::Paragraph-E<gt>B<new()>
 
         my $pod_para1 = Pod::Paragraph->new(-text => $text);
         my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
@@ -284,7 +284,7 @@ sub new {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<cmd_name()>
+=head2 $pod_para-E<gt>B<cmd_name()>
 
         my $para_cmd = $pod_para->cmd_name();
 
@@ -303,7 +303,7 @@ sub cmd_name {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<text()>
+=head2 $pod_para-E<gt>B<text()>
 
         my $para_text = $pod_para->text();
 
@@ -318,7 +318,7 @@ sub text {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<raw_text()>
+=head2 $pod_para-E<gt>B<raw_text()>
 
         my $raw_pod_para = $pod_para->raw_text();
 
@@ -335,7 +335,7 @@ sub raw_text {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<cmd_prefix()>
+=head2 $pod_para-E<gt>B<cmd_prefix()>
 
         my $prefix = $pod_para->cmd_prefix();
 
@@ -351,7 +351,7 @@ sub cmd_prefix {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<cmd_separator()>
+=head2 $pod_para-E<gt>B<cmd_separator()>
 
         my $separator = $pod_para->cmd_separator();
 
@@ -367,7 +367,7 @@ sub cmd_separator {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<parse_tree()>
+=head2 $pod_para-E<gt>B<parse_tree()>
 
         my $ptree = $pod_parser->parse_text( $pod_para->text() );
         $pod_para->parse_tree( $ptree );
@@ -387,13 +387,13 @@ sub parse_tree {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<file_line()>
+=head2 $pod_para-E<gt>B<file_line()>
 
         my ($filename, $line_number) = $pod_para->file_line();
         my $position = $pod_para->file_line();
 
 Returns the current filename and line number for the paragraph
-object.  If called in a list context, it returns a list of two
+object.  If called in an array context, it returns a list of two
 elements: first the filename, then the line number. If called in
 a scalar context, it returns a string containing the filename, followed
 by a colon (':'), followed by the line number.
@@ -423,7 +423,7 @@ It has the following methods/attributes:
 
 ##---------------------------------------------------------------------------
 
-=head2 B<new()>
+=head2 Pod::InteriorSequence-E<gt>B<new()>
 
         my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
                                                   -ldelim => $delimiter);
@@ -497,7 +497,7 @@ sub new {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<cmd_name()>
+=head2 $pod_seq-E<gt>B<cmd_name()>
 
         my $seq_cmd = $pod_seq->cmd_name();
 
@@ -546,7 +546,7 @@ sub _unset_child2parent_links {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<prepend()>
+=head2 $pod_seq-E<gt>B<prepend()>
 
         $pod_seq->prepend($text);
         $pod_seq1->prepend($pod_seq2);
@@ -565,7 +565,7 @@ sub prepend {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<append()>
+=head2 $pod_seq-E<gt>B<append()>
 
         $pod_seq->append($text);
         $pod_seq1->append($pod_seq2);
@@ -584,7 +584,7 @@ sub append {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<nested()>
+=head2 $pod_seq-E<gt>B<nested()>
 
         $outer_seq = $pod_seq->nested || print "not nested";
 
@@ -602,7 +602,7 @@ sub nested {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<raw_text()>
+=head2 $pod_seq-E<gt>B<raw_text()>
 
         my $seq_raw_text = $pod_seq->raw_text();
 
@@ -623,7 +623,7 @@ sub raw_text {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<left_delimiter()>
+=head2 $pod_seq-E<gt>B<left_delimiter()>
 
         my $ldelim = $pod_seq->left_delimiter();
 
@@ -642,7 +642,7 @@ sub left_delimiter {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<right_delimiter()>
+=head2 $pod_seq-E<gt>B<right_delimiter()>
 
 The rightmost delimiter beginning the argument text to the interior
 sequence (should be ">").
@@ -659,7 +659,7 @@ sub right_delimiter {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<parse_tree()>
+=head2 $pod_seq-E<gt>B<parse_tree()>
 
         my $ptree = $pod_parser->parse_text($paragraph_text);
         $pod_seq->parse_tree( $ptree );
@@ -680,13 +680,13 @@ sub parse_tree {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<file_line()>
+=head2 $pod_seq-E<gt>B<file_line()>
 
         my ($filename, $line_number) = $pod_seq->file_line();
         my $position = $pod_seq->file_line();
 
 Returns the current filename and line number for the interior sequence
-object.  If called in a list context, it returns a list of two
+object.  If called in an array context, it returns a list of two
 elements: first the filename, then the line number. If called in
 a scalar context, it returns a string containing the filename, followed
 by a colon (':'), followed by the line number.
@@ -701,7 +701,7 @@ sub file_line {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<DESTROY()>
+=head2 Pod::InteriorSequence::B<DESTROY()>
 
 This method performs any necessary cleanup for the interior-sequence.
 If you override this method then it is B<imperative> that you invoke
@@ -738,7 +738,7 @@ itself contain a parse-tree (since interior sequences may be nested).
 
 ##---------------------------------------------------------------------------
 
-=head2 B<new()>
+=head2 Pod::ParseTree-E<gt>B<new()>
 
         my $ptree1 = Pod::ParseTree->new;
         my $ptree2 = new Pod::ParseTree;
@@ -766,7 +766,7 @@ sub new {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<top()>
+=head2 $ptree-E<gt>B<top()>
 
         my $top_node = $ptree->top();
         $ptree->top( $top_node );
@@ -794,7 +794,7 @@ sub top {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<children()>
+=head2 $ptree-E<gt>B<children()>
 
 This method gets/sets the children of the top node in the parse-tree.
 If no arguments are given, it returns the list (array) of children
@@ -814,7 +814,7 @@ sub children {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<prepend()>
+=head2 $ptree-E<gt>B<prepend()>
 
 This method prepends the given text or parse-tree to the current parse-tree.
 If the first item on the parse-tree is text and the argument is also text,
@@ -842,7 +842,7 @@ sub prepend {
 
 ##---------------------------------------------------------------------------
 
-=head2 B<append()>
+=head2 $ptree-E<gt>B<append()>
 
 This method appends the given text or parse-tree to the current parse-tree.
 If the last item on the parse-tree is text and the argument is also text,
@@ -866,7 +866,7 @@ sub append {
    }
 }
 
-=head2 B<raw_text()>
+=head2 $ptree-E<gt>B<raw_text()>
 
         my $ptree_raw_text = $ptree->raw_text();
 
@@ -902,7 +902,7 @@ sub _set_child2parent_links {
     ## nothing to do, Pod::ParseTrees cant have parent pointers
 }
 
-=head2 B<DESTROY()>
+=head2 Pod::ParseTree::B<DESTROY()>
 
 This method performs any necessary cleanup for the parse-tree.
 If you override this method then it is B<imperative>
diff --git a/lib/Pod/ParseUtils.pm b/lib/Pod/ParseUtils.pm
index 2cb8cdcd3b..6703a7fbc8 100644
--- a/lib/Pod/ParseUtils.pm
+++ b/lib/Pod/ParseUtils.pm
@@ -10,7 +10,7 @@
 package Pod::ParseUtils;
 
 use vars qw($VERSION);
-$VERSION = 0.2;    ## Current version of this package
+$VERSION = 0.22;   ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 =head1 NAME
@@ -49,7 +49,7 @@ The following methods are available:
 
 =over 4
 
-=item new()
+=item Pod::List-E<gt>new()
 
 Create a new list object. Properties may be specified through a hash
 reference like this:
@@ -79,7 +79,7 @@ sub initialize {
     $self->{-type} ||= '';
 }
 
-=item file()
+=item $list-E<gt>file()
 
 Without argument, retrieves the file name the list is in. This must
 have been set before by either specifying B<-file> in the B<new()>
@@ -92,7 +92,7 @@ sub file {
    return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
 }
 
-=item start()
+=item $list-E<gt>start()
 
 Without argument, retrieves the line number where the list started.
 This must have been set before by either specifying B<-start> in the
@@ -106,7 +106,7 @@ sub start {
    return (@_ > 1) ? ($_[0]->{-start} = $_[1]) : $_[0]->{-start};
 }
 
-=item indent()
+=item $list-E<gt>indent()
 
 Without argument, retrieves the indent level of the list as specified
 in C<=over n>. This must have been set before by either specifying
@@ -120,7 +120,7 @@ sub indent {
    return (@_ > 1) ? ($_[0]->{-indent} = $_[1]) : $_[0]->{-indent};
 }
 
-=item type()
+=item $list-E<gt>type()
 
 Without argument, retrieves the list type, which can be an arbitrary value,
 e.g. C<OL>, C<UL>, ... when thinking the HTML way.
@@ -135,7 +135,7 @@ sub type {
    return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type};
 }
 
-=item rx()
+=item $list-E<gt>rx()
 
 Without argument, retrieves a regular expression for simplifying the 
 individual item strings once the list type has been determined. Usage:
@@ -152,7 +152,7 @@ sub rx {
    return (@_ > 1) ? ($_[0]->{-rx} = $_[1]) : $_[0]->{-rx};
 }
 
-=item item()
+=item $list-E<gt>item()
 
 Without argument, retrieves the array of the items in this list.
 The items may be represented by any scalar.
@@ -172,7 +172,7 @@ sub item {
     }
 }
 
-=item parent()
+=item $list-E<gt>parent()
 
 Without argument, retrieves information about the parent holding this
 list, which is represented as an arbitrary scalar.
@@ -188,7 +188,7 @@ sub parent {
    return (@_ > 1) ? ($_[0]->{-parent} = $_[1]) : $_[0]->{-parent};
 }
 
-=item tag()
+=item $list-E<gt>tag()
 
 Without argument, retrieves information about the list tag, which can be
 any scalar.
@@ -227,7 +227,7 @@ used to construct hyperlinks.
 
 =over 4
 
-=item new()
+=item Pod::Hyperlink-E<gt>new()
 
 The B<new()> method can either be passed a set of key/value pairs or a single
 scalar value, namely the contents of a C<LE<lt>...E<gt>> sequence. An object
@@ -269,10 +269,14 @@ sub initialize {
     $self->{_warnings} = [];
 }
 
-=item parse($string)
+=item $link-E<gt>parse($string)
 
 This method can be used to (re)parse a (new) hyperlink, i.e. the contents
 of a C<LE<lt>...E<gt>> sequence. The result is stored in the current object.
+Warnings are stored in the B<warnings> property.
+E.g. sections like C<LE<lt>open(2)E<gt>> are deprected, as they do not point
+to Perl documents. C<LE<lt>DBI::foo(3p)E<gt>> is wrong as well, the manpage
+section can simply be dropped.
 
 =cut
 
@@ -280,7 +284,7 @@ sub parse {
     my $self = shift;
     local($_) = $_[0];
     # syntax check the link and extract destination
-    my ($alttext,$page,$node,$type) = ('','','','');
+    my ($alttext,$page,$node,$type) = (undef,'','','');
 
     $self->{_warnings} = [];
 
@@ -308,25 +312,24 @@ 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...
-    # I would like the following better, here and below:
-    #if(m!^(\w+(?:::\w+)*)$!) {
-    my $page_rx = '[\w.]+(?:::[\w.]+)*';
+    my $page_rx = '[\w.]+(?:::[\w.]+)*(?:[(](?:\d\w*|)[)]|)';
+    # page name only
     if(m!^($page_rx)$!o) {
         $page = $1;
         $type = 'page';
     }
     # alttext, page and "section"
-    elsif(m!^(.+?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$!o) {
+    elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$!o) {
         ($alttext, $page, $node) = ($1, $2, $3);
         $type = 'section';
     }
     # alttext and page
-    elsif(m!^(.+?)\s*[|]\s*($page_rx)$!o) {
+    elsif(m!^(.*?)\s*[|]\s*($page_rx)$!o) {
         ($alttext, $page) = ($1, $2);
         $type = 'page';
     }
     # alttext and "section"
-    elsif(m!^(.+?)\s*[|]\s*(?:/\s*|)"(.+)"$!) {
+    elsif(m!^(.*?)\s*[|]\s*(?:/\s*|)"(.+)"$!) {
         ($alttext, $node) = ($1,$2);
         $type = 'section';
     }
@@ -356,16 +359,16 @@ sub parse {
         $type = 'hyperlink';
     }
     # alttext, page and item
-    elsif(m!^(.+?)\s*[|]\s*($page_rx)\s*/\s*(.+)$!o) {
+    elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*(.+)$!o) {
         ($alttext, $page, $node) = ($1, $2, $3);
         $type = 'item';
     }
     # alttext and item
-    elsif(m!^(.+?)\s*[|]\s*/(.+)$!) {
+    elsif(m!^(.*?)\s*[|]\s*/(.+)$!) {
         ($alttext, $node) = ($1,$2);
     }
     # nonstandard: alttext and hyperlink
-    elsif(m!^(.+?)\s*[|]\s*((?:http|ftp|mailto|news):.+)$!) {
+    elsif(m!^(.*?)\s*[|]\s*((?:http|ftp|mailto|news):.+)$!) {
         ($alttext, $node) = ($1,$2);
         $type = 'hyperlink';
     }
@@ -377,9 +380,19 @@ sub parse {
     # collapse whitespace in nodes
     $node =~ s/\s+/ /gs;
 
-    #if($page =~ /[(]\w*[)]$/) {
-    #    $self->warning("section in '$page' deprecated");
-    #}
+    # empty alternative text expands to node name
+    if(defined $alttext) {
+        if(!length($alttext)) {
+          $alttext = $node | $page;
+        }
+    }
+    else {
+        $alttext = '';
+    }
+
+    if($page =~ /[(]\w*[)]$/) {
+        $self->warning("(section) in '$page' deprecated");
+    }
     if($node =~ m:[|/]:) {
         $self->warning("node '$node' contains non-escaped | or /");
     }
@@ -435,7 +448,7 @@ sub _construct_text {
     }
 }
 
-=item markup($string)
+=item $link-E<gt>markup($string)
 
 Set/retrieve the textual value of the link. This string contains special
 markers C<PE<lt>E<gt>> and C<QE<lt>E<gt>> that should be expanded by the
@@ -450,7 +463,7 @@ sub markup {
     return (@_ > 1) ? ($_[0]->{_markup} = $_[1]) : $_[0]->{_markup};
 }
 
-=item text()
+=item $link-E<gt>text()
 
 This method returns the textual representation of the hyperlink as above,
 but without markers (read only). Depending on the link type this is one of
@@ -469,7 +482,7 @@ sub text {
     $_[0]->{_text};
 }
 
-=item warning()
+=item $link-E<gt>warning()
 
 After parsing, this method returns any warnings encountered during the
 parsing process.
@@ -486,7 +499,9 @@ sub warning {
     return @{$self->{_warnings}};
 }
 
-=item line(), file()
+=item $link-E<gt>file()
+
+=item $link-E<gt>line()
 
 Just simple slots for storing information about the line and the file
 the link was encountered in. Has to be filled in manually.
@@ -503,7 +518,7 @@ sub file {
     return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
 }
 
-=item page()
+=item $link-E<gt>page()
 
 This method sets or returns the POD page this link points to.
 
@@ -518,7 +533,7 @@ sub page {
     $_[0]->{-page};
 }
 
-=item node()
+=item $link-E<gt>node()
 
 As above, but the destination node text of the link.
 
@@ -533,7 +548,7 @@ sub node {
     $_[0]->{-node};
 }
 
-=item alttext()
+=item $link-E<gt>alttext()
 
 Sets or returns an alternative text specified in the link.
 
@@ -548,7 +563,7 @@ sub alttext {
     $_[0]->{-alttext};
 }
 
-=item type()
+=item $link-E<gt>type()
 
 The node type, either C<section> or C<item>. As an unofficial type,
 there is also C<hyperlink>, derived from e.g. C<LE<lt>http://perl.comE<gt>>
@@ -560,7 +575,7 @@ sub type {
     return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type};
 }
 
-=item link()
+=item $link-E<gt>link()
 
 Returns the link as contents of C<LE<lt>E<gt>>. Reciprocal to B<parse()>.
 
@@ -620,7 +635,7 @@ The following methods are available:
 
 =over 4
 
-=item new()
+=item Pod::Cache-E<gt>new()
 
 Create a new cache object. This object can hold an arbitrary number of
 POD documents of class Pod::Cache::Item.
@@ -635,7 +650,7 @@ sub new {
     return $self;
 }
 
-=item item()
+=item $cache-E<gt>item()
 
 Add a new item to the cache. Without arguments, this method returns a
 list of all cache elements.
@@ -654,7 +669,7 @@ sub item {
     }
 }
 
-=item find_page($name)
+=item $cache-E<gt>find_page($name)
 
 Look for a POD document named C<$name> in the cache. Returns the
 reference to the corresponding Pod::Cache::Item object or undef if
@@ -686,7 +701,7 @@ The following methods are available:
 
 =over 4
 
-=item new()
+=item Pod::Cache::Item-E<gt>new()
 
 Create a new object.
 
@@ -707,7 +722,7 @@ sub initialize {
     $self->{-nodes} = [] unless(defined $self->{-nodes});
 }
 
-=item page()
+=item $cacheitem-E<gt>page()
 
 Set/retrieve the POD document name (e.g. "Pod::Parser").
 
@@ -718,7 +733,7 @@ sub page {
    return (@_ > 1) ? ($_[0]->{-page} = $_[1]) : $_[0]->{-page};
 }
 
-=item description()
+=item $cacheitem-E<gt>description()
 
 Set/retrieve the POD short description as found in the C<=head1 NAME>
 section.
@@ -730,7 +745,7 @@ sub description {
    return (@_ > 1) ? ($_[0]->{-description} = $_[1]) : $_[0]->{-description};
 }
 
-=item path()
+=item $cacheitem-E<gt>path()
 
 Set/retrieve the POD file storage path.
 
@@ -741,7 +756,7 @@ sub path {
    return (@_ > 1) ? ($_[0]->{-path} = $_[1]) : $_[0]->{-path};
 }
 
-=item file()
+=item $cacheitem-E<gt>file()
 
 Set/retrieve the POD file name.
 
@@ -752,7 +767,7 @@ sub file {
    return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
 }
 
-=item nodes()
+=item $cacheitem-E<gt>nodes()
 
 Add a node (or a list of nodes) to the document's node list. Note that
 the order is kept, i.e. start with the first node and end with the last.
@@ -775,14 +790,12 @@ sub nodes {
     }
 }
 
-=item find_node($name)
+=item $cacheitem-E<gt>find_node($name)
 
 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.
 
-=back
-
 =cut
 
 sub find_node {
@@ -798,7 +811,7 @@ sub find_node {
     undef;
 }
 
-=item idx()
+=item $cacheitem-E<gt>idx()
 
 Add an index entry (or a list of them) to the document's index list. Note that
 the order is kept, i.e. start with the first node and end with the last.
@@ -807,6 +820,8 @@ same order the entries have been added.
 An index entry can be any scalar, but usually is a pair of string and
 unique id.
 
+=back
+
 =cut
 
 # The POD index entries
diff --git a/lib/Pod/Parser.pm b/lib/Pod/Parser.pm
index 48fc198ded..99615bcfb5 100644
--- a/lib/Pod/Parser.pm
+++ b/lib/Pod/Parser.pm
@@ -205,7 +205,6 @@ use strict;
 use Pod::InputObjects;
 use Carp;
 use Exporter;
-require VMS::Filespec if $^O eq 'VMS';
 BEGIN {
    if ($] < 5.6) {
       require Symbol;
@@ -848,7 +847,6 @@ sub parse_text {
     my $errorsub = (@seq_stack > 1) ? $self->errorsub() : undef;
     while (@seq_stack > 1) {
        ($cmd, $file, $line) = ($seq->name, $seq->file_line);
-       $file = VMS::Filespec::unixify($file) if $^O eq 'VMS';
        $ldelim  = $seq->ldelim;
        ($rdelim = $ldelim) =~ tr/</>/;
        $rdelim  =~ s/^(\S+)(\s*)$/$2$1/;
@@ -1081,10 +1079,9 @@ sub parse_from_filehandle {
                                      && (length $paragraph));
 
         ## Issue a warning about any non-empty blank lines
-        if (length($1) > 1 and $myOpts{'-warnings'} and ! $myData{_CUTTING}) {
+        if (length($1) > 0 and $myOpts{'-warnings'} and ! $myData{_CUTTING}) {
             my $errorsub = $self->errorsub();
             my $file = $self->input_file();
-            $file = VMS::Filespec::unixify($file) if $^O eq 'VMS';
             my $errmsg = "*** WARNING: line containing nothing but whitespace".
                          " in paragraph at line $nlines in file $file\n";
             (ref $errorsub) and &{$errorsub}($errmsg)
diff --git a/lib/Pod/Select.pm b/lib/Pod/Select.pm
index 5dd1595107..d86d823350 100644
--- a/lib/Pod/Select.pm
+++ b/lib/Pod/Select.pm
@@ -10,7 +10,7 @@
 package Pod::Select;
 
 use vars qw($VERSION);
-$VERSION = 1.12;  ## Current version of this package
+$VERSION = 1.13;  ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 #############################################################################
@@ -92,7 +92,7 @@ The formal syntax of a section specification is:
 
 =over 4
 
-=item
+=item *
 
 I<head1-title-regex>/I<head2-title-regex>/...
 
@@ -160,7 +160,7 @@ The formal syntax of a range specification is:
 
 =over 4
 
-=item
+=item *
 
 /I<start-range-regex>/[../I<end-range-regex>/]
 
diff --git a/lib/Pod/Usage.pm b/lib/Pod/Usage.pm
index 571588ebd2..56e91fc7d7 100644
--- a/lib/Pod/Usage.pm
+++ b/lib/Pod/Usage.pm
@@ -10,7 +10,7 @@
 package Pod::Usage;
 
 use vars qw($VERSION);
-$VERSION = 1.12;  ## Current version of this package
+$VERSION = 1.13;  ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 =head1 NAME
@@ -46,7 +46,7 @@ B<pod2usage> should be given either a single argument, or a list of
 arguments corresponding to an associative array (a "hash"). When a single
 argument is given, it should correspond to exactly one of the following:
 
-=over
+=over 4
 
 =item *
 
@@ -68,7 +68,7 @@ assumed to be a hash.  If a hash is supplied (either as a reference or
 as a list) it should contain one or more elements with the following
 keys:
 
-=over
+=over 4
 
 =item C<-message>
 
@@ -129,7 +129,7 @@ Unless they are explicitly specified, the default values for the exit
 status, verbose level, and output stream to use are determined as
 follows:
 
-=over
+=over 4
 
 =item *
 
@@ -159,7 +159,7 @@ Although the above may seem a bit confusing at first, it generally does
 "the right thing" in most situations.  This determination of the default
 values to use is based upon the following typical Unix conventions:
 
-=over
+=over 4
 
 =item *
 
@@ -211,7 +211,7 @@ convenient to use as an innocent looking error message handling function:
     ## Check for too many filenames
     pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);
 
-Some users however may feel that the above "economy of expression" is
+Some user's however may feel that the above "economy of expression" is
 not particularly readable nor consistent and may instead choose to do
 something more like the following:
 
diff --git a/pod/pod2usage.PL b/pod/pod2usage.PL
index e0f70b2ca4..1c1296a19f 100644
--- a/pod/pod2usage.PL
+++ b/pod/pod2usage.PL
@@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!';
 #############################################################################
 # pod2usage -- command to print usage messages from embedded pod docs
 #
-# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved.
+# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved.
 # This file is part of "PodParser". PodParser is free software;
 # you can redistribute it and/or modify it under the same terms
 # as Perl itself.
diff --git a/pod/podchecker.PL b/pod/podchecker.PL
index a7f96434ca..20d5e94c2e 100644
--- a/pod/podchecker.PL
+++ b/pod/podchecker.PL
@@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!';
 #############################################################################
 # podchecker -- command to invoke the podchecker function in Pod::Checker
 #
-# Copyright (c) 1998-1999 by Bradford Appleton. All rights reserved.
+# Copyright (c) 1998-2000 by Bradford Appleton. All rights reserved.
 # This file is part of "PodParser". PodParser is free software;
 # you can redistribute it and/or modify it under the same terms
 # as Perl itself.
@@ -70,7 +70,9 @@ Print the manual page and exit.
 
 =item B<-warnings> B<-nowarnings>
 
-Turn on/off printing of warnings.
+Turn on/off printing of warnings. Repeating B<-warnings> increases the
+warning level, i.e. more warnings are printed. Currently increasing to
+level two causes flagging of unescaped "E<lt>,E<gt>" characters.
 
 =item I<file>
 
@@ -85,6 +87,8 @@ syntax errors in the POD documentation and will print any errors
 it find to STDERR. At the end, it will print a status message
 indicating the number of errors found.
 
+Directories are ignored, an appropriate warning message is printed.
+
 B<podchecker> invokes the B<podchecker()> function exported by B<Pod::Checker>
 Please see L<Pod::Checker/podchecker()> for more details.
 
@@ -124,24 +128,34 @@ use Pod::Usage;
 use Getopt::Long;
 
 ## Define options
-my %options = (
-        "help"     => 0,
-        "man"      => 0,
-        "warnings" => 1,
-);
+my %options;
 
 ## Parse options
-GetOptions(\%options, "help", "man", "warnings!")  ||  pod2usage(2);
+GetOptions(\%options, qw(help man warnings+ nowarnings))  ||  pod2usage(2);
 pod2usage(1)  if ($options{help});
 pod2usage(-verbose => 2)  if ($options{man});
 
+if($options{nowarnings}) {
+  $options{warnings} = 0;
+}
+elsif(!defined $options{warnings}) {
+  $options{warnings} = 1; # default is warnings on
+}
+
 ## Dont default to STDIN if connected to a terminal
 pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
 
 ## Invoke podchecker()
 my $status = 0;
-@ARGV = ("<&STDIN") unless(@ARGV);
+@ARGV = qw(-) unless(@ARGV);
 for (@ARGV) {
+    if($_ eq '-') {
+      $_ = "<&STDIN";
+    }
+    elsif(-d) {
+      warn "podchecker: Warning: Ignoring directory '$_'\n";
+      next;
+    }
     my $s = podchecker($_, undef, '-warnings' => $options{warnings});
     if($s > 0) {
         # errors occurred
diff --git a/pod/podselect.PL b/pod/podselect.PL
index f2ba80a73b..b6b8c9b9e4 100644
--- a/pod/podselect.PL
+++ b/pod/podselect.PL
@@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!';
 #############################################################################
 # podselect -- command to invoke the podselect function in Pod::Select
 #
-# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved.
+# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved.
 # This file is part of "PodParser". PodParser is free software;
 # you can redistribute it and/or modify it under the same terms
 # as Perl itself.
diff --git a/t/pod/emptycmd.t b/t/pod/emptycmd.t
index d348a9d278..59e395ea04 100755
--- a/t/pod/emptycmd.t
+++ b/t/pod/emptycmd.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/for.t b/t/pod/for.t
index b8a6ec5c73..44af44f17d 100755
--- a/t/pod/for.t
+++ b/t/pod/for.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/headings.t b/t/pod/headings.t
index fc7b4b265b..78608d0fd9 100755
--- a/t/pod/headings.t
+++ b/t/pod/headings.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/include.t b/t/pod/include.t
index 6d0b7e34e5..4e73b78356 100755
--- a/t/pod/include.t
+++ b/t/pod/include.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/included.t b/t/pod/included.t
index 0e31a090fc..4f171c454b 100755
--- a/t/pod/included.t
+++ b/t/pod/included.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/lref.t b/t/pod/lref.t
index e367d6dd66..02e2c9e307 100755
--- a/t/pod/lref.t
+++ b/t/pod/lref.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/multiline_items.t b/t/pod/multiline_items.t
index 37e8d53069..0fe410a4e6 100755
--- a/t/pod/multiline_items.t
+++ b/t/pod/multiline_items.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/nested_items.t b/t/pod/nested_items.t
index 9c098018d1..c8e9b22427 100755
--- a/t/pod/nested_items.t
+++ b/t/pod/nested_items.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/nested_seqs.t b/t/pod/nested_seqs.t
index 6a5405bf47..8559f1f25f 100755
--- a/t/pod/nested_seqs.t
+++ b/t/pod/nested_seqs.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/oneline_cmds.t b/t/pod/oneline_cmds.t
index 3081ef4dc3..28bd1d09e5 100755
--- a/t/pod/oneline_cmds.t
+++ b/t/pod/oneline_cmds.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/pod2usage.t b/t/pod/pod2usage.t
index bceeeefce8..cf2c31b83f 100755
--- a/t/pod/pod2usage.t
+++ b/t/pod/pod2usage.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/poderrs.t b/t/pod/poderrs.t
index ec632c2538..8db7d4351c 100755
--- a/t/pod/poderrs.t
+++ b/t/pod/poderrs.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testpchk.pl";
    import TestPodChecker;
 }
@@ -59,7 +59,7 @@ The above blank line contains tabs and spaces only
 
 =over 4
 
-=item oops
+=item aaps
 
 =head2 end without begin
 
@@ -75,6 +75,20 @@ The above blank line contains tabs and spaces only
 
 =end
 
+second one results in end w/o begin
+
+=head2 begin w/o formatter
+
+=begin
+
+=end
+
+=head2 for w/o formatter
+
+=for
+
+something...
+
 =head2 Nested sequences of the same type
 
 C<code I<italic C<code again!>>>
@@ -84,6 +98,9 @@ C<code I<italic C<code again!>>>
 E<alea iacta est>
 E<C<auml>>
 E<abcI<bla>>
+E<0x100>
+E<07777>
+E<300>
 
 =head2 Unresolved internal links
 
@@ -96,12 +113,15 @@ L</OoPs>
 L<abc
 def>
 L<>
+L<   aha>
+L<oho   >
 L<"Warnings"> this one is ok
+L</unescaped> ok too, this POD has an X of the same name
 
 =head2 Warnings
 
 L<passwd(5)>
-L<   some text|page/"section"   >
+L<some text with / in it|perlvar/$|> should give warnings as hell
 
 =over 4
 
@@ -109,17 +129,70 @@ L<   some text|page/"section"   >
 
 =back 200
 
+the 200 is evil
+
 =begin html
 
 What?
 
 =end xml
 
+X<unescaped>see these unescaped < and > in the text?
+
+=head2 Misc
+
+Z<ddd> should be empty
+
+X<> should not be empty
+
+=over four
+
+This paragrapgh is misplaced - it ought to be an item.
+
+=item four should be numeric!
+
+=item
+
+=item blah
+
+=item previous is all empty!!!
+
+=back
+
+All empty over/back:
+
+=over 4
+
+=back
+
+item w/o name
+
+=cut
+
+=pod bla
+
+bla is evil
+
+=cut blub
+
+blub is evil
+
+=head2 reoccurence
+
 =over 4
 
+=item Misc
+
+we already have a head Misc
+
 =back
 
-see these unescaped < and > in the text?
+=head2 some heading
+
+=head2 another one
+
+previous section is empty!
 
 =cut
 
+
diff --git a/t/pod/poderrs.xr b/t/pod/poderrs.xr
index b8e5e86fd5..015f8984eb 100644
--- a/t/pod/poderrs.xr
+++ b/t/pod/poderrs.xr
@@ -1,33 +1,48 @@
-*** ERROR: Unknown command 'unknown1' at line 25 in file pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'Q' at line 29 in file pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'A' at line 30 in file pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'Y' at line 31 in file pod/poderrs.t
-*** ERROR: Unknown interior-sequence 'V' at line 31 in file pod/poderrs.t
-*** ERROR: unterminated B<...> at line 35 in file pod/poderrs.t
-*** ERROR: unterminated I<...> at line 34 in file pod/poderrs.t
-*** ERROR: unterminated C<...> at line 37 in file pod/poderrs.t
-*** WARNING: line containing nothing but whitespace in paragraph at line 45 in file pod/poderrs.t
-*** ERROR: =item without previous =over at line 52 in file pod/poderrs.t
-*** ERROR: =back without previous =over at line 56 in file pod/poderrs.t
-*** ERROR: =over on line 60 without closing =back (at head2) at line 64 in file pod/poderrs.t
-*** ERROR: =end without =begin at line 66 in file pod/poderrs.t
-*** ERROR: Nested =begin's (first at line 70:html) at line 72 in file pod/poderrs.t
-*** ERROR: =end without =begin at line 76 in file pod/poderrs.t
-*** ERROR: nested commands C<...C<...>...> at line 80 in file pod/poderrs.t
-*** ERROR: garbled entity E<alea iacta est> at line 84 in file pod/poderrs.t
-*** ERROR: garbled entity E<C<auml>> at line 85 in file pod/poderrs.t
-*** ERROR: garbled entity E<abcI<bla>> at line 86 in file pod/poderrs.t
-*** WARNING: collapsing newlines to blanks at line 96 in file pod/poderrs.t
-*** ERROR: malformed link L<> : empty link at line 98 in file pod/poderrs.t
-*** WARNING: ignoring leading whitespace in link at line 104 in file pod/poderrs.t
-*** WARNING: ignoring trailing whitespace in link at line 104 in file pod/poderrs.t
-*** ERROR: Spurious character(s) after =back at line 110 in file pod/poderrs.t
-*** WARNING: No items in =over (at line 118) / =back list at line 120 in file pod/poderrs.t
-*** WARNING: 2 unescaped <> in paragraph at line 122 in file pod/poderrs.t
-*** ERROR: unresolved internal link 'begin or begin' at line 90 in file pod/poderrs.t
-*** ERROR: unresolved internal link 'end with begin' at line 91 in file pod/poderrs.t
-*** ERROR: unresolved internal link 'OoPs' at line 92 in file pod/poderrs.t
-*** ERROR: unresolved internal link 'abc def' at line 96 in file pod/poderrs.t
-*** ERROR: unresolved internal link 'passwd(5)' at line 103 in file pod/poderrs.t
-*** WARNING: multiple occurence of link target 'oops' at line - in file pod/poderrs.t
-pod/poderrs.t has 25 pod syntax errors.
+*** ERROR: Unknown command 'unknown1' at line 25 in file t/pod/poderrs.t
+*** ERROR: Unknown interior-sequence 'Q' at line 29 in file t/pod/poderrs.t
+*** ERROR: Unknown interior-sequence 'A' at line 30 in file t/pod/poderrs.t
+*** ERROR: Unknown interior-sequence 'Y' at line 31 in file t/pod/poderrs.t
+*** ERROR: Unknown interior-sequence 'V' at line 31 in file t/pod/poderrs.t
+*** ERROR: unterminated B<...> at line 35 in file t/pod/poderrs.t
+*** ERROR: unterminated I<...> at line 34 in file t/pod/poderrs.t
+*** ERROR: unterminated C<...> at line 37 in file t/pod/poderrs.t
+*** WARNING: line containing nothing but whitespace in paragraph at line 45 in file t/pod/poderrs.t
+*** ERROR: =item without previous =over at line 52 in file t/pod/poderrs.t
+*** ERROR: =back without previous =over at line 56 in file t/pod/poderrs.t
+*** ERROR: =over on line 60 without closing =back (at head2) at line 64 in file t/pod/poderrs.t
+*** ERROR: =end without =begin at line 66 in file t/pod/poderrs.t
+*** ERROR: Nested =begin's (first at line 70:html) at line 72 in file t/pod/poderrs.t
+*** ERROR: =end without =begin at line 76 in file t/pod/poderrs.t
+*** ERROR: No argument for =begin at line 82 in file t/pod/poderrs.t
+*** ERROR: =for without formatter specification at line 88 in file t/pod/poderrs.t
+*** ERROR: nested commands C<...C<...>...> at line 94 in file t/pod/poderrs.t
+*** ERROR: garbled entity E<alea iacta est> at line 98 in file t/pod/poderrs.t
+*** ERROR: garbled entity E<C<auml>> at line 99 in file t/pod/poderrs.t
+*** ERROR: garbled entity E<abcI<bla>> at line 100 in file t/pod/poderrs.t
+*** ERROR: Entity number out of range E<0x100> at line 101 in file t/pod/poderrs.t
+*** ERROR: Entity number out of range E<07777> at line 102 in file t/pod/poderrs.t
+*** ERROR: Entity number out of range E<300> at line 103 in file t/pod/poderrs.t
+*** WARNING: collapsing newlines to blanks at line 113 in file t/pod/poderrs.t
+*** ERROR: malformed link L<> : empty link at line 115 in file t/pod/poderrs.t
+*** WARNING: ignoring leading whitespace in link at line 116 in file t/pod/poderrs.t
+*** WARNING: ignoring trailing whitespace in link at line 117 in file t/pod/poderrs.t
+*** WARNING: (section) in 'passwd(5)' deprecated at line 123 in file t/pod/poderrs.t
+*** WARNING: node '$|' contains non-escaped | or / at line 124 in file t/pod/poderrs.t
+*** WARNING: alternative text '$|' contains non-escaped | or / at line 124 in file t/pod/poderrs.t
+*** ERROR: Spurious character(s) after =back at line 130 in file t/pod/poderrs.t
+*** ERROR: Nonempty Z<> at line 144 in file t/pod/poderrs.t
+*** ERROR: Empty X<> at line 146 in file t/pod/poderrs.t
+*** WARNING: No numeric argument for =over at line 148 in file t/pod/poderrs.t
+*** WARNING: preceding non-item paragraph(s) at line 152 in file t/pod/poderrs.t
+*** WARNING: No argument for =item at line 154 in file t/pod/poderrs.t
+*** WARNING: previous =item has no contents at line 156 in file t/pod/poderrs.t
+*** WARNING: No items in =over (at line 164) / =back list at line 166 in file t/pod/poderrs.t
+*** ERROR: Spurious text after =pod at line 172 in file t/pod/poderrs.t
+*** ERROR: Spurious text after =cut at line 176 in file t/pod/poderrs.t
+*** WARNING: empty section in previous paragraph at line 192 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'begin or begin' at line 107 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'end with begin' at line 108 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'OoPs' at line 109 in file t/pod/poderrs.t
+*** ERROR: unresolved internal link 'abc def' at line 113 in file t/pod/poderrs.t
+*** WARNING: multiple occurence of link target 'Misc' at line - in file t/pod/poderrs.t
+t/pod/poderrs.t has 33 pod syntax errors.
diff --git a/t/pod/podselect.t b/t/pod/podselect.t
index 30eb30c9b0..0004548cb7 100755
--- a/t/pod/podselect.t
+++ b/t/pod/podselect.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }
diff --git a/t/pod/special_seqs.t b/t/pod/special_seqs.t
index b8af57ee05..1f229c2761 100755
--- a/t/pod/special_seqs.t
+++ b/t/pod/special_seqs.t
@@ -1,7 +1,7 @@
-#!./perl
 BEGIN {
-   chdir 't' if -d 't';
-   unshift @INC, './pod', '../lib';
+   use File::Basename;
+   my $THISDIR = dirname $0;
+   unshift @INC, $THISDIR;
    require "testp2pt.pl";
    import TestPodIncPlainText;
 }