X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fpod2text.PL;h=a978f717ad663a3fd0845f22df30a369aef37940;hb=8f20275887caedc32e165a1aa9890f861054dd9a;hp=b4965cb00ffdaa78b4b9b5cd3ced3fa03061903f;hpb=ab1f1d91718d3ea14ab3ebc4fc169516f655f3d7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/pod2text.PL b/pod/pod2text.PL index b4965cb..a978f71 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -37,9 +37,9 @@ print OUT <<'!NO!SUBS!'; # pod2text -- Convert POD data to formatted ASCII text. # -# Copyright 1999, 2000 by Russ Allbery +# Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery # -# This program is free software; you can redistribute it and/or modify it +# This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. # # The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color, @@ -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 # -. We turn that into -w 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', '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. @@ -89,12 +92,18 @@ if ($options{color}) { } elsif ($options{termcap}) { $formatter = 'Pod::Text::Termcap'; require Pod::Text::Termcap; +} elsif ($options{overstrike}) { + $formatter = 'Pod::Text::Overstrike'; + require Pod::Text::Overstrike; } -delete @options{'color', 'termcap'}; +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__ @@ -104,8 +113,8 @@ pod2text - Convert POD data to formatted ASCII text =head1 SYNOPSIS -pod2text [B<-aclst>] [B<-i> I] [B<-q> I] [B<-w> I] -[I [I]] +pod2text [B<-aclost>] [B<--code>] [B<-i> I] S<[B<-q> I]> +S<[B<-w> I]> [I [I ...]] pod2text B<-h> @@ -118,7 +127,10 @@ either termcap sequences or ANSI color escape sequences to format the text. I is the file to read for POD source (the POD can be embedded in code). If I isn't given, it defaults to STDIN. I, if given, is the file to which to write the formatted output. If I 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 invocation (saving module load and compile +times) by providing multiple pairs of I and I files on the +command line. =head1 OPTIONS @@ -129,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 @@ -150,6 +168,19 @@ 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, B<--left-margin>=I, B<--margin>=I + +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 +character, backspace, character. Italics and file names are rendered as +underscore, backspace, character. Many pagers, such as B, know how +to convert this to bold or underlined text. + =item B<-q> I, B<--quotes>=I Sets the quote marks used to surround CE> text to I. If @@ -188,7 +219,7 @@ your terminal device. =head1 DIAGNOSTICS -If B fails with errors, see L and L for +If B fails with errors, see L and L for information about what those errors might mean. Internally, it can also produce the following diagnostics: @@ -205,8 +236,8 @@ loaded. =back -In addition, other L error messages may result -from invalid command-line options. +In addition, other L error messages may result from invalid +command-line options. =head1 ENVIRONMENT @@ -228,12 +259,23 @@ current terminal device. =head1 SEE ALSO -L, L, -L, L +L, L, L, +L, L + +The current version of this script is always available from its web site at +L. It is also part of the +Perl core distribution as of 5.6.0. =head1 AUTHOR -Russ Allbery Erra@stanford.eduE. +Russ Allbery . + +=head1 COPYRIGHT AND LICENSE + +Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery . + +This program is free software; you may redistribute it and/or modify it +under the same terms as Perl itself. =cut !NO!SUBS!