local-lib5/bin/pod2text

   1 #!/usr/bin/perl
   2
   3 eval 'exec /usr/bin/perl  -S $0 ${1+"$@"}'
   4     if 0; # not running under some shell
   5     eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
   6         if $running_under_some_shell;
   7
   8 # pod2text -- Convert POD data to formatted ASCII text.
   9 #
  10 # Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra@stanford.edu>
  11 #
  12 # This program is free software; you may redistribute it and/or modify it
  13 # under the same terms as Perl itself.
  14 #
  15 # The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
  16 # invoked by perldoc -t among other things.
  17
  18 require 5.004;
  19
  20 use Getopt::Long qw(GetOptions);
  21 use Pod::Text ();
  22 use Pod::Usage qw(pod2usage);
  23
  24 use strict;
  25
  26 # Silence -w warnings.
  27 use vars qw($running_under_some_shell);
  28
  29 # Take an initial pass through our options, looking for one of the form
  30 # -<number>.  We turn that into -w <number> for compatibility with the
  31 # original pod2text script.
  32 for (my $i = 0; $i < @ARGV; $i++) {
  33     last if $ARGV[$i] =~ /^--$/;
  34     if ($ARGV[$i] =~ /^-(\d+)$/) {
  35         splice (@ARGV, $i++, 1, '-w', $1);
  36     }
  37 }
  38
  39 # Insert -- into @ARGV before any single dash argument to hide it from
  40 # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple
  41 # does correctly).
  42 my $stdin;
  43 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
  44
  45 # Parse our options.  Use the same names as Pod::Text for simplicity, and
  46 # default to sentence boundaries turned off for compatibility.
  47 my %options;
  48 $options{sentence} = 0;
  49 Getopt::Long::config ('bundling');
  50 GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i',
  51             'loose|l', 'margin|left-margin|m=i', 'overstrike|o',
  52             'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t', 'utf8|u',
  53             'width|w=i')
  54     or exit 1;
  55 pod2usage (1) if $options{help};
  56
  57 # Figure out what formatter we're going to use.  -c overrides -t.
  58 my $formatter = 'Pod::Text';
  59 if ($options{color}) {
  60     $formatter = 'Pod::Text::Color';
  61     eval { require Term::ANSIColor };
  62     if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
  63     require Pod::Text::Color;
  64 } elsif ($options{termcap}) {
  65     $formatter = 'Pod::Text::Termcap';
  66     require Pod::Text::Termcap;
  67 } elsif ($options{overstrike}) {
  68     $formatter = 'Pod::Text::Overstrike';
  69     require Pod::Text::Overstrike;
  70 }
  71 delete @options{'color', 'termcap', 'overstrike'};
  72
  73 # Initialize and run the formatter.
  74 my $parser = $formatter->new (%options);
  75 do {
  76     my ($input, $output) = splice (@ARGV, 0, 2);
  77     $parser->parse_from_file ($input, $output);
  78 } while (@ARGV);
  79
  80 __END__
  81
  82 =head1 NAME
  83
  84 pod2text - Convert POD data to formatted ASCII text
  85
  86 =for stopwords
  87 -aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8
  88 UTF-8
  89
  90 =head1 SYNOPSIS
  91
  92 pod2text [B<-aclostu>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
  93     [B<--stderr>] S<[B<-w> I<width>]> [I<input> [I<output> ...]]
  94
  95 pod2text B<-h>
  96
  97 =head1 DESCRIPTION
  98
  99 B<pod2text> is a front-end for Pod::Text and its subclasses.  It uses them
 100 to generate formatted ASCII text from POD source.  It can optionally use
 101 either termcap sequences or ANSI color escape sequences to format the text.
 102
 103 I<input> is the file to read for POD source (the POD can be embedded in
 104 code).  If I<input> isn't given, it defaults to C<STDIN>.  I<output>, if
 105 given, is the file to which to write the formatted output.  If I<output>
 106 isn't given, the formatted output is written to C<STDOUT>.  Several POD
 107 files can be processed in the same B<pod2text> invocation (saving module
 108 load and compile times) by providing multiple pairs of I<input> and
 109 I<output> files on the command line.
 110
 111 =head1 OPTIONS
 112
 113 =over 4
 114
 115 =item B<-a>, B<--alt>
 116
 117 Use an alternate output format that, among other things, uses a different
 118 heading style and marks C<=item> entries with a colon in the left margin.
 119
 120 =item B<--code>
 121
 122 Include any non-POD text from the input file in the output as well.  Useful
 123 for viewing code documented with POD blocks with the POD rendered and the
 124 code left intact.
 125
 126 =item B<-c>, B<--color>
 127
 128 Format the output with ANSI color escape sequences.  Using this option
 129 requires that Term::ANSIColor be installed on your system.
 130
 131 =item B<-i> I<indent>, B<--indent=>I<indent>
 132
 133 Set the number of spaces to indent regular text, and the default indentation
 134 for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
 135
 136 =item B<-h>, B<--help>
 137
 138 Print out usage information and exit.
 139
 140 =item B<-l>, B<--loose>
 141
 142 Print a blank line after a C<=head1> heading.  Normally, no blank line is
 143 printed after C<=head1>, although one is still printed after C<=head2>,
 144 because this is the expected formatting for manual pages; if you're
 145 formatting arbitrary text documents, using this option is recommended.
 146
 147 =item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width>
 148
 149 The width of the left margin in spaces.  Defaults to 0.  This is the margin
 150 for all text, including headings, not the amount by which regular text is
 151 indented; for the latter, see B<-i> option.
 152
 153 =item B<-o>, B<--overstrike>
 154
 155 Format the output with overstrike printing.  Bold text is rendered as
 156 character, backspace, character.  Italics and file names are rendered as
 157 underscore, backspace, character.  Many pagers, such as B<less>, know how
 158 to convert this to bold or underlined text.
 159
 160 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
 161
 162 Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
 163 I<quotes> is a single character, it is used as both the left and right
 164 quote; if I<quotes> is two characters, the first character is used as the
 165 left quote and the second as the right quoted; and if I<quotes> is four
 166 characters, the first two are used as the left quote and the second two as
 167 the right quote.
 168
 169 I<quotes> may also be set to the special value C<none>, in which case no
 170 quote marks are added around CE<lt>> text.
 171
 172 =item B<-s>, B<--sentence>
 173
 174 Assume each sentence ends with two spaces and try to preserve that spacing.
 175 Without this option, all consecutive whitespace in non-verbatim paragraphs
 176 is compressed into a single space.
 177
 178 =item B<--stderr>
 179
 180 By default, B<pod2text> puts any errors detected in the POD input in a POD
 181 ERRORS section in the output manual page.  If B<--stderr> is given, errors
 182 are sent to standard error instead and the POD ERRORS section is
 183 suppressed.
 184
 185 =item B<-t>, B<--termcap>
 186
 187 Try to determine the width of the screen and the bold and underline
 188 sequences for the terminal from termcap, and use that information in
 189 formatting the output.  Output will be wrapped at two columns less than the
 190 width of your terminal device.  Using this option requires that your system
 191 have a termcap file somewhere where Term::Cap can find it and requires that
 192 your system support termios.  With this option, the output of B<pod2text>
 193 will contain terminal control sequences for your current terminal type.
 194
 195 =item B<-u>, B<--utf8>
 196
 197 By default, B<pod2text> tries to use the same output encoding as its input
 198 encoding (to be backward-compatible with older versions).  This option
 199 says to instead force the output encoding to UTF-8.
 200
 201 Be aware that, when using this option, the input encoding of your POD
 202 source must be properly declared unless it is US-ASCII or Latin-1.  POD
 203 input without an C<=encoding> command will be assumed to be in Latin-1,
 204 and if it's actually in UTF-8, the output will be double-encoded.  See
 205 L<perlpod(1)> for more information on the C<=encoding> command.
 206
 207 =item B<-w>, B<--width=>I<width>, B<->I<width>
 208
 209 The column at which to wrap text on the right-hand side.  Defaults to 76,
 210 unless B<-t> is given, in which case it's two columns less than the width of
 211 your terminal device.
 212
 213 =back
 214
 215 =head1 DIAGNOSTICS
 216
 217 If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for
 218 information about what those errors might mean.  Internally, it can also
 219 produce the following diagnostics:
 220
 221 =over 4
 222
 223 =item -c (--color) requires Term::ANSIColor be installed
 224
 225 (F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
 226 loaded.
 227
 228 =item Unknown option: %s
 229
 230 (F) An unknown command line option was given.
 231
 232 =back
 233
 234 In addition, other L<Getopt::Long> error messages may result from invalid
 235 command-line options.
 236
 237 =head1 ENVIRONMENT
 238
 239 =over 4
 240
 241 =item COLUMNS
 242
 243 If B<-t> is given, B<pod2text> will take the current width of your screen
 244 from this environment variable, if available.  It overrides terminal width
 245 information in TERMCAP.
 246
 247 =item TERMCAP
 248
 249 If B<-t> is given, B<pod2text> will use the contents of this environment
 250 variable if available to determine the correct formatting sequences for your
 251 current terminal device.
 252
 253 =back
 254
 255 =head1 SEE ALSO
 256
 257 L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>,
 258 L<Pod::Text::Termcap>, L<Pod::Simple>, L<perlpod(1)>
 259
 260 The current version of this script is always available from its web site at
 261 L<http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
 262 Perl core distribution as of 5.6.0.
 263
 264 =head1 AUTHOR
 265
 266 Russ Allbery <rra@stanford.edu>.
 267
 268 =head1 COPYRIGHT AND LICENSE
 269
 270 Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
 271 <rra@stanford.edu>.
 272
 273 This program is free software; you may redistribute it and/or modify it
 274 under the same terms as Perl itself.
 275
 276 =cut