1#!/usr/local/bin/perl 2 3use Config; 4use File::Basename qw(&basename &dirname); 5use 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; 17chdir dirname($0); 18$file = basename($0, '.PL'); 19$file .= '.com' if $^O eq 'VMS'; 20 21open OUT,">$file" or die "Can't create $file: $!"; 22 23print "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 28print 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 36print OUT <<'!NO!SUBS!'; 37 38# pod2text -- Convert POD data to formatted ASCII text. 39# 40# Copyright 1999, 2000, 2001 by 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 48require 5.004; 49 50use Getopt::Long qw(GetOptions); 51use Pod::Text (); 52use Pod::Usage qw(pod2usage); 53 54use strict; 55 56# Silence -w warnings. 57use 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. 62for (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::Parser 71# does correctly). 72my $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. 77my %options; 78$options{sentence} = 0; 79Getopt::Long::config ('bundling'); 80GetOptions (\%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', 'termcap|t', 'width|w=i') or exit 1; 83pod2usage (1) if $options{help}; 84 85# Figure out what formatter we're going to use. -c overrides -t. 86my $formatter = 'Pod::Text'; 87if ($options{color}) { 88 $formatter = 'Pod::Text::Color'; 89 eval { require Term::ANSIColor }; 90 if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" } 91 require Pod::Text::Color; 92} elsif ($options{termcap}) { 93 $formatter = 'Pod::Text::Termcap'; 94 require Pod::Text::Termcap; 95} elsif ($options{overstrike}) { 96 $formatter = 'Pod::Text::Overstrike'; 97 require Pod::Text::Overstrike; 98} 99delete @options{'color', 'termcap', 'overstrike'}; 100 101# Initialize and run the formatter. 102my $parser = $formatter->new (%options); 103$parser->parse_from_file (@ARGV); 104 105__END__ 106 107=head1 NAME 108 109pod2text - Convert POD data to formatted ASCII text 110 111=head1 SYNOPSIS 112 113pod2text [B<-aclost>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]> 114S<[B<-w> I<width>]> [I<input> [I<output>]] 115 116pod2text B<-h> 117 118=head1 DESCRIPTION 119 120B<pod2text> is a front-end for Pod::Text and its subclasses. It uses them 121to generate formatted ASCII text from POD source. It can optionally use 122either termcap sequences or ANSI color escape sequences to format the text. 123 124I<input> is the file to read for POD source (the POD can be embedded in 125code). If I<input> isn't given, it defaults to STDIN. I<output>, if given, 126is the file to which to write the formatted output. If I<output> isn't 127given, the formatted output is written to STDOUT. 128 129=head1 OPTIONS 130 131=over 4 132 133=item B<-a>, B<--alt> 134 135Use an alternate output format that, among other things, uses a different 136heading style and marks C<=item> entries with a colon in the left margin. 137 138=item B<--code> 139 140Include any non-POD text from the input file in the output as well. Useful 141for viewing code documented with POD blocks with the POD rendered and the 142code left intact. 143 144=item B<-c>, B<--color> 145 146Format the output with ANSI color escape sequences. Using this option 147requires that Term::ANSIColor be installed on your system. 148 149=item B<-i> I<indent>, B<--indent=>I<indent> 150 151Set the number of spaces to indent regular text, and the default indentation 152for C<=over> blocks. Defaults to 4 spaces if this option isn't given. 153 154=item B<-h>, B<--help> 155 156Print out usage information and exit. 157 158=item B<-l>, B<--loose> 159 160Print a blank line after a C<=head1> heading. Normally, no blank line is 161printed after C<=head1>, although one is still printed after C<=head2>, 162because this is the expected formatting for manual pages; if you're 163formatting arbitrary text documents, using this option is recommended. 164 165=item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width> 166 167The width of the left margin in spaces. Defaults to 0. This is the margin 168for all text, including headings, not the amount by which regular text is 169indented; for the latter, see B<-i> option. 170 171=item B<-o>, B<--overstrike> 172 173Format the output with overstruck printing. Bold text is rendered as 174character, backspace, character. Italics and file names are rendered as 175underscore, backspace, character. Many pagers, such as B<less>, know how 176to convert this to bold or underlined text. 177 178=item B<-q> I<quotes>, B<--quotes>=I<quotes> 179 180Sets the quote marks used to surround CE<lt>> text to I<quotes>. If 181I<quotes> is a single character, it is used as both the left and right 182quote; if I<quotes> is two characters, the first character is used as the 183left quote and the second as the right quoted; and if I<quotes> is four 184characters, the first two are used as the left quote and the second two as 185the right quote. 186 187I<quotes> may also be set to the special value C<none>, in which case no 188quote marks are added around CE<lt>> text. 189 190=item B<-s>, B<--sentence> 191 192Assume each sentence ends with two spaces and try to preserve that spacing. 193Without this option, all consecutive whitespace in non-verbatim paragraphs 194is compressed into a single space. 195 196=item B<-t>, B<--termcap> 197 198Try to determine the width of the screen and the bold and underline 199sequences for the terminal from termcap, and use that information in 200formatting the output. Output will be wrapped at two columns less than the 201width of your terminal device. Using this option requires that your system 202have a termcap file somewhere where Term::Cap can find it and requires that 203your system support termios. With this option, the output of B<pod2text> 204will contain terminal control sequences for your current terminal type. 205 206=item B<-w>, B<--width=>I<width>, B<->I<width> 207 208The column at which to wrap text on the right-hand side. Defaults to 76, 209unless B<-t> is given, in which case it's two columns less than the width of 210your terminal device. 211 212=back 213 214=head1 DIAGNOSTICS 215 216If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for 217information about what those errors might mean. Internally, it can also 218produce the following diagnostics: 219 220=over 4 221 222=item -c (--color) requires Term::ANSIColor be installed 223 224(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be 225loaded. 226 227=item Unknown option: %s 228 229(F) An unknown command line option was given. 230 231=back 232 233In addition, other L<Getopt::Long|Getopt::Long> error messages may result 234from invalid command-line options. 235 236=head1 ENVIRONMENT 237 238=over 4 239 240=item COLUMNS 241 242If B<-t> is given, B<pod2text> will take the current width of your screen 243from this environment variable, if available. It overrides terminal width 244information in TERMCAP. 245 246=item TERMCAP 247 248If B<-t> is given, B<pod2text> will use the contents of this environment 249variable if available to determine the correct formatting sequences for your 250current terminal device. 251 252=back 253 254=head1 SEE ALSO 255 256L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>, 257L<Pod::Text::Termcap>, L<Pod::Parser> 258 259The current version of this script is always available from its web site at 260L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 261Perl core distribution as of 5.6.0. 262 263=head1 AUTHOR 264 265Russ Allbery <rra@stanford.edu>. 266 267=head1 COPYRIGHT AND LICENSE 268 269Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>. 270 271This program is free software; you may redistribute it and/or modify it 272under the same terms as Perl itself. 273 274=cut 275!NO!SUBS! 276 277close OUT or die "Can't close $file: $!"; 278chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; 279exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; 280chdir $origdir; 281