extra code in pp_concat, Take 2
[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',
11f72409 81 'loose|l', 'margin|left-margin|m=i', 'overstrike|o',
82 'quotes|q=s', 'sentence|s', '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
11f72409 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
73849855 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
ab1f1d91 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
6055f9d4 190=item B<-s>, B<--sentence>
191
9741dab0 192Assume each sentence ends with two spaces and try to preserve that spacing.
6055f9d4 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
46bce7d0 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.
6055f9d4 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
9741dab0 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
6055f9d4 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
6055f9d4 254=head1 SEE ALSO
255
fd20da51 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.
6055f9d4 262
263=head1 AUTHOR
264
3c014959 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.
cb1a09d0 273
6055f9d4 274=cut
c07a80fd 275!NO!SUBS!
cb1a09d0 276
c07a80fd 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 ':';
3b5ca523 280chdir $origdir;