This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Pod-Usage to v1.70
authorNicolas R <atoomic@cpan.org>
Tue, 18 Aug 2020 15:20:17 +0000 (09:20 -0600)
committerℕicolas ℝ <nicolas@atoomic.org>
Tue, 18 Aug 2020 17:32:10 +0000 (11:32 -0600)
Customized patch to t/pod/testp2pt.pl is now applied upstream
and part of the 1.70 release.

References: 88e4265ca263642612277ef33dd08ded69e4e4c5
Upstream-URL: https://rt.cpan.org/Ticket/Display.html?id=130418

Porting/Maintainers.pl
cpan/Pod-Usage/lib/Pod/Usage.pm
cpan/Pod-Usage/scripts/pod2usage.PL
cpan/Pod-Usage/t/pod/pod2usage.xr
cpan/Pod-Usage/t/pod/pod2usage2.t
cpan/Pod-Usage/t/pod/testp2pt.pl

index 2543c86..9dc7a6d 100755 (executable)
@@ -951,11 +951,8 @@ use File::Glob qw(:case);
     },
 
     'Pod::Usage' => {
-        'DISTRIBUTION' => 'MAREKR/Pod-Usage-1.69.tar.gz',
+        'DISTRIBUTION' => 'MAREKR/Pod-Usage-1.70.tar.gz',
         'FILES'        => q[cpan/Pod-Usage],
-        'CUSTOMIZED'   => [
-            't/pod/testp2pt.pl',
-        ],
     },
 
     'podlators' => {
index 8f79850..fe5e555 100644 (file)
@@ -12,7 +12,7 @@ package Pod::Usage;
 use strict;
 
 use vars qw($VERSION @ISA @EXPORT);
-$VERSION = '1.69';  ## Current version of this package
+$VERSION = '1.70';  ## Current version of this package
 require  5.006;    ## requires this Perl version or later
 
 #use diagnostics;
@@ -130,8 +130,8 @@ sub pod2usage {
 
     ## Check for perldoc
     my $progpath = $opts{'-perldoc'} ? $opts{'-perldoc'} :
-        File::Spec->catfile($Config{scriptdirexp} 
-       || $Config{scriptdir}, 'perldoc');
+        File::Spec->catfile($Config{scriptdirexp} || $Config{scriptdir},
+            'perldoc');
 
     my $version = sprintf("%vd",$^V);
     if ($Config{versiononly} and $Config{startperl} =~ /\Q$version\E$/ ) {
@@ -159,9 +159,17 @@ sub pod2usage {
         push @perldoc_cmd, ('-F', $f);
          unshift @perldoc_cmd, $opts{'-perlcmd'} if $opts{'-perlcmd'};
          system(@perldoc_cmd);
+         # RT16091: fall back to more if perldoc failed
          if($?) {
-           # RT16091: fall back to more if perldoc failed
-           system(($Config{pager} || $ENV{PAGER} || '/bin/more'), $1);
+           # RT131844: prefer PAGER env
+           my $pager = $ENV{PAGER} || $Config{pager};
+           if(defined($pager) && length($pager)) {
+             my $cmd = $pager . ' ' . ($^O =~ /win/i ? qq("$f") : quotemeta($f));
+             system($cmd);
+           } else {
+             # the most humble fallback; should work (at least) on *nix and Win
+             system('more', $f);
+           }
          }
        } else {
          croak "Unspecified input file or insecure argument.\n";
@@ -275,7 +283,12 @@ sub select {
 sub seq_i { return $_[1] }
 # Override Pod::Text->cmd_i to return just "arg", not "*arg*".
 # newer version based on Pod::Simple
-sub cmd_i { return $_[2] }
+sub cmd_i {
+ my $self = shift;
+ # RT121489: highlighting should be there with Termcap
+ return $self->SUPER::cmd_i(@_) if $self->isa('Pod::Text::Termcap');
+ return $_[1];
+}
 
 # This overrides the Pod::Text method to do something very akin to what
 # Pod::Select did as well as the work done below by preprocess_paragraph.
@@ -379,7 +392,7 @@ Pod::Usage - print a usage message from embedded pod documentation
 
 =head1 SYNOPSIS
 
-  use Pod::Usage
+  use Pod::Usage;
 
   my $message_text  = "This text precedes the usage message.";
   my $exit_status   = 2;          ## The exit status to use
@@ -484,7 +497,7 @@ This will output only the C<=head2 Algorithm> heading and content within
 the C<=head1 DESCRIPTION> section. The regexp binding is stronger than the
 section separator, such that e.g.:
 
-  "DESCRIPTION|OPTIONS|ENVIORNMENT/Caveats"
+  "DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats"
 
 will print any C<=head2 Caveats> section (only) within any of the three
 C<=head1> sections.
@@ -876,6 +889,10 @@ Brad Appleton E<lt>bradapp@enteract.comE<gt>
 Based on code for B<Pod::Text::pod2text()> written by
 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
 
+=head1 LICENSE
+
+Pod::Usage (the distribution) is licensed under the same terms as Perl.
+
 =head1 ACKNOWLEDGMENTS
 
 rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
index 4661718..a51df22 100644 (file)
@@ -120,7 +120,9 @@ This option assumes that the formatter (see above) understands the option
 =item I<file>
 
 The pathname of a file containing pod documentation to be output in
-usage message format (defaults to standard input).
+usage message format. If omitted, standard input is read - but the
+output is then formatted with L<Pod::Text> only - unless a specific
+formatter has been specified with B<-formatter>.
 
 =back
 
@@ -135,7 +137,8 @@ module. Please see L<Pod::Usage/pod2usage()>.
 
 =head1 SEE ALSO
 
-L<Pod::Usage>, L<pod2text(1)>
+L<Pod::Usage>, L<pod2text>, L<Pod::Text>, L<Pod::Text::Termcap>,
+L<perldoc>
 
 =head1 AUTHOR
 
@@ -174,14 +177,13 @@ pod2usage(VERBOSE => 2)  if ($options{man});
 ## Dont default to STDIN if connected to a terminal
 pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
 
-@ARGV = ('-')  unless (@ARGV);
 if (@ARGV > 1) {
     print STDERR "pod2usage: Too many filenames given\n\n";
     pod2usage(2);
 }
 
 my %usage = ();
-$usage{-input}    = shift(@ARGV);
+$usage{-input}    = shift(@ARGV) || \*STDIN;
 $usage{-exitval}  = $options{'exit'}      if (defined $options{'exit'});
 $usage{-output}   = $options{'output'}    if (defined $options{'output'});
 $usage{-verbose}  = $options{'verbose'}   if (defined $options{'verbose'});
index 7460a6d..43e811e 100644 (file)
@@ -42,7 +42,10 @@ OPTIONS AND ARGUMENTS
             the option "utf8". It turns on generation of utf8 output.
 
     *file*  The pathname of a file containing pod documentation to be output
-            in usage message format (defaults to standard input).
+            in usage message format. If omitted, standard input is read -
+            but the output is then formatted with the Pod::Text manpage only
+            - unless a specific formatter has been specified with
+            -formatter.
 
 DESCRIPTION
     pod2usage will read the given input file looking for pod documentation
@@ -53,7 +56,8 @@ DESCRIPTION
     Please see the pod2usage() entry in the Pod::Usage manpage.
 
 SEE ALSO
-    the Pod::Usage manpage, the pod2text(1) manpage
+    the Pod::Usage manpage, the pod2text manpage, the Pod::Text manpage, the
+    Pod::Text::Termcap manpage, the perldoc manpage
 
 AUTHOR
     Please report bugs using http://rt.cpan.org.
index 7eb5402..a6552c5 100644 (file)
@@ -226,7 +226,7 @@ $text =~ s{#Using.*/blib.*\n}{}; # older blib's emit something to STDERR
 is ($exit, 0,                 "Exit status pod2usage with self");
 ok (compare ($text, <<'EOT'), "Output test pod2usage with self") or diag "Got:\n$text\n";
 #Usage:
-#      use Pod::Usage
+#      use Pod::Usage;
 #
 #      my $message_text  = "This text precedes the usage message.";
 #      my $exit_status   = 2;          ## The exit status to use
index 7205753..1ba8022 100644 (file)
@@ -11,8 +11,9 @@ BEGIN {
    unshift @INC, $THISDIR;
    require "testcmp.pl";
    import TestCompare;
+   # RT#130418: previous use of dirname() was failing on VMS
    $PARENTDIR = File::Spec->catdir($THISDIR, File::Spec->updir());
-   push @INC, map { File::Spec->catfile($_, 'lib') } ($PARENTDIR, $THISDIR);
+   push @INC, map { File::Spec->catdir($_, 'lib') } ($PARENTDIR, $THISDIR);
 }
 
 #use strict;
@@ -27,8 +28,8 @@ $MYPKG = eval { (caller)[0] };
 @EXPORT = qw(&testpodplaintext);
 BEGIN {
     # we want this for testing only
-    unshift(@INC, File::Spec->catfile($PARENTDIR, 'inc'));
-print "INC=@INC\n";
+    unshift(@INC, File::Spec->catdir($PARENTDIR, 'inc'));
+    #print "INC=@INC\n";
 
     require Pod::PlainText;
     @ISA = qw( Pod::PlainText );
@@ -39,7 +40,7 @@ print "INC=@INC\n";
 ## reproducible results between environments
 @ENV{qw(TERMCAP COLUMNS)} = ('co=76:do=^J', 76);
 
-sub catfile(@) { File::Spec->catfile(@_); }
+sub catdir(@) { File::Spec->catdir(@_); }
 
 my $INSTDIR = abs_path(dirname $0);
 $INSTDIR = VMS::Filespec::unixpath($INSTDIR) if $^O eq 'VMS';
@@ -48,15 +49,15 @@ $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')
+my @PODINCDIRS = ( catdir($INSTDIR, 'lib', 'Pod'),
+                   catdir($INSTDIR, 'scripts'),
+                   catdir($INSTDIR, 'pod'),
+                   catdir($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};
+push @PODINCDIRS, catdir((File::Spec->updir()) x 2, 'pod') if $ENV{PERL_CORE};
 
 ## Find the path to the file to =include
 sub findinclude {
@@ -74,7 +75,7 @@ sub findinclude {
     my @podincdirs = ($thispoddir, $parentdir, @PODINCDIRS);
 
     for (@podincdirs) {
-       my $incfile = catfile($_, $incname);
+       my $incfile = File::Spec->catfile($_, $incname);
        return $incfile  if (-r $incfile);
     }
     warn("*** Can't find =include file $incname in @podincdirs\n");