Update Pod-Usage to CPAN version 1.63

  [DELTA]

1.63 (marekr)
- CPAN#85477: Module version not updated in last release
  ...fixed
- CPAN#85478: typo fixes
  ...corrected

4 files changed, 276 insertions, 3 deletions

diff --git a/cpan/Pod-Usage/lib/Pod/Usage.pm b/cpan/Pod-Usage/lib/Pod/Usage.pm
index 1c509cb7e4..f0dd8350f1 100644
--- a/cpan/Pod-Usage/lib/Pod/Usage.pm
+++ b/cpan/Pod-Usage/lib/Pod/Usage.pm
@@ -11,7 +11,7 @@ package Pod::Usage;
 use strict;
 
 use vars qw($VERSION @ISA @EXPORT);
-$VERSION = '1.61';  ## Current version of this package
+$VERSION = '1.63';  ## Current version of this package
 require  5.006;    ## requires this Perl version or later
 
 #use diagnostics;
@@ -93,7 +93,7 @@ sub pod2usage {
     ## Default the input file
     $opts{'-input'} = $0  unless (defined $opts{'-input'});
 
-    ## Look up input file in path if it doesnt exist.
+    ## Look up input file in path if it doesn't exist.
     unless ((ref $opts{'-input'}) || (-e $opts{'-input'})) {
         my $basename = $opts{'-input'};
         my $pathsep = ($^O =~ /^(?:dos|os2|MSWin32)$/i) ? ';'
@@ -341,7 +341,7 @@ sub preprocess_paragraph {
     my $self = shift;
     local $_ = shift;
     my $line = shift;
-    ## See if this is a heading and we arent printing the entire manpage.
+    ## See if this is a heading and we aren't printing the entire manpage.
     if (($self->{USAGE_OPTIONS}->{-verbose} < 2) && /^=head/) {
         ## Change the title of the SYNOPSIS section to USAGE
         s/^=head1\s+SYNOPSIS\s*$/=head1 USAGE/;
diff --git a/cpan/Pod-Usage/t/pod/pod2usage.t b/cpan/Pod-Usage/t/pod/pod2usage.t
new file mode 100644
index 0000000000..98788fc399
--- /dev/null
+++ b/cpan/Pod-Usage/t/pod/pod2usage.t
@@ -0,0 +1,18 @@
+BEGIN {

+   use File::Basename;

+   my $THISDIR = dirname $0;

+   unshift @INC, $THISDIR;

+   require "testp2pt.pl";

+   import TestPodIncPlainText;

+}

+

+my %options = map { $_ => 1 } @ARGV;  ## convert cmdline to options-hash

+my $passed  = testpodplaintext \%options, $0;

+exit( ($passed == 1) ? 0 : -1 )  unless $ENV{HARNESS_ACTIVE};

+

+

+__END__

+

+=include pod2usage.PL

+

+

diff --git a/cpan/Pod-Usage/t/pod/pod2usage.xr b/cpan/Pod-Usage/t/pod/pod2usage.xr
new file mode 100644
index 0000000000..ceac4f1f82
--- /dev/null
+++ b/cpan/Pod-Usage/t/pod/pod2usage.xr
@@ -0,0 +1,63 @@
+###### begin =include pod2usage.PL #####
+NAME
+    pod2usage - print usage messages from embedded pod docs in files
+
+SYNOPSIS
+    pod2usage   [-help] [-man] [-exit *exitval*] [-output *outfile*]
+                [-verbose *level*] [-pathlist *dirlist*] [-formatter
+                *module*] *file*
+
+OPTIONS AND ARGUMENTS
+    -help   Print a brief help message and exit.
+
+    -man    Print this command's manual page and exit.
+
+    -exit *exitval*
+            The exit status value to return.
+
+    -output *outfile*
+            The output file to print to. If the special names "-" or ">&1"
+            or ">&STDOUT" are used then standard output is used. If ">&2" or
+            ">&STDERR" is used then standard error is used.
+
+    -verbose *level*
+            The desired level of verbosity to use:
+
+                1 : print SYNOPSIS only
+                2 : print SYNOPSIS sections and any OPTIONS/ARGUMENTS sections
+                3 : print the entire manpage (similar to running pod2text)
+
+    -pathlist *dirlist*
+            Specifies one or more directories to search for the input file
+            if it was not supplied with an absolute path. Each directory
+            path in the given list should be separated by a ':' on Unix (';'
+            on MSWin32 and DOS).
+
+    -formatter *module*
+            Which text formatter to use. Default is the Pod::Text manpage,
+            or for very old Perl versions the Pod::PlainText manpage. An
+            alternative would be e.g. the Pod::Text::Termcap manpage.
+
+    *file*  The pathname of a file containing pod documentation to be output
+            in usage message format (defaults to standard input).
+
+DESCRIPTION
+    pod2usage will read the given input file looking for pod documentation
+    and will print the corresponding usage message. If no input file is
+    specified then standard input is read.
+
+    pod2usage invokes the pod2usage() function in the Pod::Usage module.
+    Please see the pod2usage() entry in the Pod::Usage manpage.
+
+SEE ALSO
+    the Pod::Usage manpage, the pod2text(1) manpage
+
+AUTHOR
+    Please report bugs using http://rt.cpan.org.
+
+    Brad Appleton <bradapp@enteract.com>
+
+    Based on code for pod2text(1) written by Tom Christiansen
+    <tchrist@mox.perl.com>
+
+###### end =include pod2usage.PL #####
diff --git a/cpan/Pod-Usage/t/pod/testp2pt.pl b/cpan/Pod-Usage/t/pod/testp2pt.pl
new file mode 100644
index 0000000000..5c17300b50
--- /dev/null
+++ b/cpan/Pod-Usage/t/pod/testp2pt.pl
@@ -0,0 +1,192 @@
+package TestPodIncPlainText;

+

+BEGIN {

+   use File::Basename;

+   use File::Spec;

+   use Cwd qw(abs_path);

+   push @INC, '..';

+   my $THISDIR = abs_path(dirname $0);

+   unshift @INC, $THISDIR;

+   require "testcmp.pl";

+   import TestCompare;

+   my $PARENTDIR = dirname $THISDIR;

+   push @INC, map { File::Spec->catfile($_, 'lib') } ($PARENTDIR, $THISDIR);

+}

+

+#use strict;

+#use diagnostics;

+use Carp;

+use Exporter;

+#use File::Compare;

+#use Cwd qw(abs_path);

+

+use vars qw($MYPKG @EXPORT @ISA);

+$MYPKG = eval { (caller)[0] };

+@EXPORT = qw(&testpodplaintext);

+BEGIN {

+    require Pod::PlainText;

+    @ISA = qw( Pod::PlainText );

+    require VMS::Filespec if $^O eq 'VMS';

+}

+

+## Hardcode settings for TERMCAP and COLUMNS so we can try to get

+## reproducible results between environments

+@ENV{qw(TERMCAP COLUMNS)} = ('co=76:do=^J', 76);

+

+sub catfile(@) { File::Spec->catfile(@_); }

+

+my $INSTDIR = abs_path(dirname $0);

+$INSTDIR = VMS::Filespec::unixpath($INSTDIR) if $^O eq 'VMS';

+$INSTDIR =~ s#/$## if $^O eq 'VMS';

+$INSTDIR =~ s#:$## if $^O eq 'MacOS';

+$INSTDIR = (dirname $INSTDIR) if (basename($INSTDIR) eq 'pod');

+$INSTDIR =~ s#:$## if $^O eq 'MacOS';

+$INSTDIR = (dirname $INSTDIR) if (basename($INSTDIR) eq 't');

+my @PODINCDIRS = ( catfile($INSTDIR, 'lib', 'Pod'),

+                   catfile($INSTDIR, 'scripts'),

+                   catfile($INSTDIR, 'pod'),

+                   catfile($INSTDIR, 't', 'pod')

+                 );

+

+# FIXME - we should make the core capable of finding utilities built in

+# locations in ext.

+push @PODINCDIRS, catfile((File::Spec->updir()) x 2, 'pod') if $ENV{PERL_CORE};

+

+## Find the path to the file to =include

+sub findinclude {

+    my $self    = shift;

+    my $incname = shift;

+

+    ## See if its already found w/out any "searching;

+    return  $incname if (-r $incname);

+

+    ## Need to search for it. Look in the following directories ...

+    ##   1. the directory containing this pod file

+    my $thispoddir = dirname $self->input_file;

+    ##   2. the parent directory of the above

+    my $parentdir  = dirname $thispoddir;

+    my @podincdirs = ($thispoddir, $parentdir, @PODINCDIRS);

+

+    for (@podincdirs) {

+       my $incfile = catfile($_, $incname);

+       return $incfile  if (-r $incfile);

+    }

+    warn("*** Can't find =include file $incname in @podincdirs\n");

+    return "";

+}

+

+sub command {

+    my $self = shift;

+    my ($cmd, $text, $line_num, $pod_para)  = @_;

+    $cmd     = ''  unless (defined $cmd);

+    local $_ = $text || '';

+    my $out_fh  = $self->output_handle;

+

+    ## Defer to the superclass for everything except '=include'

+    return  $self->SUPER::command(@_) unless ($cmd eq "include");

+

+    ## We have an '=include' command

+    my $incdebug = 1; ## debugging

+    my @incargs = split;

+    if (@incargs == 0) {

+        warn("*** No filename given for '=include'\n");

+        return;

+    }

+    my $incfile  = $self->findinclude(shift @incargs)  or  return;

+    my $incbase  = basename $incfile;

+    print $out_fh "###### begin =include $incbase #####\n"  if ($incdebug);

+    $self->parse_from_file( {-cutting => 1}, $incfile );

+    print $out_fh "###### end =include $incbase #####\n"    if ($incdebug);

+}

+

+sub begin_input {

+   $_[0]->{_INFILE} = VMS::Filespec::unixify($_[0]->{_INFILE}) if $^O eq 'VMS';

+}

+

+sub podinc2plaintext( $ $ ) {

+    my ($infile, $outfile) = @_;

+    local $_;

+    my $text_parser = $MYPKG->new;

+    $text_parser->parse_from_file($infile, $outfile);

+}

+

+sub testpodinc2plaintext( @ ) {

+   my %args = @_;

+   my $infile  = $args{'-In'}  || croak "No input file given!";

+   my $outfile = $args{'-Out'} || croak "No output file given!";

+   my $cmpfile = $args{'-Cmp'} || croak "No compare-result file given!";

+

+   my $different = '';

+   my $testname = basename $cmpfile, '.t', '.xr';

+

+   unless (-e $cmpfile) {

+      my $msg = "*** Can't find comparison file $cmpfile for testing $infile";

+      warn  "$msg\n";

+      return  $msg;

+   }

+

+   print "# Running testpodinc2plaintext for '$testname'...\n";

+   ## Compare the output against the expected result

+   podinc2plaintext($infile, $outfile);

+   if ( testcmp($outfile, $cmpfile) ) {

+       $different = "$outfile is different from $cmpfile";

+   }

+   else {

+       unlink($outfile);

+   }

+   return  $different;

+}

+

+sub testpodplaintext( @ ) {

+   my %opts = (ref $_[0] eq 'HASH') ? %{shift()} : ();

+   my @testpods = @_;

+   my ($testname, $testdir) = ("", "");

+   my ($podfile, $cmpfile) = ("", "");

+   my ($outfile, $errfile) = ("", "");

+   my $passes = 0;

+   my $failed = 0;

+   local $_;

+

+   print "1..", scalar @testpods, "\n"  unless ($opts{'-xrgen'});

+

+   for $podfile (@testpods) {

+      ($testname, $_) = fileparse($podfile);

+      $testdir ||=  $_;

+      $testname  =~ s/\.t$//;

+      $cmpfile   =  $testdir . $testname . '.xr';

+      $outfile   =  $testdir . $testname . '.OUT';

+

+      if ($opts{'-xrgen'}) {

+          if ($opts{'-force'} or ! -e $cmpfile) {

+             ## Create the comparison file

+             print "# Creating expected result for \"$testname\"" .

+                   " pod2plaintext test ...\n";

+             podinc2plaintext($podfile, $cmpfile);

+          }

+          else {

+             print "# File $cmpfile already exists" .

+                   " (use '-force' to regenerate it).\n";

+          }

+          next;

+      }

+

+      my $failmsg = testpodinc2plaintext

+                        -In  => $podfile,

+                        -Out => $outfile,

+                        -Cmp => $cmpfile;

+      if ($failmsg) {

+          ++$failed;

+          print "#\tFAILED. ($failmsg)\n";

+	  print "not ok ", $failed+$passes, "\n";

+      }

+      else {

+          ++$passes;

+          unlink($outfile);

+          print "#\tPASSED.\n";

+	  print "ok ", $failed+$passes, "\n";

+      }

+   }

+   return  $passes;

+}

+

+1;