X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fpod2text.PL;h=a978f717ad663a3fd0845f22df30a369aef37940;hb=8f20275887caedc32e165a1aa9890f861054dd9a;hp=54a22790a4e0ce37c648a52f5c8dff6850ec0d14;hpb=3c01495985c7c4b8f1b95ec88b49209869fdb517;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/pod2text.PL b/pod/pod2text.PL
index 54a2279..a978f71 100644
--- a/pod/pod2text.PL
+++ b/pod/pod2text.PL
@@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!';
 
 # pod2text -- Convert POD data to formatted ASCII text.
 #
-# Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -53,6 +53,9 @@ use Pod::Usage qw(pod2usage);
 
 use strict;
 
+# Silence -w warnings.
+use vars qw($running_under_some_shell);
+
 # Take an initial pass through our options, looking for one of the form
 # -<number>.  We turn that into -w <number> for compatibility with the
 # original pod2text script.
@@ -64,7 +67,7 @@ for (my $i = 0; $i < @ARGV; $i++) {
 }
 
 # Insert -- into @ARGV before any single dash argument to hide it from
-# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser
+# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple
 # does correctly).
 my $stdin;
 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
@@ -74,9 +77,9 @@ my $stdin;
 my %options;
 $options{sentence} = 0;
 Getopt::Long::config ('bundling');
-GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i',
-            'loose|l', 'overstrike|o', 'quotes|q=s', 'sentence|s',
-            'termcap|t', 'width|w=i') or exit 1;
+GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i',
+            'loose|l', 'margin|left-margin|m=i', 'overstrike|o',
+            'quotes|q=s', 'sentence|s', 'termcap|t', 'width|w=i') or exit 1;
 pod2usage (1) if $options{help};
 
 # Figure out what formatter we're going to use.  -c overrides -t.
@@ -97,7 +100,10 @@ delete @options{'color', 'termcap', 'overstrike'};
 
 # Initialize and run the formatter.
 my $parser = $formatter->new (%options);
-$parser->parse_from_file (@ARGV);
+do {
+    my ($input, $output) = splice (@ARGV, 0, 2);
+    $parser->parse_from_file ($input, $output);
+} while (@ARGV);
 
 __END__
 
@@ -107,8 +113,8 @@ pod2text - Convert POD data to formatted ASCII text
 
 =head1 SYNOPSIS
 
-pod2text [B<-aclost>] [B<-i> I<indent>] [B<-q> I<quotes>] [B<-w> I<width>]
-[I<input> [I<output>]]
+pod2text [B<-aclost>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
+S<[B<-w> I<width>]> [I<input> [I<output> ...]]
 
 pod2text B<-h>
 
@@ -121,7 +127,10 @@ either termcap sequences or ANSI color escape sequences to format the text.
 I<input> is the file to read for POD source (the POD can be embedded in
 code).  If I<input> isn't given, it defaults to STDIN.  I<output>, if given,
 is the file to which to write the formatted output.  If I<output> isn't
-given, the formatted output is written to STDOUT.
+given, the formatted output is written to STDOUT.  Several POD files can be
+processed in the same B<pod2text> invocation (saving module load and compile
+times) by providing multiple pairs of I<input> and I<output> files on the
+command line.
 
 =head1 OPTIONS
 
@@ -132,6 +141,12 @@ given, the formatted output is written to STDOUT.
 Use an alternate output format that, among other things, uses a different
 heading style and marks C<=item> entries with a colon in the left margin.
 
+=item B<--code>
+
+Include any non-POD text from the input file in the output as well.  Useful
+for viewing code documented with POD blocks with the POD rendered and the
+code left intact.
+
 =item B<-c>, B<--color>
 
 Format the output with ANSI color escape sequences.  Using this option
@@ -153,6 +168,12 @@ printed after C<=head1>, although one is still printed after C<=head2>,
 because this is the expected formatting for manual pages; if you're
 formatting arbitrary text documents, using this option is recommended.
 
+=item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width>
+
+The width of the left margin in spaces.  Defaults to 0.  This is the margin
+for all text, including headings, not the amount by which regular text is
+indented; for the latter, see B<-i> option.
+
 =item B<-o>, B<--overstrike>
 
 Format the output with overstruck printing.  Bold text is rendered as
@@ -198,7 +219,7 @@ your terminal device.
 
 =head1 DIAGNOSTICS
 
-If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for
+If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for
 information about what those errors might mean.  Internally, it can also
 produce the following diagnostics:
 
@@ -215,8 +236,8 @@ loaded.
 
 =back
 
-In addition, other L<Getopt::Long|Getopt::Long> error messages may result
-from invalid command-line options.
+In addition, other L<Getopt::Long> error messages may result from invalid
+command-line options.
 
 =head1 ENVIRONMENT
 
@@ -238,8 +259,12 @@ current terminal device.
 
 =head1 SEE ALSO
 
-L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>,
-L<Pod::Text::Termcap|Pod::Text::Termcap>, L<Pod::Parser|Pod::Parser>
+L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>,
+L<Pod::Text::Termcap>, L<Pod::Simple>
+
+The current version of this script is always available from its web site at
+L<http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
+Perl core distribution as of 5.6.0.
 
 =head1 AUTHOR
 
@@ -247,7 +272,7 @@ Russ Allbery <rra@stanford.edu>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.