4 use File::Basename qw(&basename &dirname);
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
12 # to ensure Configure will look for $Config{startperl}.
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.
18 $file = basename($0, '.PL');
19 $file .= '.com' if $^O eq 'VMS';
21 open OUT,">$file" or die "Can't create $file: $!";
23 print "Extracting $file (with variable substitutions)\n";
25 # In this section, perl variables will be expanded during extraction.
26 # You can use $Config{...} to use Configure variables.
28 print OUT <<"!GROK!THIS!";
30 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
31 if \$running_under_some_shell;
34 # In the following, perl variables are not expanded during extraction.
36 print OUT <<'!NO!SUBS!';
38 # pod2text -- Convert POD data to formatted ASCII text.
40 # Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra@stanford.edu>
42 # This program is free software; you may redistribute it and/or modify it
43 # under the same terms as Perl itself.
45 # The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
46 # invoked by perldoc -t among other things.
50 use Getopt::Long qw(GetOptions);
52 use Pod::Usage qw(pod2usage);
56 # Silence -w warnings.
57 use vars qw($running_under_some_shell);
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);
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
73 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
75 # Parse our options. Use the same names as Pod::Text for simplicity, and
76 # default to sentence boundaries turned off for compatibility.
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', 'termcap|t', 'width|w=i') or exit 1;
83 pod2usage (1) if $options{help};
85 # Figure out what formatter we're going to use. -c overrides -t.
86 my $formatter = 'Pod::Text';
87 if ($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;
99 delete @options{'color', 'termcap', 'overstrike'};
101 # Initialize and run the formatter.
102 my $parser = $formatter->new (%options);
104 my ($input, $output) = splice (@ARGV, 0, 2);
105 $parser->parse_from_file ($input, $output);
112 pod2text - Convert POD data to formatted ASCII text
115 -aclost --alt Allbery
119 pod2text [B<-aclost>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
120 S<[B<-w> I<width>]> [I<input> [I<output> ...]]
126 B<pod2text> is a front-end for Pod::Text and its subclasses. It uses them
127 to generate formatted ASCII text from POD source. It can optionally use
128 either termcap sequences or ANSI color escape sequences to format the text.
130 I<input> is the file to read for POD source (the POD can be embedded in
131 code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if
132 given, is the file to which to write the formatted output. If I<output>
133 isn't given, the formatted output is written to C<STDOUT>. Several POD
134 files can be processed in the same B<pod2text> invocation (saving module
135 load and compile times) by providing multiple pairs of I<input> and
136 I<output> files on the command line.
142 =item B<-a>, B<--alt>
144 Use an alternate output format that, among other things, uses a different
145 heading style and marks C<=item> entries with a colon in the left margin.
149 Include any non-POD text from the input file in the output as well. Useful
150 for viewing code documented with POD blocks with the POD rendered and the
153 =item B<-c>, B<--color>
155 Format the output with ANSI color escape sequences. Using this option
156 requires that Term::ANSIColor be installed on your system.
158 =item B<-i> I<indent>, B<--indent=>I<indent>
160 Set the number of spaces to indent regular text, and the default indentation
161 for C<=over> blocks. Defaults to 4 spaces if this option isn't given.
163 =item B<-h>, B<--help>
165 Print out usage information and exit.
167 =item B<-l>, B<--loose>
169 Print a blank line after a C<=head1> heading. Normally, no blank line is
170 printed after C<=head1>, although one is still printed after C<=head2>,
171 because this is the expected formatting for manual pages; if you're
172 formatting arbitrary text documents, using this option is recommended.
174 =item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width>
176 The width of the left margin in spaces. Defaults to 0. This is the margin
177 for all text, including headings, not the amount by which regular text is
178 indented; for the latter, see B<-i> option.
180 =item B<-o>, B<--overstrike>
182 Format the output with overstrike printing. Bold text is rendered as
183 character, backspace, character. Italics and file names are rendered as
184 underscore, backspace, character. Many pagers, such as B<less>, know how
185 to convert this to bold or underlined text.
187 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
189 Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
190 I<quotes> is a single character, it is used as both the left and right
191 quote; if I<quotes> is two characters, the first character is used as the
192 left quote and the second as the right quoted; and if I<quotes> is four
193 characters, the first two are used as the left quote and the second two as
196 I<quotes> may also be set to the special value C<none>, in which case no
197 quote marks are added around CE<lt>> text.
199 =item B<-s>, B<--sentence>
201 Assume each sentence ends with two spaces and try to preserve that spacing.
202 Without this option, all consecutive whitespace in non-verbatim paragraphs
203 is compressed into a single space.
205 =item B<-t>, B<--termcap>
207 Try to determine the width of the screen and the bold and underline
208 sequences for the terminal from termcap, and use that information in
209 formatting the output. Output will be wrapped at two columns less than the
210 width of your terminal device. Using this option requires that your system
211 have a termcap file somewhere where Term::Cap can find it and requires that
212 your system support termios. With this option, the output of B<pod2text>
213 will contain terminal control sequences for your current terminal type.
215 =item B<-w>, B<--width=>I<width>, B<->I<width>
217 The column at which to wrap text on the right-hand side. Defaults to 76,
218 unless B<-t> is given, in which case it's two columns less than the width of
219 your terminal device.
225 If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for
226 information about what those errors might mean. Internally, it can also
227 produce the following diagnostics:
231 =item -c (--color) requires Term::ANSIColor be installed
233 (F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
236 =item Unknown option: %s
238 (F) An unknown command line option was given.
242 In addition, other L<Getopt::Long> error messages may result from invalid
243 command-line options.
251 If B<-t> is given, B<pod2text> will take the current width of your screen
252 from this environment variable, if available. It overrides terminal width
253 information in TERMCAP.
257 If B<-t> is given, B<pod2text> will use the contents of this environment
258 variable if available to determine the correct formatting sequences for your
259 current terminal device.
265 L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>,
266 L<Pod::Text::Termcap>, L<Pod::Simple>
268 The current version of this script is always available from its web site at
269 L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
270 Perl core distribution as of 5.6.0.
274 Russ Allbery <rra@stanford.edu>.
276 =head1 COPYRIGHT AND LICENSE
278 Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
281 This program is free software; you may redistribute it and/or modify it
282 under the same terms as Perl itself.
287 close OUT or die "Can't close $file: $!";
288 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
289 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';