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 $ID = q$Id: pod2text,v 0.1 1999/06/13 02:42:18 eagle Exp $;
  39
  40 # pod2text -- Convert POD data to formatted ASCII text.
  41 #            Copyright 1999 by Russ Allbery <rra@stanford.edu>
  42 #
  43 # This program is free software; you can redistribute it and/or modify it
  44 # under the same terms as Perl itself.
  45 #
  46 # The driver script for Pod::Text, Pod::Text::Termcap, and
  47 # Pod::Text::Color, invoked by perldoc -t among other things.
  48
  49 require 5.004;
  50
  51 use Getopt::Long qw(GetOptions);
  52 use Pod::Text ();
  53 use Pod::Usage qw(pod2usage);
  54
  55 use strict;
  56 use vars qw($ID);
  57
  58 # Take an initial pass through our options, looking for one of the form
  59 # -<number>.  We turn that into -w <number> for compatibility with the
  60 # original pod2text script.
  61 for (my $i = 0; $i < @ARGV; $i++) {
  62     last if $ARGV[$i] =~ /^--$/;
  63     if ($ARGV[$i] =~ /^-(\d+)$/) {
  64         splice (@ARGV, $i++, 1, '-w', $1);
  65     }
  66 }
  67
  68 # Parse our options.  Use the same names as Pod::Text for simplicity,
  69 # and default to sentence boundaries turned off for compatibility.
  70 my %options;
  71 $options{termcap} = -t STDOUT;
  72 $options{sentence} = 0;
  73 Getopt::Long::config ('bundling');
  74 GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i',
  75             'loose|l', 'sentence|s', 'termcap|t!', 'width|w=i') or exit 1;
  76 pod2usage (1) if $options{help};
  77
  78 # Figure out what formatter we're going to use.  -c overrides -t.
  79 my $formatter = 'Pod::Text';
  80 if ($options{color}) {
  81     $formatter = 'Pod::Text::Color';
  82     require Pod::Text::Color;
  83 } elsif ($options{termcap}) {
  84     $formatter = 'Pod::Text::Termcap';
  85     require Pod::Text::Termcap;
  86 }
  87 delete @options{'color', 'termcap'};
  88
  89 # Initialize and run the formatter.
  90 my $parser = $formatter->new (%options);
  91 $parser->parse_from_file (@ARGV);
  92
  93 __END__
  94
  95 =head1 NAME
  96
  97 pod2text - Convert POD data to formatted ASCII text
  98
  99 =head1 SYNOPSIS
 100
 101 pod2text [B<-aclst>] [B<-i> I<indent>] [B<-w> I<width>] [I<input> [I<output>]]
 102
 103 pod2text B<-h>
 104
 105 =head1 DESCRIPTION
 106
 107 B<pod2text> is a front-end for Pod::Text and its subclasses.  It uses
 108 them to generate formatted ASCII text from POD source.  It can optionally
 109 use either termcap sequences or ANSI color escape sequences to format the
 110 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 =head1 OPTIONS
 118
 119 =over 4
 120
 121 =item B<-a>, B<--alt>
 122
 123 Use an alternate output format that, among other things, uses a different
 124 heading style and marks C<=item> entries with a colon in the left margin.
 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<-l>, B<--loose>
 137
 138 Print a blank line after a C<=head1> heading.  Normally, no blank line is
 139 printed after C<=head1>, although one is still printed after C<=head2>.
 140 This is the default because it's the expected formatting for manual pages;
 141 if you're formatting arbitrary text documents, using this option is
 142 recommended.
 143
 144 =item B<-s>, B<--sentence>
 145
 146 Assume each sentence ends in two spaces and try to preserve that spacing.
 147 Without this option, all consecutive whitespace in non-verbatim paragraphs
 148 is compressed into a single space.
 149
 150 =item B<-t>, B<--termcap>
 151
 152 Try to determine the width of the screen and the bold and underline
 153 sequences for the terminal from termcap, and use that information in
 154 formatting the output.  Output will be wrapped at two columns less than the
 155 width of your terminal device.  Using this option requires that your system
 156 have a termcap file somewhere where Term::Cap can find it.  With this
 157 option, the output of B<pod2text> will contain terminal control sequences for
 158 your current terminal type.
 159
 160 =item B<-w>, B<--width=>I<width>, B<->I<width>
 161
 162 The column at which to wrap text on the right-hand side.  Defaults to 76,
 163 unless B<-t> is given, in which case it's two columns less than the width of
 164 your terminal device.
 165
 166 =back
 167
 168 =head1 ENVIRONMENT
 169
 170 =over 4
 171
 172 =item COLUMNS
 173
 174 If B<-t> is given, B<pod2text> will take the current width of your screen
 175 from this environment variable, if available.  It overrides terminal width
 176 information in TERMCAP.
 177
 178 =item TERMCAP
 179
 180 If B<-t> is given, B<pod2text> will use the contents of this environment
 181 variable if available to determine the correct formatting sequences for your
 182 current terminal device.
 183
 184 =back
 185
 186 =head1 DIAGNOSTICS
 187
 188 If B<pod2text> fails with POD errors, see L<Pod::Text> and
 189 L<Pod::Parser> for information about what those errors might mean.
 190
 191 =head1 SEE ALSO
 192
 193 L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>,
 194 L<Pod::Text::Termcap|Pod::Text::Termcap>, L<Pod::Parser|Pod::Parser>
 195
 196 =head1 AUTHOR
 197
 198 Russ Allbery E<lt>rra@stanford.eduE<gt>.
 199
 200 =cut
 201 !NO!SUBS!
 202
 203 close OUT or die "Can't close $file: $!";
 204 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
 205 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
 206 chdir $origdir;