pod/pod2text.PL

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