summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Pod/Usage.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Pod/Usage.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Usage.pm126
1 files changed, 98 insertions, 28 deletions
diff --git a/Master/tlpkg/tlperl/lib/Pod/Usage.pm b/Master/tlpkg/tlperl/lib/Pod/Usage.pm
index bb8e60f05b0..cc4f2e1e4fd 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Usage.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Usage.pm
@@ -1,8 +1,9 @@
#############################################################################
# Pod/Usage.pm -- print usage messages for the running script.
#
-# Copyright (C) 1996-2000 by Bradford Appleton. All rights reserved.
-# This file is part of "PodParser". PodParser is free software;
+# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved.
+# Copyright (c) 2001-2016 by Marek Rouchal.
+# This file is part of "Pod-Usage". Pod-Usage is free software;
# you can redistribute it and/or modify it under the same terms
# as Perl itself.
#############################################################################
@@ -11,7 +12,7 @@ package Pod::Usage;
use strict;
use vars qw($VERSION @ISA @EXPORT);
-$VERSION = '1.64'; ## Current version of this package
+$VERSION = '1.68'; ## Current version of this package
require 5.006; ## requires this Perl version or later
#use diagnostics;
@@ -128,7 +129,8 @@ sub pod2usage {
}
## Check for perldoc
- my $progpath = File::Spec->catfile($Config{scriptdirexp}
+ my $progpath = $opts{'-perldoc'} ? $opts{'-perldoc'} :
+ File::Spec->catfile($Config{scriptdirexp}
|| $Config{scriptdir}, 'perldoc');
my $version = sprintf("%vd",$^V);
@@ -148,7 +150,15 @@ sub pod2usage {
if(defined $opts{-input} && $opts{-input} =~ /^\s*(\S.*?)\s*$/) {
# the perldocs back to 5.005 should all have -F
# without -F there are warnings in -T scripts
- system($progpath, '-F', $1);
+ my $f = $1;
+ my @perldoc_cmd = ($progpath);
+ if ($opts{'-perldocopt'}) {
+ $opts{'-perldocopt'} =~ s/^\s+|\s+$//g;
+ push @perldoc_cmd, split(/\s+/, $opts{'-perldocopt'});
+ }
+ push @perldoc_cmd, ('-F', $f);
+ unshift @perldoc_cmd, $opts{'-perlcmd'} if $opts{'-perlcmd'};
+ system(@perldoc_cmd);
if($?) {
# RT16091: fall back to more if perldoc failed
system(($Config{pager} || $ENV{PAGER} || '/bin/more'), $1);
@@ -263,10 +273,13 @@ sub select {
# Override Pod::Text->seq_i to return just "arg", not "*arg*".
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] }
# 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.
-# Note that the below is very, very specific to Pod::Text.
+# Note that the below is very, very specific to Pod::Text and Pod::Simple.
sub _handle_element_end {
my ($self, $element) = @_;
if ($element eq 'head1') {
@@ -278,6 +291,8 @@ sub _handle_element_end {
my $idx = $1 - 1;
$self->{USAGE_HEADINGS} = [] unless($self->{USAGE_HEADINGS});
$self->{USAGE_HEADINGS}->[$idx] = $$self{PENDING}[-1][1];
+ # we have to get rid of the lower headings
+ splice(@{$self->{USAGE_HEADINGS}},$idx+1);
}
if ($element =~ /^head\d+$/) {
$$self{USAGE_SKIPPING} = 1;
@@ -312,7 +327,7 @@ sub _handle_element_end {
$$self{PENDING}[-1][1] = $_;
}
}
- if ($$self{USAGE_SKIPPING} && $element !~ m/^over-/) {
+ if ($$self{USAGE_SKIPPING} && $element !~ m/^over-|^[BCFILSZ]$/) {
pop @{ $$self{PENDING} };
} else {
$self->SUPER::_handle_element_end($element);
@@ -383,10 +398,15 @@ Pod::Usage - print a usage message from embedded pod documentation
pod2usage( -msg => $message_text ,
-exitval => $exit_status ,
-verbose => $verbose_level,
- -output => $filehandle );
+ -output => $filehandle );
pod2usage( -verbose => 2,
- -noperldoc => 1 )
+ -noperldoc => 1 );
+
+ pod2usage( -verbose => 2,
+ -perlcmd => $path_to_perl,
+ -perldoc => $path_to_perldoc,
+ -perldocopt => $perldoc_options );
=head1 ARGUMENTS
@@ -418,49 +438,73 @@ keys:
=over 4
-=item C<-message>
+=item C<-message> I<string>
-=item C<-msg>
+=item C<-msg> I<string>
The text of a message to print immediately prior to printing the
program's usage message.
-=item C<-exitval>
+=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
indicate that control should simply be returned without
terminating the invoking process.
-=item C<-verbose>
+=item C<-verbose> I<value>
-The desired level of "verboseness" to use when printing the usage
-message. If the corresponding value is 0, then only the "SYNOPSIS"
-section of the pod documentation is printed. If the corresponding 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.
+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>.
The special verbosity level 99 requires to also specify the -sections
parameter; then these sections are extracted and printed.
-=item C<-sections>
+=item C<-sections> I<spec>
+
+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
+output to particular subsections only, e.g.:
-A string representing a selection list for sections to be printed
-when -verbose is set to 99, e.g. C<"NAME|SYNOPSIS|DESCRIPTION|VERSION">.
+ "DESCRIPTION/Algorithm"
+
+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"
+
+will print any C<=head2 Caveats> section (only) within any of the three
+C<=head1> sections.
Alternatively, an array reference of section specifications can be used:
- pod2usage(-verbose => 99,
- -sections => [ qw(fred fred/subsection) ] );
+ pod2usage(-verbose => 99, -sections => [
+ qw(DESCRIPTION DESCRIPTION/Introduction) ] );
+
+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.
-=item C<-output>
+=item C<-output> I<handle>
A reference to a filehandle, or the pathname of a file to which the
usage message should be written. The default is C<\*STDERR> unless the
exit value is less than 2 (in which case the default is C<\*STDOUT>).
-=item C<-input>
+=item C<-input> I<handle>
A reference to a filehandle, or the pathname of a file from which the
invoking script's pod documentation should be read. It defaults to the
@@ -472,7 +516,7 @@ that module's POD, you can use this:
use Pod::Find qw(pod_where);
pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
-=item C<-pathlist>
+=item C<-pathlist> I<string>
A list of directory paths. If the input file does not exist, then it
will be searched for in the given directory list (in the order the
@@ -490,17 +534,43 @@ 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.
+=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
+which should run L<perldoc>.
+
+=item C<-perldoc> I<path-to-perldoc>
+
+By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is
+specified. In case L<perldoc> is not installed where the L<perl> interpreter
+thinks it is (see L<Config>), the -perldoc option may be used to supply
+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
+string may contain several, space-separated options.
+
=back
=head2 Formatting base class
-The default text formatter is L<Pod::Text>. The base class for Pod::Usage can
+The default text formatter is L<Pod::Text>. The base class for Pod::Usage can
be defined by pre-setting C<$Pod::Usage::Formatter> I<before>
loading Pod::Usage, e.g.:
BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
use Pod::Usage qw(pod2usage);
+Pod::Usage uses L<Pod::Simple>'s _handle_element_end() method to implement
+the section selection, and in case of verbosity < 2 it down-cases the
+all-caps headings to first capital letter and rest lowercase, and adds
+a colon/newline at the end of the headings, for better readability. Same for
+verbosity = 99.
+
=head2 Pass-through options
The following options are passed through to the underlying text formatter.