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 by Russ Allbery <rra@stanford.edu>
  41 #
  42 # This program is free software; you can 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 use vars qw($ID);
  56
  57 # Take an initial pass through our options, looking for one of the form
  58 # -<number>.  We turn that into -w <number> for compatibility with the
  59 # original pod2text script.
  60 for (my $i = 0; $i < @ARGV; $i++) {
  61     last if $ARGV[$i] =~ /^--$/;
  62     if ($ARGV[$i] =~ /^-(\d+)$/) {
  63         splice (@ARGV, $i++, 1, '-w', $1);
  64     }
  65 }
  66
  67 # Parse our options.  Use the same names as Pod::Text for simplicity, and
  68 # default to sentence boundaries turned off for compatibility.
  69 my %options;
  70 $options{termcap} = -t STDOUT;
  71 $options{sentence} = 0;
  72 Getopt::Long::config ('bundling');
  73 GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i',
  74             'loose|l', 'sentence|s', 'termcap|t!', 'width|w=i') or exit 1;
  75 pod2usage (1) if $options{help};
  76
  77 # Figure out what formatter we're going to use.  -c overrides -t.
  78 my $formatter = 'Pod::Text';
  79 if ($options{color}) {
  80     $formatter = 'Pod::Text::Color';
  81     eval { require Term::ANSIColor };
  82     if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
  83     require Pod::Text::Color;
  84 } elsif ($options{termcap}) {
  85     $formatter = 'Pod::Text::Termcap';
  86     require Pod::Text::Termcap;
  87 }
  88 delete @options{'color', 'termcap'};
  89
  90 # Initialize and run the formatter.
  91 my $parser = $formatter->new (%options);
  92 $parser->parse_from_file (@ARGV);
  93
  94 __END__
  95
  96 =head1 NAME
  97
  98 pod2text - Convert POD data to formatted ASCII text
  99
 100 =head1 SYNOPSIS
 101
 102 pod2text [B<-aclst>] [B<-i> I<indent>] [B<-w> I<width>] [I<input> [I<output>]]
 103
 104 pod2text B<-h>
 105
 106 =head1 DESCRIPTION
 107
 108 B<pod2text> is a front-end for Pod::Text and its subclasses.  It uses them
 109 to generate formatted ASCII text from POD source.  It can optionally use
 110 either termcap sequences or ANSI color escape sequences to format the text.
 111
 112 I<input> is the file to read for POD source (the POD can be embedded in
 113 code).  If I<input> isn't given, it defaults to STDIN.  I<output>, if given,
 114 is the file to which to write the formatted output.  If I<output> isn't
 115 given, the formatted output is written to STDOUT.
 116
 117 B<pod2text> defaults to trying to use Pod::Text::Termcap if STDOUT is a tty.
 118 To explicitly say not to attempt termcap escape sequences, use
 119 B<--notermcap>.
 120
 121 =head1 OPTIONS
 122
 123 =over 4
 124
 125 =item B<-a>, B<--alt>
 126
 127 Use an alternate output format that, among other things, uses a different
 128 heading style and marks C<=item> entries with a colon in the left margin.
 129
 130 =item B<-c>, B<--color>
 131
 132 Format the output with ANSI color escape sequences.  Using this option
 133 requires that Term::ANSIColor be installed on your system.
 134
 135 =item B<-i> I<indent>, B<--indent=>I<indent>
 136
 137 Set the number of spaces to indent regular text, and the default indentation
 138 for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
 139
 140 =item B<-h>, B<--help>
 141
 142 Print out usage information and exit.
 143
 144 =item B<-l>, B<--loose>
 145
 146 Print a blank line after a C<=head1> heading.  Normally, no blank line is
 147 printed after C<=head1>, although one is still printed after C<=head2>,
 148 because this is the expected formatting for manual pages; if you're
 149 formatting arbitrary text documents, using this option is recommended.
 150
 151 =item B<-s>, B<--sentence>
 152
 153 Assume each sentence ends with two spaces and try to preserve that spacing.
 154 Without this option, all consecutive whitespace in non-verbatim paragraphs
 155 is compressed into a single space.
 156
 157 =item B<-t>, B<--termcap>
 158
 159 Try to determine the width of the screen and the bold and underline
 160 sequences for the terminal from termcap, and use that information in
 161 formatting the output.  Output will be wrapped at two columns less than the
 162 width of your terminal device.  Using this option requires that your system
 163 have a termcap file somewhere where Term::Cap can find it.  With this
 164 option, the output of B<pod2text> will contain terminal control sequences
 165 for your current terminal type.
 166
 167 =item B<-w>, B<--width=>I<width>, B<->I<width>
 168
 169 The column at which to wrap text on the right-hand side.  Defaults to 76,
 170 unless B<-t> is given, in which case it's two columns less than the width of
 171 your terminal device.
 172
 173 =back
 174
 175 =head1 DIAGNOSTICS
 176
 177 If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for
 178 information about what those errors might mean.  Internally, it can also
 179 produce the following diagnostics:
 180
 181 =over 4
 182
 183 =item -c (--color) requires Term::ANSIColor be installed
 184
 185 (F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
 186 loaded.
 187
 188 =item Unknown option: %s
 189
 190 (F) An unknown command line option was given.
 191
 192 =back
 193
 194 In addition, other L<Getopt::Long|Getopt::Long> error messages may result
 195 from invalid command-line options.
 196
 197 =head1 ENVIRONMENT
 198
 199 =over 4
 200
 201 =item COLUMNS
 202
 203 If B<-t> is given, B<pod2text> will take the current width of your screen
 204 from this environment variable, if available.  It overrides terminal width
 205 information in TERMCAP.
 206
 207 =item TERMCAP
 208
 209 If B<-t> is given, B<pod2text> will use the contents of this environment
 210 variable if available to determine the correct formatting sequences for your
 211 current terminal device.
 212
 213 =back
 214
 215 =head1 SEE ALSO
 216
 217 L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>,
 218 L<Pod::Text::Termcap|Pod::Text::Termcap>, L<Pod::Parser|Pod::Parser>
 219
 220 =head1 AUTHOR
 221
 222 Russ Allbery E<lt>rra@stanford.eduE<gt>.
 223
 224 =cut
 225 !NO!SUBS!
 226
 227 close OUT or die "Can't close $file: $!";
 228 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
 229 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
 230 chdir $origdir;