X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fpod2text.PL;h=785a3f393f3333efd3f81339066fdded2b7929d4;hb=8269e00da02a2e0f107fbb8b4a78f0c4058f3587;hp=1402f0dbe9e2154d190a1e16cee7c998563a9cca;hpb=c07a80fdfe3926b5eb0585b674aa5d1f57b32ade;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/pod2text.PL b/pod/pod2text.PL index 1402f0d..785a3f3 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -2,6 +2,7 @@ use Config; use File::Basename qw(&basename &dirname); +use Cwd; # List explicitly here the variables you want Configure to # generate. Metaconfig only looks for shell variables, so you @@ -12,11 +13,10 @@ use File::Basename qw(&basename &dirname); # This forces PL files to create target in same directory as PL file. # This is so that make depend always knows where to find PL derivatives. -chdir(dirname($0)); -($file = basename($0)) =~ s/\.PL$//; -$file =~ s/\.pl$// - if ($Config{'osname'} eq 'VMS' or - $Config{'osname'} eq 'OS2'); # "case-forgiving" +$origdir = cwd; +chdir dirname($0); +$file = basename($0, '.PL'); +$file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; @@ -26,25 +26,262 @@ print "Extracting $file (with variable substitutions)\n"; # You can use $Config{...} to use Configure variables. print OUT <<"!GROK!THIS!"; -$Config{'startperl'} - eval 'exec perl -S \$0 "\$@"' - if 0; +$Config{startperl} + eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' + if \$running_under_some_shell; !GROK!THIS! # In the following, perl variables are not expanded during extraction. print OUT <<'!NO!SUBS!'; -use Pod::Text; +# pod2text -- Convert POD data to formatted ASCII text. +# +# Copyright 1999, 2000, 2001 by Russ Allbery +# +# 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, +# invoked by perldoc -t among other things. -if(@ARGV) { - pod2text($ARGV[0]); -} else { - pod2text("<&STDIN"); +require 5.004; + +use Getopt::Long qw(GetOptions); +use Pod::Text (); +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. +for (my $i = 0; $i < @ARGV; $i++) { + last if $ARGV[$i] =~ /^--$/; + if ($ARGV[$i] =~ /^-(\d+)$/) { + splice (@ARGV, $i++, 1, '-w', $1); + } } +# Insert -- into @ARGV before any single dash argument to hide it from +# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple +# does correctly). +my $stdin; +@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; + +# Parse our options. Use the same names as Pod::Text for simplicity, and +# default to sentence boundaries turned off for compatibility. +my %options; +$options{sentence} = 0; +Getopt::Long::config ('bundling'); +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. +my $formatter = 'Pod::Text'; +if ($options{color}) { + $formatter = 'Pod::Text::Color'; + eval { require Term::ANSIColor }; + if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" } + require Pod::Text::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', 'overstrike'}; + +# Initialize and run the formatter. +do { + my $parser = $formatter->new (%options); + my ($input, $output) = splice (@ARGV, 0, 2); + $parser->parse_file ($input, $output); + undef $parser; +} while (@ARGV); + +__END__ + +=head1 NAME + +pod2text - Convert POD data to formatted ASCII text + +=head1 SYNOPSIS + +pod2text [B<-aclost>] [B<--code>] [B<-i> I] S<[B<-q> I]> +S<[B<-w> I]> [I [I ...]] + +pod2text B<-h> + +=head1 DESCRIPTION + +B is a front-end for Pod::Text and its subclasses. It uses them +to generate formatted ASCII text from POD source. It can optionally use +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. 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 + +=over 4 + +=item B<-a>, B<--alt> + +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 +requires that Term::ANSIColor be installed on your system. + +=item B<-i> I, B<--indent=>I + +Set the number of spaces to indent regular text, and the default indentation +for C<=over> blocks. Defaults to 4 spaces if this option isn't given. + +=item B<-h>, B<--help> + +Print out usage information and exit. + +=item B<-l>, B<--loose> + +Print a blank line after a C<=head1> heading. Normally, no blank line is +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 +I is a single character, it is used as both the left and right +quote; if I is two characters, the first character is used as the +left quote and the second as the right quoted; and if I is four +characters, the first two are used as the left quote and the second two as +the right quote. + +I may also be set to the special value C, in which case no +quote marks are added around CE> text. + +=item B<-s>, B<--sentence> + +Assume each sentence ends with two spaces and try to preserve that spacing. +Without this option, all consecutive whitespace in non-verbatim paragraphs +is compressed into a single space. + +=item B<-t>, B<--termcap> + +Try to determine the width of the screen and the bold and underline +sequences for the terminal from termcap, and use that information in +formatting the output. Output will be wrapped at two columns less than the +width of your terminal device. Using this option requires that your system +have a termcap file somewhere where Term::Cap can find it and requires that +your system support termios. With this option, the output of B +will contain terminal control sequences for your current terminal type. + +=item B<-w>, B<--width=>I, B<->I + +The column at which to wrap text on the right-hand side. Defaults to 76, +unless B<-t> is given, in which case it's two columns less than the width of +your terminal device. + +=back + +=head1 DIAGNOSTICS + +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: + +=over 4 + +=item -c (--color) requires Term::ANSIColor be installed + +(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be +loaded. + +=item Unknown option: %s + +(F) An unknown command line option was given. + +=back + +In addition, other L error messages may result from invalid +command-line options. + +=head1 ENVIRONMENT + +=over 4 + +=item COLUMNS + +If B<-t> is given, B will take the current width of your screen +from this environment variable, if available. It overrides terminal width +information in TERMCAP. + +=item TERMCAP + +If B<-t> is given, B will use the contents of this environment +variable if available to determine the correct formatting sequences for your +current terminal device. + +=back + +=head1 SEE ALSO + +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 . + +=head1 COPYRIGHT AND LICENSE + +Copyright 1999, 2000, 2001, 2004 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! close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; +chdir $origdir;