diff options
Diffstat (limited to 'lib/Pod/Usage.pm')
| -rw-r--r-- | lib/Pod/Usage.pm | 38 |
1 files changed, 31 insertions, 7 deletions
diff --git a/lib/Pod/Usage.pm b/lib/Pod/Usage.pm index 0827dcc4d2..c298e941f2 100644 --- a/lib/Pod/Usage.pm +++ b/lib/Pod/Usage.pm @@ -10,7 +10,7 @@ package Pod::Usage; use vars qw($VERSION); -$VERSION = 1.30; ## Current version of this package +$VERSION = 1.33; ## Current version of this package require 5.005; ## requires this Perl version or later =head1 NAME @@ -40,6 +40,9 @@ Pod::Usage, pod2usage() - print a usage message from embedded pod documentation -verbose => $verbose_level, -output => $filehandle ); + pod2usage( -verbose => 2, + -noperldoc => 1 ) + =head1 ARGUMENTS B<pod2usage> should be given either a single argument, or a list of @@ -94,7 +97,8 @@ is 1, then the "SYNOPSIS" section, along with any section entitled corresponding value is 2 or more then the entire manpage is printed. The special verbosity level 99 requires to also specify the -section -parameter; then these sections are extracted and printed. +parameter; then these sections are extracted (see L<Pod::Select>) +and printed. =item C<-section> @@ -123,6 +127,14 @@ to an array, or by a string of directory paths which use the same path separator as C<$ENV{PATH}> on your system (e.g., C<:> for Unix, C<;> for 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. + =back =head1 DESCRIPTION @@ -200,8 +212,8 @@ to C<STDOUT>, just in case the user wants to pipe the output to a pager =item * If program usage has been explicitly requested by the user, it is often -desirable to exit with a status of 1 (as opposed to 0) after issuing -the user-requested usage message. It is also desirable to give a +desireable to exit with a status of 1 (as opposed to 0) after issuing +the user-requested usage message. It is also desireable to give a more verbose description of program usage in this case. =back @@ -387,6 +399,11 @@ similar to the following: pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs"); +In the pathological case that a script is called via a relative path +I<and> the script itself changes the current working directory +(see L<perlfunc/chdir>) I<before> calling pod2usage, Pod::Usage will +fail even on robust platforms. Don't do that. + =head1 AUTHOR Please report bugs using L<http://rt.cpan.org>. @@ -433,7 +450,7 @@ BEGIN { ##--------------------------------- sub pod2usage { - local($_) = shift || ""; + local($_) = shift; my %opts; ## Collect arguments if (@_ > 0) { @@ -441,6 +458,9 @@ sub pod2usage { ## the user forgot to pass a reference to it. %opts = ($_, @_); } + elsif (!defined $_) { + $_ = ""; + } elsif (ref $_) { ## User passed a ref to a hash %opts = %{$_} if (ref($_) eq 'HASH'); @@ -503,7 +523,7 @@ sub pod2usage { ## Now create a pod reader and constrain it to the desired sections. my $parser = new Pod::Usage(USAGE_OPTIONS => \%opts); if ($opts{"-verbose"} == 0) { - $parser->select("SYNOPSIS"); + $parser->select('SYNOPSIS\s*'); } elsif ($opts{"-verbose"} == 1) { my $opt_re = '(?i)' . @@ -517,7 +537,8 @@ sub pod2usage { } ## Now translate the pod document and then exit with the desired status - if ( $opts{"-verbose"} >= 2 + if ( !$opts{"-noperldoc"} + and $opts{"-verbose"} >= 2 and !ref($opts{"-input"}) and $opts{"-output"} == \*STDOUT ) { @@ -562,6 +583,9 @@ sub select { } } +# Override Pod::Text->seq_i to return just "arg", not "*arg*". +sub seq_i { 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. # Note that the below is very, very specific to Pod::Text. |