Update Changes.
[p5sagit/p5-mst-13.2.git] / pod / pod2text.PL
CommitLineData
cb1a09d0 1#!/usr/local/bin/perl
2
c07a80fd 3use Config;
4use File::Basename qw(&basename &dirname);
3b5ca523 5use Cwd;
cb1a09d0 6
c07a80fd 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}.
cb1a09d0 13
3b5ca523 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);
44a8e56a 18$file = basename($0, '.PL');
774d564b 19$file .= '.com' if $^O eq 'VMS';
cb1a09d0 20
c07a80fd 21open OUT,">$file" or die "Can't create $file: $!";
cb1a09d0 22
c07a80fd 23print "Extracting $file (with variable substitutions)\n";
cb1a09d0 24
c07a80fd 25# In this section, perl variables will be expanded during extraction.
26# You can use $Config{...} to use Configure variables.
cb1a09d0 27
c07a80fd 28print OUT <<"!GROK!THIS!";
5f05dabc 29$Config{startperl}
30 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
9741dab0 31 if \$running_under_some_shell;
c07a80fd 32!GROK!THIS!
cb1a09d0 33
c07a80fd 34# In the following, perl variables are not expanded during extraction.
cb1a09d0 35
c07a80fd 36print OUT <<'!NO!SUBS!';
cb1a09d0 37
6055f9d4 38# pod2text -- Convert POD data to formatted ASCII text.
9741dab0 39#
59548eca 40# Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
6055f9d4 41#
3c014959 42# This program is free software; you may redistribute it and/or modify it
6055f9d4 43# under the same terms as Perl itself.
44#
9741dab0 45# The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
46# invoked by perldoc -t among other things.
6055f9d4 47
48require 5.004;
49
50use Getopt::Long qw(GetOptions);
51use Pod::Text ();
52use Pod::Usage qw(pod2usage);
53
54use strict;
6055f9d4 55
59548eca 56# Silence -w warnings.
57use vars qw($running_under_some_shell);
58
6055f9d4 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
46bce7d0 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
9741dab0 75# Parse our options. Use the same names as Pod::Text for simplicity, and
76# default to sentence boundaries turned off for compatibility.
6055f9d4 77my %options;
6055f9d4 78$options{sentence} = 0;
79Getopt::Long::config ('bundling');
59548eca 80GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i',
73849855 81 'loose|l', 'overstrike|o', 'quotes|q=s', 'sentence|s',
82 'termcap|t', 'width|w=i') or exit 1;
6055f9d4 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';
9741dab0 89 eval { require Term::ANSIColor };
90 if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
6055f9d4 91 require Pod::Text::Color;
92} elsif ($options{termcap}) {
93 $formatter = 'Pod::Text::Termcap';
94 require Pod::Text::Termcap;
73849855 95} elsif ($options{overstrike}) {
96 $formatter = 'Pod::Text::Overstrike';
97 require Pod::Text::Overstrike;
cb1a09d0 98}
73849855 99delete @options{'color', 'termcap', 'overstrike'};
6055f9d4 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
59548eca 113pod2text [B<-aclost>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
114S<[B<-w> I<width>]> [I<input> [I<output>]]
6055f9d4 115
116pod2text B<-h>
117
118=head1 DESCRIPTION
119
9741dab0 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.
6055f9d4 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
59548eca 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
6055f9d4 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
9741dab0 154=item B<-h>, B<--help>
155
156Print out usage information and exit.
157
6055f9d4 158=item B<-l>, B<--loose>
159
160Print a blank line after a C<=head1> heading. Normally, no blank line is
9741dab0 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.
6055f9d4 164
73849855 165=item B<-o>, B<--overstrike>
166
167Format the output with overstruck printing. Bold text is rendered as
168character, backspace, character. Italics and file names are rendered as
169underscore, backspace, character. Many pagers, such as B<less>, know how
170to convert this to bold or underlined text.
171
ab1f1d91 172=item B<-q> I<quotes>, B<--quotes>=I<quotes>
173
174Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
175I<quotes> is a single character, it is used as both the left and right
176quote; if I<quotes> is two characters, the first character is used as the
177left quote and the second as the right quoted; and if I<quotes> is four
178characters, the first two are used as the left quote and the second two as
179the right quote.
180
181I<quotes> may also be set to the special value C<none>, in which case no
182quote marks are added around CE<lt>> text.
183
6055f9d4 184=item B<-s>, B<--sentence>
185
9741dab0 186Assume each sentence ends with two spaces and try to preserve that spacing.
6055f9d4 187Without this option, all consecutive whitespace in non-verbatim paragraphs
188is compressed into a single space.
189
190=item B<-t>, B<--termcap>
191
192Try to determine the width of the screen and the bold and underline
193sequences for the terminal from termcap, and use that information in
194formatting the output. Output will be wrapped at two columns less than the
195width of your terminal device. Using this option requires that your system
46bce7d0 196have a termcap file somewhere where Term::Cap can find it and requires that
197your system support termios. With this option, the output of B<pod2text>
198will contain terminal control sequences for your current terminal type.
6055f9d4 199
200=item B<-w>, B<--width=>I<width>, B<->I<width>
201
202The column at which to wrap text on the right-hand side. Defaults to 76,
203unless B<-t> is given, in which case it's two columns less than the width of
204your terminal device.
205
206=back
207
9741dab0 208=head1 DIAGNOSTICS
209
210If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for
211information about what those errors might mean. Internally, it can also
212produce the following diagnostics:
213
214=over 4
215
216=item -c (--color) requires Term::ANSIColor be installed
217
218(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
219loaded.
220
221=item Unknown option: %s
222
223(F) An unknown command line option was given.
224
225=back
226
227In addition, other L<Getopt::Long|Getopt::Long> error messages may result
228from invalid command-line options.
229
6055f9d4 230=head1 ENVIRONMENT
231
232=over 4
233
234=item COLUMNS
235
236If B<-t> is given, B<pod2text> will take the current width of your screen
237from this environment variable, if available. It overrides terminal width
238information in TERMCAP.
239
240=item TERMCAP
241
242If B<-t> is given, B<pod2text> will use the contents of this environment
243variable if available to determine the correct formatting sequences for your
244current terminal device.
245
246=back
247
6055f9d4 248=head1 SEE ALSO
249
250L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>,
251L<Pod::Text::Termcap|Pod::Text::Termcap>, L<Pod::Parser|Pod::Parser>
252
253=head1 AUTHOR
254
3c014959 255Russ Allbery <rra@stanford.edu>.
256
257=head1 COPYRIGHT AND LICENSE
258
259Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>.
260
261This program is free software; you may redistribute it and/or modify it
262under the same terms as Perl itself.
cb1a09d0 263
6055f9d4 264=cut
c07a80fd 265!NO!SUBS!
cb1a09d0 266
c07a80fd 267close OUT or die "Can't close $file: $!";
268chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
269exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
3b5ca523 270chdir $origdir;