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