Update Pod-Usage from version 1.70 to 2.01

15 files changed, 1128 insertions, 1024 deletions

diff --git a/cpan/Pod-Usage/lib/Pod/Usage.pm b/cpan/Pod-Usage/lib/Pod/Usage.pm
index fe5e555626..c290f2baf1 100644
--- a/cpan/Pod-Usage/lib/Pod/Usage.pm
+++ b/cpan/Pod-Usage/lib/Pod/Usage.pm
@@ -9,19 +9,19 @@
 #############################################################################
 
 package Pod::Usage;
-use strict;
 
-use vars qw($VERSION @ISA @EXPORT);
-$VERSION = '1.70';  ## Current version of this package
+use strict;
 require  5.006;    ## requires this Perl version or later
 
-#use diagnostics;
 use Carp;
 use Config;
 use Exporter;
 use File::Spec;
 
-@EXPORT = qw(&pod2usage);
+our $VERSION = '2.01';
+
+our @EXPORT = qw(&pod2usage);
+our @ISA;
 BEGIN {
     $Pod::Usage::Formatter ||= 'Pod::Text';
     eval "require $Pod::Usage::Formatter";
@@ -103,13 +103,13 @@ sub pod2usage {
 
         my @paths = (ref $pathspec) ? @$pathspec : split($pathsep, $pathspec);
         for my $dirname (@paths) {
-            $_ = File::Spec->catfile($dirname, $basename)  if length;
+            $_ = length($dirname) ? File::Spec->catfile($dirname, $basename) : $basename;
             last if (-e $_) && ($opts{'-input'} = $_);
         }
     }
 
     ## Now create a pod reader and constrain it to the desired sections.
-    my $parser = new Pod::Usage(USAGE_OPTIONS => \%opts);
+    my $parser = Pod::Usage->new(USAGE_OPTIONS => \%opts);
     if ($opts{'-verbose'} == 0) {
         $parser->select('(?:SYNOPSIS|USAGE)\s*');
     }
@@ -386,9 +386,11 @@ sub preprocess_paragraph {
 
 __END__
 
+=for stopwords pod2usage verboseness downcased MSWin32 Marek Rouchal Christiansen ATOOMIC rjbs McDougall
+
 =head1 NAME
 
-Pod::Usage - print a usage message from embedded pod documentation
+Pod::Usage - extracts POD documentation and shows usage information
 
 =head1 SYNOPSIS
 
@@ -404,13 +406,13 @@ Pod::Usage - print a usage message from embedded pod documentation
   pod2usage($exit_status);
 
   pod2usage( { -message => $message_text ,
-               -exitval => $exit_status  ,  
-               -verbose => $verbose_level,  
+               -exitval => $exit_status  ,
+               -verbose => $verbose_level,
                -output  => $filehandle } );
 
   pod2usage(   -msg     => $message_text ,
-               -exitval => $exit_status  ,  
-               -verbose => $verbose_level,  
+               -exitval => $exit_status  ,
+               -verbose => $verbose_level,
                -output  => $filehandle );
 
   pod2usage(   -verbose => 2,
@@ -456,39 +458,39 @@ keys:
 =item C<-msg> I<string>
 
 The text of a message to print immediately prior to printing the
-program's usage message. 
+program's usage message.
 
 =item C<-exitval> I<value>
 
 The desired exit status to pass to the B<exit()> function.
-This should be an integer, or else the string "NOEXIT" to
+This should be an integer, or else the string C<NOEXIT> to
 indicate that control should simply be returned without
 terminating the invoking process.
 
 =item C<-verbose> I<value>
 
 The desired level of "verboseness" to use when printing the usage message.
-If the value is 0, then only the "SYNOPSIS" section of the pod documentation
-is printed. If the value is 1, then the "SYNOPSIS" section, along with any
-section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is
-printed. If the corresponding value is 2 or more then the entire manpage is
-printed, using L<perldoc> if available; otherwise L<Pod::Text> is used for
-the formatting. For better readability, the all-capital headings are
-downcased, e.g. C<SYNOPSIS> =E<gt> C<Synopsis>.
+If the value is 0, then only the "SYNOPSIS" and/or "USAGE" sections of the
+pod documentation are printed. If the value is 1, then the "SYNOPSIS" and/or
+"USAGE" sections, along with any section entitled "OPTIONS", "ARGUMENTS", or
+"OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more
+then the entire manpage is printed, using L<perldoc> if available; otherwise
+L<Pod::Text> is used for the formatting. For better readability, the
+all-capital headings are downcased, e.g. C<SYNOPSIS> =E<gt> C<Synopsis>.
 
 The special verbosity level 99 requires to also specify the -sections
 parameter; then these sections are extracted and printed.
 
 =item C<-sections> I<spec>
 
-There are two ways to specify the selection. Either a string (scalar) 
+There are two ways to specify the selection. Either a string (scalar)
 representing a selection regexp for sections to be printed when -verbose
 is set to 99, e.g.
 
   "NAME|SYNOPSIS|DESCRIPTION|VERSION"
 
 With the above regexp all content following (and including) any of the
-given C<=head1> headings will be shown. It is possible to restrict the 
+given C<=head1> headings will be shown. It is possible to restrict the
 output to particular subsections only, e.g.:
 
   "DESCRIPTION/Algorithm"
@@ -507,7 +509,7 @@ Alternatively, an array reference of section specifications can be used:
   pod2usage(-verbose => 99, -sections => [
     qw(DESCRIPTION DESCRIPTION/Introduction) ] );
 
-This will print only the content of C<=head1 DESCRIPTION> and the 
+This will print only the content of C<=head1 DESCRIPTION> and the
 C<=head2 Introduction> sections, but no other C<=head2>, and no other
 C<=head1> either.
 
@@ -541,17 +543,16 @@ MSWin32 and DOS).
 
 =item C<-noperldoc>
 
-By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is
-specified. This does not work well e.g. if the script was packed
-with L<PAR>. The -noperldoc option suppresses the external call to
-L<perldoc> and uses the simple text formatter (L<Pod::Text>) to 
-output the POD.
+By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is specified.
+This does not work well e.g. if the script was packed with L<PAR>. This option
+suppresses the external call to L<perldoc> and uses the simple text formatter
+(L<Pod::Text>) to output the POD.
 
 =item C<-perlcmd>
 
 By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is
 specified. In case of special or unusual Perl installations,
-the -perlcmd option may be used to supply the path to a L<perl> executable
+this option may be used to supply the path to a L<perl> executable
 which should run L<perldoc>.
 
 =item C<-perldoc> I<path-to-perldoc>
@@ -564,7 +565,7 @@ the correct path to L<perldoc>.
 =item C<-perldocopt> I<string>
 
 By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is specified.
-The -perldocopt option may be used to supply options to L<perldoc>. The
+This option may be used to supply options to L<perldoc>. The
 string may contain several, space-separated options.
 
 =back
@@ -672,7 +673,7 @@ more verbose description of program usage in this case.
 
 =back
 
-B<pod2usage> doesn't force the above conventions upon you, but it will
+B<pod2usage> does not force the above conventions upon you, but it will
 use them by default if you don't expressly tell it to do otherwise.  The
 ability of B<pod2usage()> to accept a single number or a string makes it
 convenient to use as an innocent looking error message handling function:
@@ -861,7 +862,7 @@ things:
 
 By default, B<pod2usage()> will use C<$0> as the path to the pod input
 file.  Unfortunately, not all systems on which Perl runs will set C<$0>
-properly (although if C<$0> isn't found, B<pod2usage()> will search
+properly (although if C<$0> is not found, B<pod2usage()> will search
 C<$ENV{PATH}> or else the list specified by the C<-pathlist> option).
 If this is the case for your system, you may need to explicitly specify
 the path to the pod docs for the invoking script using something
@@ -878,12 +879,27 @@ the script:
     use FindBin;
     pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);
 
-=head1 AUTHOR
+=head1 SUPPORT
 
-Please report bugs using L<http://rt.cpan.org>.
+This module is managed in a GitHub repository,
+L<https://github.com/Dual-Life/Pod-Usage> Feel free to fork and contribute, or
+to clone and send patches!
+
+Please use L<https://github.com/Dual-Life/Pod-Usage/issues/new> to file a bug
+report.  The previous ticketing system,
+L<https://rt.cpan.org/Dist/Display.html?Queue=Pod-Usage>, is deprecated for
+this package.
+
+More general questions or discussion about POD should be sent to the
+C<pod-people@perl.org> mail list. Send an empty email to
+C<pod-people-subscribe@perl.org> to subscribe.
+
+=head1 AUTHOR
 
 Marek Rouchal E<lt>marekr@cpan.orgE<gt>
 
+Nicolas R E<lt>nicolas@atoomic.orgE<gt>
+
 Brad Appleton E<lt>bradapp@enteract.comE<gt>
 
 Based on code for B<Pod::Text::pod2text()> written by
@@ -895,10 +911,13 @@ Pod::Usage (the distribution) is licensed under the same terms as Perl.
 
 =head1 ACKNOWLEDGMENTS
 
+Nicolas R (ATOOMIC) for setting up the Github repo and modernizing this
+package.
+
 rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
 
-Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience
-with re-writing this manpage.
+Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience with
+re-writing this manpage.
 
 =head1 SEE ALSO
 
diff --git a/cpan/Pod-Usage/scripts/pod2usage.PL b/cpan/Pod-Usage/scripts/pod2usage.PL
index a51df226eb..573559da93 100644
--- a/cpan/Pod-Usage/scripts/pod2usage.PL
+++ b/cpan/Pod-Usage/scripts/pod2usage.PL
@@ -1,5 +1,7 @@
 #!/usr/local/bin/perl
 
+use strict;
+use warnings;
 use Config;
 use File::Basename qw(&basename &dirname);
 use Cwd;
@@ -13,19 +15,19 @@ use Cwd;
 
 # This forces PL files to create target in same directory as PL file.
 # This is so that make depend always knows where to find PL derivatives.
-$origdir = cwd;
-chdir(dirname($0));
-$file = basename($0, '.PL');
+my $origdir = cwd;
+chdir( dirname($0) );
+my $file = basename( $0, '.PL' );
 $file .= '.com' if $^O eq 'VMS';
 
-open OUT,">$file" or die "Can't create $file: $!";
+open my $OUT, '>', $file or die "Can't create $file: $!";
 
 print "Extracting $file (with variable substitutions)\n";
 
 # In this section, perl variables will be expanded during extraction.
 # You can use $Config{...} to use Configure variables.
 
-print OUT <<"!GROK!THIS!";
+print {$OUT} <<"!GROK!THIS!";
 $Config{'startperl'}
     eval 'exec perl -S \$0 "\$@"'
         if 0;
@@ -33,7 +35,7 @@ $Config{'startperl'}
 
 # In the following, perl variables are not expanded during extraction.
 
-print OUT <<'!NO!SUBS!';
+print {$OUT} <<'!NO!SUBS!';
 
 #############################################################################
 # pod2usage -- command to print usage messages from embedded pod docs
@@ -195,7 +197,7 @@ pod2usage(\%usage);
 
 !NO!SUBS!
 
-close OUT or die "Can't close $file: $!";
-chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+close($OUT) or die "Can't close $file: $!";
+chmod( 0755, $file ) or die "Can't reset permissions for $file: $!\n";
 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
-chdir $origdir;
+chdir($origdir);
diff --git a/cpan/Pod-Usage/t/inc/Pod/InputObjects.pm b/cpan/Pod-Usage/t/inc/Pod/InputObjects.pm
index c19d4c550b..f3570425de 100644
--- a/cpan/Pod-Usage/t/inc/Pod/InputObjects.pm
+++ b/cpan/Pod-Usage/t/inc/Pod/InputObjects.pm
@@ -1,942 +1,941 @@
-#############################################################################

-# Pod/InputObjects.pm -- package which defines objects for input streams

-# and paragraphs and commands when parsing POD docs.

-#

-# 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.

-#############################################################################

-

-package Pod::InputObjects;

-use strict;

-

-use vars qw($VERSION);

-$VERSION = '1.60';  ## Current version of this package

-require  5.005;    ## requires this Perl version or later

-

-#############################################################################

-

-=head1 NAME

-

-Pod::InputObjects - objects representing POD input paragraphs, commands, etc.

-

-=head1 SYNOPSIS

-

-    use Pod::InputObjects;

-

-=head1 REQUIRES

-

-perl5.004, Carp

-

-=head1 EXPORTS

-

-Nothing.

-

-=head1 DESCRIPTION

-

-This module defines some basic input objects used by B<Pod::Parser> when

-reading and parsing POD text from an input source. The following objects

-are defined:

-

-=begin __PRIVATE__

-

-=over 4

-

-=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

-that implements the C<getline()> method) which keeps track of some

-additional information relevant to the parsing of PODs.

-

-=back

-

-=end __PRIVATE__

-

-=over 4

-

-=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 package B<Pod::InteriorSequence>

-

-An object corresponding to an interior sequence command from the POD

-input text (see L<perlpod>).

-

-=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 the order in which they were parsed from left-to-right.

-

-=back

-

-Each of these input objects are described in further detail in the

-sections which follow.

-

-=cut

-

-#############################################################################

-

-package Pod::InputSource;

-

-##---------------------------------------------------------------------------

-

-=begin __PRIVATE__

-

-=head1 B<Pod::InputSource>

-

-This object corresponds to an input source or stream of POD

-documentation. When parsing PODs, it is necessary to associate and store

-certain context information with each input source. All of this

-information is kept together with the stream itself in one of these

-C<Pod::InputSource> objects. Each such object is merely a wrapper around

-an C<IO::Handle> object of some kind (or at least something that

-implements the C<getline()> method). They have the following

-methods/attributes:

-

-=end __PRIVATE__

-

-=cut

-

-##---------------------------------------------------------------------------

-

-=begin __PRIVATE__

-

-=head2 B<new()>

-

-        my $pod_input1 = Pod::InputSource->new(-handle => $filehandle);

-        my $pod_input2 = new Pod::InputSource(-handle => $filehandle,

-                                              -name   => $name);

-        my $pod_input3 = new Pod::InputSource(-handle => \*STDIN);

-        my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN,

-                                               -name => "(STDIN)");

-

-This is a class method that constructs a C<Pod::InputSource> object and

-returns a reference to the new input source object. It takes one or more

-keyword arguments in the form of a hash. The keyword C<-handle> is

-required and designates the corresponding input handle. The keyword

-C<-name> is optional and specifies the name associated with the input

-handle (typically a file name).

-

-=end __PRIVATE__

-

-=cut

-

-sub new {

-    ## Determine if we were called via an object-ref or a classname

-    my $this = shift;

-    my $class = ref($this) || $this;

-

-    ## Any remaining arguments are treated as initial values for the

-    ## hash that is used to represent this object. Note that we default

-    ## certain values by specifying them *before* the arguments passed.

-    ## If they are in the argument list, they will override the defaults.

-    my $self = { -name        => '(unknown)',

-                 -handle      => undef,

-                 -was_cutting => 0,

-                 @_ };

-

-    ## Bless ourselves into the desired class and perform any initialization

-    bless $self, $class;

-    return $self;

-}

-

-##---------------------------------------------------------------------------

-

-=begin __PRIVATE__

-

-=head2 B<name()>

-

-        my $filename = $pod_input->name();

-        $pod_input->name($new_filename_to_use);

-

-This method gets/sets the name of the input source (usually a filename).

-If no argument is given, it returns a string containing the name of

-the input source; otherwise it sets the name of the input source to the

-contents of the given argument.

-

-=end __PRIVATE__

-

-=cut

-

-sub name {

-   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];

-   return $_[0]->{'-name'};

-}

-

-## allow 'filename' as an alias for 'name'

-*filename = \&name;

-

-##---------------------------------------------------------------------------

-

-=begin __PRIVATE__

-

-=head2 B<handle()>

-

-        my $handle = $pod_input->handle();

-

-Returns a reference to the handle object from which input is read (the

-one used to contructed this input source object).

-

-=end __PRIVATE__

-

-=cut

-

-sub handle {

-   return $_[0]->{'-handle'};

-}

-

-##---------------------------------------------------------------------------

-

-=begin __PRIVATE__

-

-=head2 B<was_cutting()>

-

-        print "Yes.\n" if ($pod_input->was_cutting());

-

-The value of the C<cutting> state (that the B<cutting()> method would

-have returned) immediately before any input was read from this input

-stream. After all input from this stream has been read, the C<cutting>

-state is restored to this value.

-

-=end __PRIVATE__

-

-=cut

-

-sub was_cutting {

-   (@_ > 1)  and  $_[0]->{-was_cutting} = $_[1];

-   return $_[0]->{-was_cutting};

-}

-

-##---------------------------------------------------------------------------

-

-#############################################################################

-

-package Pod::Paragraph;

-

-##---------------------------------------------------------------------------

-

-=head1 B<Pod::Paragraph>

-

-An object representing a paragraph of POD input text.

-It has the following methods/attributes:

-

-=cut

-

-##---------------------------------------------------------------------------

-

-=head2 Pod::Paragraph-E<gt>B<new()>

-

-        my $pod_para1 = Pod::Paragraph->new(-text => $text);

-        my $pod_para2 = Pod::Paragraph->new(-name => $cmd,

-                                            -text => $text);

-        my $pod_para3 = new Pod::Paragraph(-text => $text);

-        my $pod_para4 = new Pod::Paragraph(-name => $cmd,

-                                           -text => $text);

-        my $pod_para5 = Pod::Paragraph->new(-name => $cmd,

-                                            -text => $text,

-                                            -file => $filename,

-                                            -line => $line_number);

-

-This is a class method that constructs a C<Pod::Paragraph> object and

-returns a reference to the new paragraph object. It may be given one or

-two keyword arguments. The C<-text> keyword indicates the corresponding

-text of the POD paragraph. The C<-name> keyword indicates the name of

-the corresponding POD command, such as C<head1> or C<item> (it should

-I<not> contain the C<=> prefix); this is needed only if the POD

-paragraph corresponds to a command paragraph. The C<-file> and C<-line>

-keywords indicate the filename and line number corresponding to the

-beginning of the paragraph 

-

-=cut

-

-sub new {

-    ## Determine if we were called via an object-ref or a classname

-    my $this = shift;

-    my $class = ref($this) || $this;

-

-    ## Any remaining arguments are treated as initial values for the

-    ## hash that is used to represent this object. Note that we default

-    ## certain values by specifying them *before* the arguments passed.

-    ## If they are in the argument list, they will override the defaults.

-    my $self = {

-          -name       => undef,

-          -text       => (@_ == 1) ? shift : undef,

-          -file       => '<unknown-file>',

-          -line       => 0,

-          -prefix     => '=',

-          -separator  => ' ',

-          -ptree => [],

-          @_

-    };

-

-    ## Bless ourselves into the desired class and perform any initialization

-    bless $self, $class;

-    return $self;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_para-E<gt>B<cmd_name()>

-

-        my $para_cmd = $pod_para->cmd_name();

-

-If this paragraph is a command paragraph, then this method will return 

-the name of the command (I<without> any leading C<=> prefix).

-

-=cut

-

-sub cmd_name {

-   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];

-   return $_[0]->{'-name'};

-}

-

-## let name() be an alias for cmd_name()

-*name = \&cmd_name;

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_para-E<gt>B<text()>

-

-        my $para_text = $pod_para->text();

-

-This method will return the corresponding text of the paragraph.

-

-=cut

-

-sub text {

-   (@_ > 1)  and  $_[0]->{'-text'} = $_[1];

-   return $_[0]->{'-text'};

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_para-E<gt>B<raw_text()>

-

-        my $raw_pod_para = $pod_para->raw_text();

-

-This method will return the I<raw> text of the POD paragraph, exactly

-as it appeared in the input.

-

-=cut

-

-sub raw_text {

-   return $_[0]->{'-text'}  unless (defined $_[0]->{'-name'});

-   return $_[0]->{'-prefix'} . $_[0]->{'-name'} .

-          $_[0]->{'-separator'} . $_[0]->{'-text'};

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_para-E<gt>B<cmd_prefix()>

-

-        my $prefix = $pod_para->cmd_prefix();

-

-If this paragraph is a command paragraph, then this method will return 

-the prefix used to denote the command (which should be the string "="

-or "==").

-

-=cut

-

-sub cmd_prefix {

-   return $_[0]->{'-prefix'};

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_para-E<gt>B<cmd_separator()>

-

-        my $separator = $pod_para->cmd_separator();

-

-If this paragraph is a command paragraph, then this method will return

-the text used to separate the command name from the rest of the

-paragraph (if any).

-

-=cut

-

-sub cmd_separator {

-   return $_[0]->{'-separator'};

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_para-E<gt>B<parse_tree()>

-

-        my $ptree = $pod_parser->parse_text( $pod_para->text() );

-        $pod_para->parse_tree( $ptree );

-        $ptree = $pod_para->parse_tree();

-

-This method will get/set the corresponding parse-tree of the paragraph's text.

-

-=cut

-

-sub parse_tree {

-   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];

-   return $_[0]->{'-ptree'};

-}

-

-## let ptree() be an alias for parse_tree()

-*ptree = \&parse_tree;

-

-##---------------------------------------------------------------------------

-

-=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

-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.

-

-=cut

-

-sub file_line {

-   my @loc = ($_[0]->{'-file'} || '<unknown-file>',

-              $_[0]->{'-line'} || 0);

-   return (wantarray) ? @loc : join(':', @loc);

-}

-

-##---------------------------------------------------------------------------

-

-#############################################################################

-

-package Pod::InteriorSequence;

-

-##---------------------------------------------------------------------------

-

-=head1 B<Pod::InteriorSequence>

-

-An object representing a POD interior sequence command.

-It has the following methods/attributes:

-

-=cut

-

-##---------------------------------------------------------------------------

-

-=head2 Pod::InteriorSequence-E<gt>B<new()>

-

-        my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd

-                                                  -ldelim => $delimiter);

-        my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,

-                                                 -ldelim => $delimiter);

-        my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,

-                                                 -ldelim => $delimiter,

-                                                 -file => $filename,

-                                                 -line => $line_number);

-

-        my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);

-        my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);

-

-This is a class method that constructs a C<Pod::InteriorSequence> object

-and returns a reference to the new interior sequence object. It should

-be given two keyword arguments.  The C<-ldelim> keyword indicates the

-corresponding left-delimiter of the interior sequence (e.g. 'E<lt>').

-The C<-name> keyword indicates the name of the corresponding interior

-sequence command, such as C<I> or C<B> or C<C>. The C<-file> and

-C<-line> keywords indicate the filename and line number corresponding

-to the beginning of the interior sequence. If the C<$ptree> argument is

-given, it must be the last argument, and it must be either string, or

-else an array-ref suitable for passing to B<Pod::ParseTree::new> (or

-it may be a reference to a Pod::ParseTree object).

-

-=cut

-

-sub new {

-    ## Determine if we were called via an object-ref or a classname

-    my $this = shift;

-    my $class = ref($this) || $this;

-

-    ## See if first argument has no keyword

-    if (((@_ <= 2) or (@_ % 2)) and $_[0] !~ /^-\w/) {

-       ## Yup - need an implicit '-name' before first parameter

-       unshift @_, '-name';

-    }

-

-    ## See if odd number of args

-    if ((@_ % 2) != 0) {

-       ## Yup - need an implicit '-ptree' before the last parameter

-       splice @_, $#_, 0, '-ptree';

-    }

-

-    ## Any remaining arguments are treated as initial values for the

-    ## hash that is used to represent this object. Note that we default

-    ## certain values by specifying them *before* the arguments passed.

-    ## If they are in the argument list, they will override the defaults.

-    my $self = {

-          -name       => (@_ == 1) ? $_[0] : undef,

-          -file       => '<unknown-file>',

-          -line       => 0,

-          -ldelim     => '<',

-          -rdelim     => '>',

-          @_

-    };

-

-    ## Initialize contents if they havent been already

-    my $ptree = $self->{'-ptree'} || new Pod::ParseTree();

-    if ( ref $ptree =~ /^(ARRAY)?$/ ) {

-        ## We have an array-ref, or a normal scalar. Pass it as an

-        ## an argument to the ptree-constructor

-        $ptree = new Pod::ParseTree($1 ? [$ptree] : $ptree);

-    }

-    $self->{'-ptree'} = $ptree;

-

-    ## Bless ourselves into the desired class and perform any initialization

-    bless $self, $class;

-    return $self;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<cmd_name()>

-

-        my $seq_cmd = $pod_seq->cmd_name();

-

-The name of the interior sequence command.

-

-=cut

-

-sub cmd_name {

-   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];

-   return $_[0]->{'-name'};

-}

-

-## let name() be an alias for cmd_name()

-*name = \&cmd_name;

-

-##---------------------------------------------------------------------------

-

-## Private subroutine to set the parent pointer of all the given

-## children that are interior-sequences to be $self

-

-sub _set_child2parent_links {

-   my ($self, @children) = @_;

-   ## Make sure any sequences know who their parent is

-   for (@children) {

-      next  unless (length  and  ref  and  ref ne 'SCALAR');

-      if (UNIVERSAL::isa($_, 'Pod::InteriorSequence') or

-          UNIVERSAL::can($_, 'nested'))

-      {

-          $_->nested($self);

-      }

-   }

-}

-

-## Private subroutine to unset child->parent links

-

-sub _unset_child2parent_links {

-   my $self = shift;

-   $self->{'-parent_sequence'} = undef;

-   my $ptree = $self->{'-ptree'};

-   for (@$ptree) {

-      next  unless (length  and  ref  and  ref ne 'SCALAR');

-      $_->_unset_child2parent_links()

-          if UNIVERSAL::isa($_, 'Pod::InteriorSequence');

-   }

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<prepend()>

-

-        $pod_seq->prepend($text);

-        $pod_seq1->prepend($pod_seq2);

-

-Prepends the given string or parse-tree or sequence object to the parse-tree

-of this interior sequence.

-

-=cut

-

-sub prepend {

-   my $self  = shift;

-   $self->{'-ptree'}->prepend(@_);

-   _set_child2parent_links($self, @_);

-   return $self;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<append()>

-

-        $pod_seq->append($text);

-        $pod_seq1->append($pod_seq2);

-

-Appends the given string or parse-tree or sequence object to the parse-tree

-of this interior sequence.

-

-=cut

-

-sub append {

-   my $self = shift;

-   $self->{'-ptree'}->append(@_);

-   _set_child2parent_links($self, @_);

-   return $self;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<nested()>

-

-        $outer_seq = $pod_seq->nested || print "not nested";

-

-If this interior sequence is nested inside of another interior

-sequence, then the outer/parent sequence that contains it is

-returned. Otherwise C<undef> is returned.

-

-=cut

-

-sub nested {

-   my $self = shift;

-  (@_ == 1)  and  $self->{'-parent_sequence'} = shift;

-   return  $self->{'-parent_sequence'} || undef;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<raw_text()>

-

-        my $seq_raw_text = $pod_seq->raw_text();

-

-This method will return the I<raw> text of the POD interior sequence,

-exactly as it appeared in the input.

-

-=cut

-

-sub raw_text {

-   my $self = shift;

-   my $text = $self->{'-name'} . $self->{'-ldelim'};

-   for ( $self->{'-ptree'}->children ) {

-      $text .= (ref $_) ? $_->raw_text : $_;

-   }

-   $text .= $self->{'-rdelim'};

-   return $text;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<left_delimiter()>

-

-        my $ldelim = $pod_seq->left_delimiter();

-

-The leftmost delimiter beginning the argument text to the interior

-sequence (should be "<").

-

-=cut

-

-sub left_delimiter {

-   (@_ > 1)  and  $_[0]->{'-ldelim'} = $_[1];

-   return $_[0]->{'-ldelim'};

-}

-

-## let ldelim() be an alias for left_delimiter()

-*ldelim = \&left_delimiter;

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<right_delimiter()>

-

-The rightmost delimiter beginning the argument text to the interior

-sequence (should be ">").

-

-=cut

-

-sub right_delimiter {

-   (@_ > 1)  and  $_[0]->{'-rdelim'} = $_[1];

-   return $_[0]->{'-rdelim'};

-}

-

-## let rdelim() be an alias for right_delimiter()

-*rdelim = \&right_delimiter;

-

-##---------------------------------------------------------------------------

-

-=head2 $pod_seq-E<gt>B<parse_tree()>

-

-        my $ptree = $pod_parser->parse_text($paragraph_text);

-        $pod_seq->parse_tree( $ptree );

-        $ptree = $pod_seq->parse_tree();

-

-This method will get/set the corresponding parse-tree of the interior

-sequence's text.

-

-=cut

-

-sub parse_tree {

-   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];

-   return $_[0]->{'-ptree'};

-}

-

-## let ptree() be an alias for parse_tree()

-*ptree = \&parse_tree;

-

-##---------------------------------------------------------------------------

-

-=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

-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.

-

-=cut

-

-sub file_line {

-   my @loc = ($_[0]->{'-file'}  || '<unknown-file>',

-              $_[0]->{'-line'}  || 0);

-   return (wantarray) ? @loc : join(':', @loc);

-}

-

-##---------------------------------------------------------------------------

-

-=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

-the parent method from within your own method, otherwise

-I<interior-sequence storage will not be reclaimed upon destruction!>

-

-=cut

-

-sub DESTROY {

-   ## We need to get rid of all child->parent pointers throughout the

-   ## tree so their reference counts will go to zero and they can be

-   ## garbage-collected

-   _unset_child2parent_links(@_);

-}

-

-##---------------------------------------------------------------------------

-

-#############################################################################

-

-package Pod::ParseTree;

-

-##---------------------------------------------------------------------------

-

-=head1 B<Pod::ParseTree>

-

-This object corresponds to a tree of parsed POD text. As POD text is

-scanned from left to right, it is parsed into an ordered list of

-text-strings and B<Pod::InteriorSequence> objects (in order of

-appearance). A B<Pod::ParseTree> object corresponds to this list of

-strings and sequences. Each interior sequence in the parse-tree may

-itself contain a parse-tree (since interior sequences may be nested).

-

-=cut

-

-##---------------------------------------------------------------------------

-

-=head2 Pod::ParseTree-E<gt>B<new()>

-

-        my $ptree1 = Pod::ParseTree->new;

-        my $ptree2 = new Pod::ParseTree;

-        my $ptree4 = Pod::ParseTree->new($array_ref);

-        my $ptree3 = new Pod::ParseTree($array_ref);

-

-This is a class method that constructs a C<Pod::Parse_tree> object and

-returns a reference to the new parse-tree. If a single-argument is given,

-it must be a reference to an array, and is used to initialize the root

-(top) of the parse tree.

-

-=cut

-

-sub new {

-    ## Determine if we were called via an object-ref or a classname

-    my $this = shift;

-    my $class = ref($this) || $this;

-

-    my $self = (@_ == 1  and  ref $_[0]) ? $_[0] : [];

-

-    ## Bless ourselves into the desired class and perform any initialization

-    bless $self, $class;

-    return $self;

-}

-

-##---------------------------------------------------------------------------

-

-=head2 $ptree-E<gt>B<top()>

-

-        my $top_node = $ptree->top();

-        $ptree->top( $top_node );

-        $ptree->top( @children );

-

-This method gets/sets the top node of the parse-tree. If no arguments are

-given, it returns the topmost node in the tree (the root), which is also

-a B<Pod::ParseTree>. If it is given a single argument that is a reference,

-then the reference is assumed to a parse-tree and becomes the new top node.

-Otherwise, if arguments are given, they are treated as the new list of

-children for the top node.

-

-=cut

-

-sub top {

-   my $self = shift;

-   if (@_ > 0) {

-      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;

-   }

-   return $self;

-}

-

-## let parse_tree() & ptree() be aliases for the 'top' method

-*parse_tree = *ptree = \&top;

-

-##---------------------------------------------------------------------------

-

-=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

-(each of which should be either a string or a B<Pod::InteriorSequence>.

-Otherwise, if arguments are given, they are treated as the new list of

-children for the top node.

-

-=cut

-

-sub children {

-   my $self = shift;

-   if (@_ > 0) {

-      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;

-   }

-   return @{ $self };

-}

-

-##---------------------------------------------------------------------------

-

-=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,

-then the text is prepended to the first item (not added as a separate string).

-Otherwise the argument is added as a new string or parse-tree I<before>

-the current one.

-

-=cut

-

-use vars qw(@ptree);  ## an alias used for performance reasons

-

-sub prepend {

-   my $self = shift;

-   local *ptree = $self;

-   for (@_) {

-      next  unless length;

-      if (@ptree && !(ref $ptree[0]) && !(ref $_)) {

-         $ptree[0] = $_ . $ptree[0];

-      }

-      else {

-         unshift @ptree, $_;

-      }

-   }

-}

-

-##---------------------------------------------------------------------------

-

-=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,

-then the text is appended to the last item (not added as a separate string).

-Otherwise the argument is added as a new string or parse-tree I<after>

-the current one.

-

-=cut

-

-sub append {

-   my $self = shift;

-   local *ptree = $self;

-   my $can_append = @ptree && !(ref $ptree[-1]);

-   for (@_) {

-      if (ref) {

-         push @ptree, $_;

-      }

-      elsif(!length) {

-         next;

-      }

-      elsif ($can_append) {

-         $ptree[-1] .= $_;

-      }

-      else {

-         push @ptree, $_;

-      }

-   }

-}

-

-=head2 $ptree-E<gt>B<raw_text()>

-

-        my $ptree_raw_text = $ptree->raw_text();

-

-This method will return the I<raw> text of the POD parse-tree

-exactly as it appeared in the input.

-

-=cut

-

-sub raw_text {

-   my $self = shift;

-   my $text = '';

-   for ( @$self ) {

-      $text .= (ref $_) ? $_->raw_text : $_;

-   }

-   return $text;

-}

-

-##---------------------------------------------------------------------------

-

-## Private routines to set/unset child->parent links

-

-sub _unset_child2parent_links {

-   my $self = shift;

-   local *ptree = $self;

-   for (@ptree) {

-       next  unless (defined and length  and  ref  and  ref ne 'SCALAR');

-       $_->_unset_child2parent_links()

-           if UNIVERSAL::isa($_, 'Pod::InteriorSequence');

-   }

-}

-

-sub _set_child2parent_links {

-    ## nothing to do, Pod::ParseTrees cant have parent pointers

-}

-

-=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>

-that you invoke the parent method from within your own method,

-otherwise I<parse-tree storage will not be reclaimed upon destruction!>

-

-=cut

-

-sub DESTROY {

-   ## We need to get rid of all child->parent pointers throughout the

-   ## tree so their reference counts will go to zero and they can be

-   ## garbage-collected

-   _unset_child2parent_links(@_);

-}

-

-#############################################################################

-

-=head1 SEE ALSO

-

-B<Pod::InputObjects> is part of the L<Pod::Parser> distribution.

-

-See L<Pod::Parser>, L<Pod::Select>

-

-=head1 AUTHOR

-

-Please report bugs using L<http://rt.cpan.org>.

-

-Brad Appleton E<lt>bradapp@enteract.comE<gt>

-

-=cut

-

-1;

+#############################################################################
+# Pod/InputObjects.pm -- package which defines objects for input streams
+# and paragraphs and commands when parsing POD docs.
+#
+# 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.
+#############################################################################
+
+package Pod::InputObjects;
+use strict;
+use warnings;
+
+use vars qw($VERSION);
+$VERSION = '1.60';  ## Current version of this package
+require  5.005;    ## requires this Perl version or later
+
+#############################################################################
+
+=head1 NAME
+
+Pod::InputObjects - objects representing POD input paragraphs, commands, etc.
+
+=head1 SYNOPSIS
+
+    use Pod::InputObjects;
+
+=head1 REQUIRES
+
+perl5.004, Carp
+
+=head1 EXPORTS
+
+Nothing.
+
+=head1 DESCRIPTION
+
+This module defines some basic input objects used by B<Pod::Parser> when
+reading and parsing POD text from an input source. The following objects
+are defined:
+
+=begin __PRIVATE__
+
+=over 4
+
+=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
+that implements the C<getline()> method) which keeps track of some
+additional information relevant to the parsing of PODs.
+
+=back
+
+=end __PRIVATE__
+
+=over 4
+
+=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 package B<Pod::InteriorSequence>
+
+An object corresponding to an interior sequence command from the POD
+input text (see L<perlpod>).
+
+=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 the order in which they were parsed from left-to-right.
+
+=back
+
+Each of these input objects are described in further detail in the
+sections which follow.
+
+=cut
+
+#############################################################################
+
+package Pod::InputSource;
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head1 B<Pod::InputSource>
+
+This object corresponds to an input source or stream of POD
+documentation. When parsing PODs, it is necessary to associate and store
+certain context information with each input source. All of this
+information is kept together with the stream itself in one of these
+C<Pod::InputSource> objects. Each such object is merely a wrapper around
+an C<IO::Handle> object of some kind (or at least something that
+implements the C<getline()> method). They have the following
+methods/attributes:
+
+=end __PRIVATE__
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<new()>
+
+        my $pod_input1 = Pod::InputSource->new(-handle => $filehandle);
+        my $pod_input2 = Pod::InputSource->new(-handle => $filehandle,
+                                               -name   => $name);
+        my $pod_input3 = Pod::InputSource->new(-handle => \*STDIN);
+        my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN,
+                                               -name => "(STDIN)");
+
+This is a class method that constructs a C<Pod::InputSource> object and
+returns a reference to the new input source object. It takes one or more
+keyword arguments in the form of a hash. The keyword C<-handle> is
+required and designates the corresponding input handle. The keyword
+C<-name> is optional and specifies the name associated with the input
+handle (typically a file name).
+
+=end __PRIVATE__
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    ## Any remaining arguments are treated as initial values for the
+    ## hash that is used to represent this object. Note that we default
+    ## certain values by specifying them *before* the arguments passed.
+    ## If they are in the argument list, they will override the defaults.
+    my $self = { -name        => '(unknown)',
+                 -handle      => undef,
+                 -was_cutting => 0,
+                 @_ };
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<name()>
+
+        my $filename = $pod_input->name();
+        $pod_input->name($new_filename_to_use);
+
+This method gets/sets the name of the input source (usually a filename).
+If no argument is given, it returns a string containing the name of
+the input source; otherwise it sets the name of the input source to the
+contents of the given argument.
+
+=end __PRIVATE__
+
+=cut
+
+sub name {
+   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];
+   return $_[0]->{'-name'};
+}
+
+## allow 'filename' as an alias for 'name'
+*filename = \&name;
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<handle()>
+
+        my $handle = $pod_input->handle();
+
+Returns a reference to the handle object from which input is read (the
+one used to contructed this input source object).
+
+=end __PRIVATE__
+
+=cut
+
+sub handle {
+   return $_[0]->{'-handle'};
+}
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<was_cutting()>
+
+        print "Yes.\n" if ($pod_input->was_cutting());
+
+The value of the C<cutting> state (that the B<cutting()> method would
+have returned) immediately before any input was read from this input
+stream. After all input from this stream has been read, the C<cutting>
+state is restored to this value.
+
+=end __PRIVATE__
+
+=cut
+
+sub was_cutting {
+   (@_ > 1)  and  $_[0]->{-was_cutting} = $_[1];
+   return $_[0]->{-was_cutting};
+}
+
+##---------------------------------------------------------------------------
+
+#############################################################################
+
+package Pod::Paragraph;
+
+##---------------------------------------------------------------------------
+
+=head1 B<Pod::Paragraph>
+
+An object representing a paragraph of POD input text.
+It has the following methods/attributes:
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=head2 Pod::Paragraph-E<gt>B<new()>
+
+        my $pod_para1 = Pod::Paragraph->new(-text => $text);
+        my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
+                                            -text => $text);
+        my $pod_para3 = Pod::Paragraph->new(-text => $text);
+        my $pod_para4 = Pod::Paragraph->new(-name => $cmd,
+                                           -text => $text);
+        my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
+                                            -text => $text,
+                                            -file => $filename,
+                                            -line => $line_number);
+
+This is a class method that constructs a C<Pod::Paragraph> object and
+returns a reference to the new paragraph object. It may be given one or
+two keyword arguments. The C<-text> keyword indicates the corresponding
+text of the POD paragraph. The C<-name> keyword indicates the name of
+the corresponding POD command, such as C<head1> or C<item> (it should
+I<not> contain the C<=> prefix); this is needed only if the POD
+paragraph corresponds to a command paragraph. The C<-file> and C<-line>
+keywords indicate the filename and line number corresponding to the
+beginning of the paragraph 
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    ## Any remaining arguments are treated as initial values for the
+    ## hash that is used to represent this object. Note that we default
+    ## certain values by specifying them *before* the arguments passed.
+    ## If they are in the argument list, they will override the defaults.
+    my $self = {
+          -name       => undef,
+          -text       => (@_ == 1) ? shift : undef,
+          -file       => '<unknown-file>',
+          -line       => 0,
+          -prefix     => '=',
+          -separator  => ' ',
+          -ptree => [],
+          @_
+    };
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<cmd_name()>
+
+        my $para_cmd = $pod_para->cmd_name();
+
+If this paragraph is a command paragraph, then this method will return 
+the name of the command (I<without> any leading C<=> prefix).
+
+=cut
+
+sub cmd_name {
+   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];
+   return $_[0]->{'-name'};
+}
+
+## let name() be an alias for cmd_name()
+*name = \&cmd_name;
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<text()>
+
+        my $para_text = $pod_para->text();
+
+This method will return the corresponding text of the paragraph.
+
+=cut
+
+sub text {
+   (@_ > 1)  and  $_[0]->{'-text'} = $_[1];
+   return $_[0]->{'-text'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<raw_text()>
+
+        my $raw_pod_para = $pod_para->raw_text();
+
+This method will return the I<raw> text of the POD paragraph, exactly
+as it appeared in the input.
+
+=cut
+
+sub raw_text {
+   return $_[0]->{'-text'}  unless (defined $_[0]->{'-name'});
+   return $_[0]->{'-prefix'} . $_[0]->{'-name'} .
+          $_[0]->{'-separator'} . $_[0]->{'-text'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<cmd_prefix()>
+
+        my $prefix = $pod_para->cmd_prefix();
+
+If this paragraph is a command paragraph, then this method will return 
+the prefix used to denote the command (which should be the string "="
+or "==").
+
+=cut
+
+sub cmd_prefix {
+   return $_[0]->{'-prefix'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<cmd_separator()>
+
+        my $separator = $pod_para->cmd_separator();
+
+If this paragraph is a command paragraph, then this method will return
+the text used to separate the command name from the rest of the
+paragraph (if any).
+
+=cut
+
+sub cmd_separator {
+   return $_[0]->{'-separator'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<parse_tree()>
+
+        my $ptree = $pod_parser->parse_text( $pod_para->text() );
+        $pod_para->parse_tree( $ptree );
+        $ptree = $pod_para->parse_tree();
+
+This method will get/set the corresponding parse-tree of the paragraph's text.
+
+=cut
+
+sub parse_tree {
+   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];
+   return $_[0]->{'-ptree'};
+}
+
+## let ptree() be an alias for parse_tree()
+*ptree = \&parse_tree;
+
+##---------------------------------------------------------------------------
+
+=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
+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.
+
+=cut
+
+sub file_line {
+   my @loc = ($_[0]->{'-file'} || '<unknown-file>',
+              $_[0]->{'-line'} || 0);
+   return (wantarray) ? @loc : join(':', @loc);
+}
+
+##---------------------------------------------------------------------------
+
+#############################################################################
+
+package Pod::InteriorSequence;
+
+##---------------------------------------------------------------------------
+
+=head1 B<Pod::InteriorSequence>
+
+An object representing a POD interior sequence command.
+It has the following methods/attributes:
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=head2 Pod::InteriorSequence-E<gt>B<new()>
+
+        my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
+                                                  -ldelim => $delimiter);
+        my $pod_seq2 = Pod::InteriorSequence->new(-name => $cmd,
+                                                 -ldelim => $delimiter);
+        my $pod_seq3 = Pod::InteriorSequence->new(-name => $cmd,
+                                                 -ldelim => $delimiter,
+                                                 -file => $filename,
+                                                 -line => $line_number);
+
+        my $pod_seq4 = Pod::InteriorSequence->new(-name => $cmd, $ptree);
+        my $pod_seq5 = Pod::InteriorSequence->new($cmd, $ptree);
+
+This is a class method that constructs a C<Pod::InteriorSequence> object
+and returns a reference to the new interior sequence object. It should
+be given two keyword arguments.  The C<-ldelim> keyword indicates the
+corresponding left-delimiter of the interior sequence (e.g. 'E<lt>').
+The C<-name> keyword indicates the name of the corresponding interior
+sequence command, such as C<I> or C<B> or C<C>. The C<-file> and
+C<-line> keywords indicate the filename and line number corresponding
+to the beginning of the interior sequence. If the C<$ptree> argument is
+given, it must be the last argument, and it must be either string, or
+else an array-ref suitable for passing to B<Pod::ParseTree::new> (or
+it may be a reference to a Pod::ParseTree object).
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    ## See if first argument has no keyword
+    if (((@_ <= 2) or (@_ % 2)) and $_[0] !~ /^-\w/) {
+       ## Yup - need an implicit '-name' before first parameter
+       unshift @_, '-name';
+    }
+
+    ## See if odd number of args
+    if ((@_ % 2) != 0) {
+       ## Yup - need an implicit '-ptree' before the last parameter
+       splice @_, $#_, 0, '-ptree';
+    }
+
+    ## Any remaining arguments are treated as initial values for the
+    ## hash that is used to represent this object. Note that we default
+    ## certain values by specifying them *before* the arguments passed.
+    ## If they are in the argument list, they will override the defaults.
+    my $self = {
+          -name       => (@_ == 1) ? $_[0] : undef,
+          -file       => '<unknown-file>',
+          -line       => 0,
+          -ldelim     => '<',
+          -rdelim     => '>',
+          @_
+    };
+
+    ## Initialize contents if they havent been already
+    my $ptree = $self->{'-ptree'} || Pod::ParseTree->new();
+    if ( ref $ptree =~ /^(ARRAY)?$/ ) {
+        ## We have an array-ref, or a normal scalar. Pass it as an
+        ## an argument to the ptree-constructor
+        $ptree = Pod::ParseTree->new($1 ? [$ptree] : $ptree);
+    }
+    $self->{'-ptree'} = $ptree;
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<cmd_name()>
+
+        my $seq_cmd = $pod_seq->cmd_name();
+
+The name of the interior sequence command.
+
+=cut
+
+sub cmd_name {
+   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];
+   return $_[0]->{'-name'};
+}
+
+## let name() be an alias for cmd_name()
+*name = \&cmd_name;
+
+##---------------------------------------------------------------------------
+
+## Private subroutine to set the parent pointer of all the given
+## children that are interior-sequences to be $self
+
+sub _set_child2parent_links {
+   my ($self, @children) = @_;
+   ## Make sure any sequences know who their parent is
+   for (@children) {
+      next  unless (length  and  ref  and  ref ne 'SCALAR');
+      if (UNIVERSAL::isa($_, 'Pod::InteriorSequence') or
+          UNIVERSAL::can($_, 'nested'))
+      {
+          $_->nested($self);
+      }
+   }
+}
+
+## Private subroutine to unset child->parent links
+
+sub _unset_child2parent_links {
+   my $self = shift;
+   $self->{'-parent_sequence'} = undef;
+   my $ptree = $self->{'-ptree'};
+   for (@$ptree) {
+      next  unless (length  and  ref  and  ref ne 'SCALAR');
+      $_->_unset_child2parent_links()
+          if UNIVERSAL::isa($_, 'Pod::InteriorSequence');
+   }
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<prepend()>
+
+        $pod_seq->prepend($text);
+        $pod_seq1->prepend($pod_seq2);
+
+Prepends the given string or parse-tree or sequence object to the parse-tree
+of this interior sequence.
+
+=cut
+
+sub prepend {
+   my $self  = shift;
+   $self->{'-ptree'}->prepend(@_);
+   _set_child2parent_links($self, @_);
+   return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<append()>
+
+        $pod_seq->append($text);
+        $pod_seq1->append($pod_seq2);
+
+Appends the given string or parse-tree or sequence object to the parse-tree
+of this interior sequence.
+
+=cut
+
+sub append {
+   my $self = shift;
+   $self->{'-ptree'}->append(@_);
+   _set_child2parent_links($self, @_);
+   return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<nested()>
+
+        $outer_seq = $pod_seq->nested || print "not nested";
+
+If this interior sequence is nested inside of another interior
+sequence, then the outer/parent sequence that contains it is
+returned. Otherwise C<undef> is returned.
+
+=cut
+
+sub nested {
+   my $self = shift;
+  (@_ == 1)  and  $self->{'-parent_sequence'} = shift;
+   return  $self->{'-parent_sequence'} || undef;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<raw_text()>
+
+        my $seq_raw_text = $pod_seq->raw_text();
+
+This method will return the I<raw> text of the POD interior sequence,
+exactly as it appeared in the input.
+
+=cut
+
+sub raw_text {
+   my $self = shift;
+   my $text = $self->{'-name'} . $self->{'-ldelim'};
+   for ( $self->{'-ptree'}->children ) {
+      $text .= (ref $_) ? $_->raw_text : $_;
+   }
+   $text .= $self->{'-rdelim'};
+   return $text;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<left_delimiter()>
+
+        my $ldelim = $pod_seq->left_delimiter();
+
+The leftmost delimiter beginning the argument text to the interior
+sequence (should be "<").
+
+=cut
+
+sub left_delimiter {
+   (@_ > 1)  and  $_[0]->{'-ldelim'} = $_[1];
+   return $_[0]->{'-ldelim'};
+}
+
+## let ldelim() be an alias for left_delimiter()
+*ldelim = \&left_delimiter;
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<right_delimiter()>
+
+The rightmost delimiter beginning the argument text to the interior
+sequence (should be ">").
+
+=cut
+
+sub right_delimiter {
+   (@_ > 1)  and  $_[0]->{'-rdelim'} = $_[1];
+   return $_[0]->{'-rdelim'};
+}
+
+## let rdelim() be an alias for right_delimiter()
+*rdelim = \&right_delimiter;
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<parse_tree()>
+
+        my $ptree = $pod_parser->parse_text($paragraph_text);
+        $pod_seq->parse_tree( $ptree );
+        $ptree = $pod_seq->parse_tree();
+
+This method will get/set the corresponding parse-tree of the interior
+sequence's text.
+
+=cut
+
+sub parse_tree {
+   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];
+   return $_[0]->{'-ptree'};
+}
+
+## let ptree() be an alias for parse_tree()
+*ptree = \&parse_tree;
+
+##---------------------------------------------------------------------------
+
+=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
+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.
+
+=cut
+
+sub file_line {
+   my @loc = ($_[0]->{'-file'}  || '<unknown-file>',
+              $_[0]->{'-line'}  || 0);
+   return (wantarray) ? @loc : join(':', @loc);
+}
+
+##---------------------------------------------------------------------------
+
+=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
+the parent method from within your own method, otherwise
+I<interior-sequence storage will not be reclaimed upon destruction!>
+
+=cut
+
+sub DESTROY {
+   ## We need to get rid of all child->parent pointers throughout the
+   ## tree so their reference counts will go to zero and they can be
+   ## garbage-collected
+   _unset_child2parent_links(@_);
+}
+
+##---------------------------------------------------------------------------
+
+#############################################################################
+
+package Pod::ParseTree;
+
+##---------------------------------------------------------------------------
+
+=head1 B<Pod::ParseTree>
+
+This object corresponds to a tree of parsed POD text. As POD text is
+scanned from left to right, it is parsed into an ordered list of
+text-strings and B<Pod::InteriorSequence> objects (in order of
+appearance). A B<Pod::ParseTree> object corresponds to this list of
+strings and sequences. Each interior sequence in the parse-tree may
+itself contain a parse-tree (since interior sequences may be nested).
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=head2 Pod::ParseTree-E<gt>B<new()>
+
+        my $ptree1 = Pod::ParseTree->new;
+        my $ptree2 = Pod::ParseTree->new($array_ref);
+
+This is a class method that constructs a C<Pod::Parse_tree> object and
+returns a reference to the new parse-tree. If a single-argument is given,
+it must be a reference to an array, and is used to initialize the root
+(top) of the parse tree.
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    my $self = (@_ == 1  and  ref $_[0]) ? $_[0] : [];
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $ptree-E<gt>B<top()>
+
+        my $top_node = $ptree->top();
+        $ptree->top( $top_node );
+        $ptree->top( @children );
+
+This method gets/sets the top node of the parse-tree. If no arguments are
+given, it returns the topmost node in the tree (the root), which is also
+a B<Pod::ParseTree>. If it is given a single argument that is a reference,
+then the reference is assumed to a parse-tree and becomes the new top node.
+Otherwise, if arguments are given, they are treated as the new list of
+children for the top node.
+
+=cut
+
+sub top {
+   my $self = shift;
+   if (@_ > 0) {
+      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;
+   }
+   return $self;
+}
+
+## let parse_tree() & ptree() be aliases for the 'top' method
+*parse_tree = *ptree = \&top;
+
+##---------------------------------------------------------------------------
+
+=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
+(each of which should be either a string or a B<Pod::InteriorSequence>.
+Otherwise, if arguments are given, they are treated as the new list of
+children for the top node.
+
+=cut
+
+sub children {
+   my $self = shift;
+   if (@_ > 0) {
+      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;
+   }
+   return @{ $self };
+}
+
+##---------------------------------------------------------------------------
+
+=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,
+then the text is prepended to the first item (not added as a separate string).
+Otherwise the argument is added as a new string or parse-tree I<before>
+the current one.
+
+=cut
+
+use vars qw(@ptree);  ## an alias used for performance reasons
+
+sub prepend {
+   my $self = shift;
+   local *ptree = $self;
+   for (@_) {
+      next  unless length;
+      if (@ptree && !(ref $ptree[0]) && !(ref $_)) {
+         $ptree[0] = $_ . $ptree[0];
+      }
+      else {
+         unshift @ptree, $_;
+      }
+   }
+}
+
+##---------------------------------------------------------------------------
+
+=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,
+then the text is appended to the last item (not added as a separate string).
+Otherwise the argument is added as a new string or parse-tree I<after>
+the current one.
+
+=cut
+
+sub append {
+   my $self = shift;
+   local *ptree = $self;
+   my $can_append = @ptree && !(ref $ptree[-1]);
+   for (@_) {
+      if (ref) {
+         push @ptree, $_;
+      }
+      elsif(!length) {
+         next;
+      }
+      elsif ($can_append) {
+         $ptree[-1] .= $_;
+      }
+      else {
+         push @ptree, $_;
+      }
+   }
+}
+
+=head2 $ptree-E<gt>B<raw_text()>
+
+        my $ptree_raw_text = $ptree->raw_text();
+
+This method will return the I<raw> text of the POD parse-tree
+exactly as it appeared in the input.
+
+=cut
+
+sub raw_text {
+   my $self = shift;
+   my $text = '';
+   for ( @$self ) {
+      $text .= (ref $_) ? $_->raw_text : $_;
+   }
+   return $text;
+}
+
+##---------------------------------------------------------------------------
+
+## Private routines to set/unset child->parent links
+
+sub _unset_child2parent_links {
+   my $self = shift;
+   local *ptree = $self;
+   for (@ptree) {
+       next  unless (defined and length  and  ref  and  ref ne 'SCALAR');
+       $_->_unset_child2parent_links()
+           if UNIVERSAL::isa($_, 'Pod::InteriorSequence');
+   }
+}
+
+sub _set_child2parent_links {
+    ## nothing to do, Pod::ParseTrees cant have parent pointers
+}
+
+=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>
+that you invoke the parent method from within your own method,
+otherwise I<parse-tree storage will not be reclaimed upon destruction!>
+
+=cut
+
+sub DESTROY {
+   ## We need to get rid of all child->parent pointers throughout the
+   ## tree so their reference counts will go to zero and they can be
+   ## garbage-collected
+   _unset_child2parent_links(@_);
+}
+
+#############################################################################
+
+=head1 SEE ALSO
+
+B<Pod::InputObjects> is part of the L<Pod::Parser> distribution.
+
+See L<Pod::Parser>, L<Pod::Select>
+
+=head1 AUTHOR
+
+Please report bugs using L<http://rt.cpan.org>.
+
+Brad Appleton E<lt>bradapp@enteract.comE<gt>
+
+=cut
+
+1;
diff --git a/cpan/Pod-Usage/t/inc/Pod/Parser.pm b/cpan/Pod-Usage/t/inc/Pod/Parser.pm
index 4b4fecfbdd..25d562062c 100644
--- a/cpan/Pod-Usage/t/inc/Pod/Parser.pm
+++ b/cpan/Pod-Usage/t/inc/Pod/Parser.pm
@@ -9,6 +9,7 @@
 

 package Pod::Parser;

 use strict;

+use warnings;

 

 ## These "variables" are used as local "glob aliases" for performance

 use vars qw($VERSION @ISA %myData %myOpts @input_stack);

@@ -67,7 +68,7 @@ Pod::Parser - base class for creating POD filters and translators
 

     ## Create a parser object and have it parse file whose name was

     ## given on the command-line (use STDIN if no files were given).

-    $parser = new MyParser();

+    $parser = MyParser->new();

     $parser->parse_from_filehandle(\*STDIN)  if (@ARGV == 0);

     for (@ARGV) { $parser->parse_from_file($_); }

 

@@ -212,7 +213,7 @@ use Exporter;
 BEGIN {

    if ($] < 5.006) {

       require Symbol;

-      import Symbol;

+      Symbol->import;

    }

 }

 @ISA = qw(Exporter);

@@ -416,8 +417,7 @@ subclass objects as well as base class objects, provided you use
 any of the following constructor invocation styles:

 

     my $parser1 = MyParser->new();

-    my $parser2 = new MyParser();

-    my $parser3 = $parser2->new();

+    my $parser2 = $parser1->new();

 

 where C<MyParser> is some subclass of B<Pod::Parser>.

 

@@ -434,7 +434,7 @@ associative array (or hash-table) my be passed to the B<new()>
 constructor, as in:

 

     my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 );

-    my $parser2 = new MyParser( -myflag => 1 );

+    my $parser2 = MyParser->new( -myflag => 1 );

 

 All arguments passed to the B<new()> constructor will be treated as

 key/value pairs in a hash-table. The newly constructed object will be

@@ -977,7 +977,7 @@ sub parse_paragraph {
         }

     }

     ## Save the attributes indicating how the command was specified.

-    $pod_para = new Pod::Paragraph(

+    $pod_para = Pod::Paragraph->new(

           -name      => $cmd,

           -text      => $text,

           -prefix    => $pfx,

@@ -1563,7 +1563,7 @@ sub _push_input_stream {
     $myData{_INFILE}  = '(unknown)'  unless (defined  $myData{_INFILE});

     $myData{_INPUT}   = $in_fh;

     my $input_top     = $myData{_TOP_STREAM}

-                      = new Pod::InputSource(

+                      = Pod::InputSource->new(

                             -name        => $myData{_INFILE},

                             -handle      => $in_fh,

                             -was_cutting => $myData{_CUTTING}

@@ -1712,7 +1712,7 @@ following:
 

     package main;

     ...

-    my $parser = new MyPodParserTree(...);

+    my $parser = MyPodParserTree->new(...);

     $parser->parse_from_file(...);

     my $paragraphs_ref = $parser->{'-paragraphs'};

 

@@ -1727,7 +1727,7 @@ interface for all parse-tree nodes. The result would look something like:
 

     sub begin_pod {

         my $self = shift;

-        $self->{'-ptree'} = new Pod::ParseTree;  ## initialize parse-tree

+        $self->{'-ptree'} = Pod::ParseTree->new();  ## initialize parse-tree

     }

 

     sub parse_tree {

@@ -1759,7 +1759,7 @@ interface for all parse-tree nodes. The result would look something like:
 

     package main;

     ...

-    my $parser = new MyPodParserTree2(...);

+    my $parser = MyPodParserTree2->new(...);

     $parser->parse_from_file(...);

     my $ptree = $parser->parse_tree;

     ...

diff --git a/cpan/Pod-Usage/t/inc/Pod/PlainText.pm b/cpan/Pod-Usage/t/inc/Pod/PlainText.pm
index e8dc001dff..733d2a07e4 100644
--- a/cpan/Pod-Usage/t/inc/Pod/PlainText.pm
+++ b/cpan/Pod-Usage/t/inc/Pod/PlainText.pm
@@ -17,6 +17,7 @@
 

 package Pod::PlainText;

 use strict;

+use warnings;

 

 require 5.005;

 

@@ -34,7 +35,7 @@ $VERSION = '2.06';
 BEGIN {

    if ($] < 5.006) {

       require Symbol;

-      import Symbol;

+      Symbol->import;

    }

 }

 

diff --git a/cpan/Pod-Usage/t/inc/Pod/Select.pm b/cpan/Pod-Usage/t/inc/Pod/Select.pm
index 148b5d17cf..5065506f2b 100644
--- a/cpan/Pod-Usage/t/inc/Pod/Select.pm
+++ b/cpan/Pod-Usage/t/inc/Pod/Select.pm
@@ -9,6 +9,7 @@
 

 package Pod::Select;

 use strict;

+use warnings;

 

 use vars qw($VERSION @ISA @EXPORT $MAX_HEADING_LEVEL %myData @section_headings @selected_sections);

 $VERSION = '1.60'; ## Current version of this package

@@ -44,7 +45,7 @@ or
     use Pod::Select;

 

     ## Create a parser object for selecting POD sections from the input

-    $parser = new Pod::Select();

+    $parser = Pod::Select->new();

 

     ## Select all the POD sections for each file in @filelist

     ## and print the result to tmp.out.

@@ -575,7 +576,7 @@ filenames are given).
 sub podselect {

     my(@argv) = @_;

     my %defaults = ();

-    my $pod_parser = new Pod::Select(%defaults);

+    my $pod_parser = Pod::Select->new(%defaults);

     my $num_inputs = 0;

     my $output = '>&STDOUT';

     my %opts;

diff --git a/cpan/Pod-Usage/t/pod/headwithmarkup.t b/cpan/Pod-Usage/t/pod/headwithmarkup.t
index adba2bef82..ef745d14a3 100644
--- a/cpan/Pod-Usage/t/pod/headwithmarkup.t
+++ b/cpan/Pod-Usage/t/pod/headwithmarkup.t
@@ -1,5 +1,8 @@
 use Test::More tests => 1;
 
+use strict;
+use warnings;
+
 my $blib = $ENV{PERL_CORE} ? '-I../../lib' : '-Mblib';
 
 my $pl = $0;
diff --git a/cpan/Pod-Usage/t/pod/p2u_data.pl b/cpan/Pod-Usage/t/pod/p2u_data.pl
index ec0e3a7e50..4569043622 100644
--- a/cpan/Pod-Usage/t/pod/p2u_data.pl
+++ b/cpan/Pod-Usage/t/pod/p2u_data.pl
@@ -1,4 +1,7 @@
 use Pod::Usage;
+use strict;
+use warnings;
+
 pod2usage(-verbose => 2, -exit => 17, -input => \*DATA);
 
 __DATA__
diff --git a/cpan/Pod-Usage/t/pod/pod2usage.t b/cpan/Pod-Usage/t/pod/pod2usage.t
index cf2c31b83f..3ee7450398 100644
--- a/cpan/Pod-Usage/t/pod/pod2usage.t
+++ b/cpan/Pod-Usage/t/pod/pod2usage.t
@@ -1,9 +1,12 @@
+use strict;
+use warnings;
+
 BEGIN {
    use File::Basename;
    my $THISDIR = dirname $0;
    unshift @INC, $THISDIR;
    require "testp2pt.pl";
-   import TestPodIncPlainText;
+   TestPodIncPlainText->import;
 }
 
 my %options = map { $_ => 1 } @ARGV;  ## convert cmdline to options-hash
diff --git a/cpan/Pod-Usage/t/pod/pod2usage2.t b/cpan/Pod-Usage/t/pod/pod2usage2.t
index a6552c5e9c..8616422c94 100644
--- a/cpan/Pod-Usage/t/pod/pod2usage2.t
+++ b/cpan/Pod-Usage/t/pod/pod2usage2.t
@@ -1,14 +1,17 @@
 #!/usr/bin/perl -w
 
-use Test::More;
 use strict;
+use warnings;
+use Test::More;
+use File::Basename qw(fileparse);
+use File::Spec;
 
 BEGIN {
   if ($^O eq 'MSWin32' || $^O eq 'VMS') {
     plan skip_all => "Not portable on Win32 or VMS\n";
   }
   else {
-    plan tests => 33;
+    plan tests => 42;
   }
   use_ok ("Pod::Usage");
 }
@@ -16,24 +19,32 @@ BEGIN {
 sub getoutput
 {
   my ($code) = @_;
-  my $pid = open(TEST_IN, "-|");
-  unless(defined $pid) {
-    die "Cannot fork: $!";
-  }
-  if($pid) {
+  my $pid = open(my $in, "-|");
+  die "Cannot fork: $!" unless defined $pid;
+  if ($pid) {
     # parent
-    my @out = <TEST_IN>;
-    close(TEST_IN);
+    my @out = <$in>;
+    close($in);
+
     my $exit = $?>>8;
     s/^/#/ for @out;
+
     local $" = "";
+
     print "#EXIT=$exit OUTPUT=+++#@out#+++\n";
-    return($exit, join("",@out));
+    waitpid( $pid, 1 );
+
+    return ($exit, join("", @out) );
   }
   # child
-  open(STDERR, ">&STDOUT");
+  open (STDERR, ">&STDOUT");
+
   Test::More->builder->no_ending(1);
-  &$code;
+  local $SIG{ALRM} = sub { die "Alarm reached" };
+  alarm(600);
+
+  # this could hang
+  $code->();
   print "--NORMAL-RETURN--\n";
   exit 0;
 }
@@ -69,17 +80,17 @@ ok (compare ($text, <<'EOT'), "Output test pod2usage (-message => '...', -verbos
 #You naughty person, what did you say?
 # Usage:
 #     frobnicate [ -r | --recursive ] [ -f | --force ] file ...
-# 
+#
 # Options:
 #     -r | --recursive
 #         Run recursively.
-# 
+#
 #     -f | --force
 #         Just do it!
-# 
+#
 #     -n number
 #         Specify number of frobs, default is 42.
-# 
+#
 EOT
 
 ($exit, $text) = getoutput( sub { pod2usage(
@@ -214,7 +225,7 @@ is ($exit, 0,                 "Exit status pod2usage with USAGE and verbose=99")
 ok (compare ($text, <<'EOT'), "Output test pod2usage with USAGE and verbose=99") or diag "Got:\n$text\n";
 #Usage:
 #    This is a test for CPAN#33020
-# 
+#
 EOT
 
 # test with self
@@ -238,13 +249,13 @@ ok (compare ($text, <<'EOT'), "Output test pod2usage with self") or diag "Got:\n
 #      pod2usage($exit_status);
 #
 #      pod2usage( { -message => $message_text ,
-#                   -exitval => $exit_status  ,  
-#                   -verbose => $verbose_level,  
+#                   -exitval => $exit_status  ,
+#                   -verbose => $verbose_level,
 #                   -output  => $filehandle } );
 #
 #      pod2usage(   -msg     => $message_text ,
-#                   -exitval => $exit_status  ,  
-#                   -verbose => $verbose_level,  
+#                   -exitval => $exit_status  ,
+#                   -verbose => $verbose_level,
 #                   -output  => $filehandle   );
 #
 #      pod2usage(   -verbose => 2,
@@ -323,6 +334,58 @@ ok (compare ($text, <<'EOT'), "Output test pod2usage with subheadings in OPTIONS
 #    from the values by whitespace or the "=" character.
 #
 EOT
+
+# test various use cases of calling pod2usage to increase coverage
+($exit, $text) = getoutput( sub {
+  pod2usage({ -input => $pod_file2,
+            -exitval => 3, -verbose => 0 }) } );
+is ($exit, 3,                 "Exit status pod2usage with hash options");
+like ($text, qr/^\s*$/s, "Output test pod2usage with hash options is empty") or diag "Got:\n$text\n";
+
+# call with single string option
+($exit, $text) = getoutput( sub {
+  pod2usage('Just print this') } );
+is ($exit, 2,                 "Exit status pod2usage with single string option");
+like ($text, qr/^#Just print this/, "Output test pod2usage with single string options has first line") or diag "Got:\n$text\n";
+
+# call with search path and relative file name
+my ($file, $dir) = fileparse($0);
+($exit, $text) = getoutput( sub {
+  pod2usage({ -input => $file, -pathlist => [ $dir ], -exit => 0, -verbose => 2 } ) } );
+is ($exit, 0,                 "Exit status pod2usage with relative path");
+like ($text, qr/frobnicate - do what I mean/, "Output test pod2usage with relative path works OK") or diag "Got:\n$text\n";
+
+# trigger specific perldoc case
+# ...and one coverage line
+{ no warnings;
+  *Pod::Usage::initialize = sub { 1; };
+}
+
+SKIP: {
+    my $perldoc = $^X . 'doc';
+    skip "Missing perldoc binary", 2 unless -x $perldoc;
+
+    my $out = qx[$perldoc 2>&1] || '';
+    skip "Need perl-doc package", 2 if $out =~ qr[You need to install the perl-doc package to use this program];
+
+    ($exit, $text) = getoutput( sub {
+        require Pod::Perldoc;
+      my $devnull = File::Spec->devnull();
+      open(SAVE_STDOUT, '>&', \*STDOUT);
+      open(STDOUT, '>', $devnull);
+      pod2usage({ -verbose => 2, -input => $0, -output => \*STDOUT, -exit => 0, -message => 'Special perldoc case', -perldocopt => '-i' });
+      open(STDOUT, '>&', \*SAVE_STDOUT);
+      } );
+    is ($exit, 0,                 "Exit status pod2usage with special perldoc case");
+    # output went to devnull
+    like ($text, qr/^\s*$/s, "Output test pod2usage with special perldoc case") or diag "Got:\n$text\n";
+
+}
+
+# bad regexp syntax
+($exit, $text) = getoutput( sub { pod2usage( -verbose => 99, -sections => 'DESCRIPTION{BLAH') } );
+like ($text, qr/Bad regular expression/, "Output test pod2usage with bad section regexp");
+
 } # end SKIP
 
 __END__
diff --git a/cpan/Pod-Usage/t/pod/selectheaders.pl b/cpan/Pod-Usage/t/pod/selectheaders.pl
index d0b557f475..1fd6a7f98b 100644
--- a/cpan/Pod-Usage/t/pod/selectheaders.pl
+++ b/cpan/Pod-Usage/t/pod/selectheaders.pl
@@ -1,5 +1,6 @@
 #!/usr/bin/perl -w
 use strict;
+use warnings;
 use Pod::Usage;
 
 my $h2 = shift @ARGV || '.*';
diff --git a/cpan/Pod-Usage/t/pod/selectheaders.t b/cpan/Pod-Usage/t/pod/selectheaders.t
index ff138a38ce..0badc2fe24 100644
--- a/cpan/Pod-Usage/t/pod/selectheaders.t
+++ b/cpan/Pod-Usage/t/pod/selectheaders.t
@@ -1,5 +1,8 @@
 use Test::More tests => 2;
 
+use strict;
+use warnings;
+
 my $blib = $ENV{PERL_CORE} ? '-I../../lib' : '-Mblib';
 
 my $pl = $0;
diff --git a/cpan/Pod-Usage/t/pod/selectsections.pl b/cpan/Pod-Usage/t/pod/selectsections.pl
index 0f1ad828d4..29c4d267c0 100644
--- a/cpan/Pod-Usage/t/pod/selectsections.pl
+++ b/cpan/Pod-Usage/t/pod/selectsections.pl
@@ -1,4 +1,7 @@
 #!/usr/bin/env perl
+use strict;
+use warnings;
+
 use Pod::Usage;
 
 my @tests = (
diff --git a/cpan/Pod-Usage/t/pod/selectsections.t b/cpan/Pod-Usage/t/pod/selectsections.t
index d71c487956..c6c1801aa0 100644
--- a/cpan/Pod-Usage/t/pod/selectsections.t
+++ b/cpan/Pod-Usage/t/pod/selectsections.t
@@ -1,5 +1,8 @@
 use Test::More tests => 2;
 
+use strict;
+use warnings;
+
 my $blib = $ENV{PERL_CORE} ? '-I../../lib' : '-Mblib';
 
 my $pl = $0;
diff --git a/cpan/Pod-Usage/t/pod/testp2pt.pl b/cpan/Pod-Usage/t/pod/testp2pt.pl
index 1ba802259e..f33fd4ae55 100644
--- a/cpan/Pod-Usage/t/pod/testp2pt.pl
+++ b/cpan/Pod-Usage/t/pod/testp2pt.pl
@@ -10,7 +10,7 @@ BEGIN {
    my $THISDIR = abs_path(dirname $0);
    unshift @INC, $THISDIR;
    require "testcmp.pl";
-   import TestCompare;
+   TestCompare->import;
    # RT#130418: previous use of dirname() was failing on VMS
    $PARENTDIR = File::Spec->catdir($THISDIR, File::Spec->updir());
    push @INC, map { File::Spec->catdir($_, 'lib') } ($PARENTDIR, $THISDIR);