f1acdbe744f74cc2978a2714050ba225416c220d
[perl.git] / cpan / podlators / scripts / pod2text.PL
1 #!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, 2010, 2012, 2013
41 #     Russ Allbery <rra@stanford.edu>
42 #
43 # This program is free software; you may redistribute it and/or modify it
44 # under the same terms as Perl itself.
45 #
46 # The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
47 # invoked by perldoc -t among other things.
48
49 require 5.004;
50
51 use Getopt::Long qw(GetOptions);
52 use Pod::Text ();
53 use Pod::Usage qw(pod2usage);
54
55 use strict;
56
57 # Clean up $0 for error reporting.
58 $0 =~ s%.*/%%;
59
60 # Take an initial pass through our options, looking for one of the form
61 # -<number>.  We turn that into -w <number> for compatibility with the
62 # original pod2text script.
63 for (my $i = 0; $i < @ARGV; $i++) {
64     last if $ARGV[$i] =~ /^--$/;
65     if ($ARGV[$i] =~ /^-(\d+)$/) {
66         splice (@ARGV, $i++, 1, '-w', $1);
67     }
68 }
69
70 # Insert -- into @ARGV before any single dash argument to hide it from
71 # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple
72 # does correctly).
73 my $stdin;
74 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
75
76 # Parse our options.  Use the same names as Pod::Text for simplicity, and
77 # default to sentence boundaries turned off for compatibility.
78 my %options;
79 $options{sentence} = 0;
80 Getopt::Long::config ('bundling');
81 GetOptions (\%options, 'alt|a', 'code', 'color|c', 'errors=s', 'help|h',
82             'indent|i=i', 'loose|l', 'margin|left-margin|m=i', 'nourls',
83             'overstrike|o', 'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t',
84             'utf8|u', 'width|w=i')
85     or exit 1;
86 pod2usage (1) if $options{help};
87
88 # Figure out what formatter we're going to use.  -c overrides -t.
89 my $formatter = 'Pod::Text';
90 if ($options{color}) {
91     $formatter = 'Pod::Text::Color';
92     eval { require Term::ANSIColor };
93     if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
94     require Pod::Text::Color;
95 } elsif ($options{termcap}) {
96     $formatter = 'Pod::Text::Termcap';
97     require Pod::Text::Termcap;
98 } elsif ($options{overstrike}) {
99     $formatter = 'Pod::Text::Overstrike';
100     require Pod::Text::Overstrike;
101 }
102 delete @options{'color', 'termcap', 'overstrike'};
103
104 # If neither stderr nor errors is set, default to errors = die.
105 if (!defined $options{stderr} && !defined $options{errors}) {
106     $options{errors} = 'die';
107 }
108
109 # Initialize and run the formatter.
110 my $parser = $formatter->new (%options);
111 my $status = 0;
112 do {
113     my ($input, $output) = splice (@ARGV, 0, 2);
114     $parser->parse_from_file ($input, $output);
115     if ($parser->{CONTENTLESS}) {
116         $status = 1;
117         warn "$0: unable to format $input\n";
118         if (defined ($output) and $output ne '-') {
119             unlink $output unless (-s $output);
120         }
121     }
122 } while (@ARGV);
123 exit $status;
124
125 __END__
126
127 =for stopwords
128 -aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8
129 UTF-8 subclasses --nourls
130
131 =head1 NAME
132
133 pod2text - Convert POD data to formatted ASCII text
134
135 =head1 SYNOPSIS
136
137 pod2text [B<-aclostu>] [B<--code>] [B<--errors>=I<style>] [B<-i> I<indent>]
138     S<[B<-q> I<quotes>]> [B<--nourls>] [B<--stderr>] S<[B<-w> I<width>]>
139     [I<input> [I<output> ...]]
140
141 pod2text B<-h>
142
143 =head1 DESCRIPTION
144
145 B<pod2text> is a front-end for Pod::Text and its subclasses.  It uses them
146 to generate formatted ASCII text from POD source.  It can optionally use
147 either termcap sequences or ANSI color escape sequences to format the text.
148
149 I<input> is the file to read for POD source (the POD can be embedded in
150 code).  If I<input> isn't given, it defaults to C<STDIN>.  I<output>, if
151 given, is the file to which to write the formatted output.  If I<output>
152 isn't given, the formatted output is written to C<STDOUT>.  Several POD
153 files can be processed in the same B<pod2text> invocation (saving module
154 load and compile times) by providing multiple pairs of I<input> and
155 I<output> files on the command line.
156
157 =head1 OPTIONS
158
159 =over 4
160
161 =item B<-a>, B<--alt>
162
163 Use an alternate output format that, among other things, uses a different
164 heading style and marks C<=item> entries with a colon in the left margin.
165
166 =item B<--code>
167
168 Include any non-POD text from the input file in the output as well.  Useful
169 for viewing code documented with POD blocks with the POD rendered and the
170 code left intact.
171
172 =item B<-c>, B<--color>
173
174 Format the output with ANSI color escape sequences.  Using this option
175 requires that Term::ANSIColor be installed on your system.
176
177 =item B<-i> I<indent>, B<--indent=>I<indent>
178
179 Set the number of spaces to indent regular text, and the default indentation
180 for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
181
182 =item B<-errors>=I<style>
183
184 Set the error handling style.  C<die> says to throw an exception on any
185 POD formatting error.  C<stderr> says to report errors on standard error,
186 but not to throw an exception.  C<pod> says to include a POD ERRORS
187 section in the resulting documentation summarizing the errors.  C<none>
188 ignores POD errors entirely, as much as possible.
189
190 The default is C<die>.
191
192 =item B<-h>, B<--help>
193
194 Print out usage information and exit.
195
196 =item B<-l>, B<--loose>
197
198 Print a blank line after a C<=head1> heading.  Normally, no blank line is
199 printed after C<=head1>, although one is still printed after C<=head2>,
200 because this is the expected formatting for manual pages; if you're
201 formatting arbitrary text documents, using this option is recommended.
202
203 =item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width>
204
205 The width of the left margin in spaces.  Defaults to 0.  This is the margin
206 for all text, including headings, not the amount by which regular text is
207 indented; for the latter, see B<-i> option.
208
209 =item B<--nourls>
210
211 Normally, LZ<><> formatting codes with a URL but anchor text are formatted
212 to show both the anchor text and the URL.  In other words:
213
214     L<foo|http://example.com/>
215
216 is formatted as:
217
218     foo <http://example.com/>
219
220 This flag, if given, suppresses the URL when anchor text is given, so this
221 example would be formatted as just C<foo>.  This can produce less
222 cluttered output in cases where the URLs are not particularly important.
223
224 =item B<-o>, B<--overstrike>
225
226 Format the output with overstrike printing.  Bold text is rendered as
227 character, backspace, character.  Italics and file names are rendered as
228 underscore, backspace, character.  Many pagers, such as B<less>, know how
229 to convert this to bold or underlined text.
230
231 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
232
233 Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
234 I<quotes> is a single character, it is used as both the left and right
235 quote; if I<quotes> is two characters, the first character is used as the
236 left quote and the second as the right quoted; and if I<quotes> is four
237 characters, the first two are used as the left quote and the second two as
238 the right quote.
239
240 I<quotes> may also be set to the special value C<none>, in which case no
241 quote marks are added around CE<lt>> text.
242
243 =item B<-s>, B<--sentence>
244
245 Assume each sentence ends with two spaces and try to preserve that spacing.
246 Without this option, all consecutive whitespace in non-verbatim paragraphs
247 is compressed into a single space.
248
249 =item B<--stderr>
250
251 By default, B<pod2text> dies if any errors are detected in the POD input.
252 If B<--stderr> is given and no B<--errors> flag is present, errors are
253 sent to standard error, but B<pod2text> does not abort.  This is
254 equivalent to C<--errors=stderr> and is supported for backward
255 compatibility.
256
257 =item B<-t>, B<--termcap>
258
259 Try to determine the width of the screen and the bold and underline
260 sequences for the terminal from termcap, and use that information in
261 formatting the output.  Output will be wrapped at two columns less than the
262 width of your terminal device.  Using this option requires that your system
263 have a termcap file somewhere where Term::Cap can find it and requires that
264 your system support termios.  With this option, the output of B<pod2text>
265 will contain terminal control sequences for your current terminal type.
266
267 =item B<-u>, B<--utf8>
268
269 By default, B<pod2text> tries to use the same output encoding as its input
270 encoding (to be backward-compatible with older versions).  This option
271 says to instead force the output encoding to UTF-8.
272
273 Be aware that, when using this option, the input encoding of your POD
274 source must be properly declared unless it is US-ASCII or Latin-1.  POD
275 input without an C<=encoding> command will be assumed to be in Latin-1,
276 and if it's actually in UTF-8, the output will be double-encoded.  See
277 L<perlpod(1)> for more information on the C<=encoding> command.
278
279 =item B<-w>, B<--width=>I<width>, B<->I<width>
280
281 The column at which to wrap text on the right-hand side.  Defaults to 76,
282 unless B<-t> is given, in which case it's two columns less than the width of
283 your terminal device.
284
285 =back
286
287 =head1 EXIT STATUS
288
289 As long as all documents processed result in some output, even if that
290 output includes errata (a C<POD ERRORS> section generated with
291 C<--errors=pod>), B<pod2text> will exit with status 0.  If any of the
292 documents being processed do not result in an output document, B<pod2text>
293 will exit with status 1.  If there are syntax errors in a POD document
294 being processed and the error handling style is set to the default of
295 C<die>, B<pod2text> will abort immediately with exit status 255.
296
297 =head1 DIAGNOSTICS
298
299 If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for
300 information about what those errors might mean.  Internally, it can also
301 produce the following diagnostics:
302
303 =over 4
304
305 =item -c (--color) requires Term::ANSIColor be installed
306
307 (F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
308 loaded.
309
310 =item Unknown option: %s
311
312 (F) An unknown command line option was given.
313
314 =back
315
316 In addition, other L<Getopt::Long> error messages may result from invalid
317 command-line options.
318
319 =head1 ENVIRONMENT
320
321 =over 4
322
323 =item COLUMNS
324
325 If B<-t> is given, B<pod2text> will take the current width of your screen
326 from this environment variable, if available.  It overrides terminal width
327 information in TERMCAP.
328
329 =item TERMCAP
330
331 If B<-t> is given, B<pod2text> will use the contents of this environment
332 variable if available to determine the correct formatting sequences for your
333 current terminal device.
334
335 =back
336
337 =head1 SEE ALSO
338
339 L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>,
340 L<Pod::Text::Termcap>, L<Pod::Simple>, L<perlpod(1)>
341
342 The current version of this script is always available from its web site at
343 L<http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
344 Perl core distribution as of 5.6.0.
345
346 =head1 AUTHOR
347
348 Russ Allbery <rra@stanford.edu>.
349
350 =head1 COPYRIGHT AND LICENSE
351
352 Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 Russ
353 Allbery <rra@stanford.edu>.
354
355 This program is free software; you may redistribute it and/or modify it
356 under the same terms as Perl itself.
357
358 =cut
359 !NO!SUBS!
360
361 close OUT or die "Can't close $file: $!";
362 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
363 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
364 chdir $origdir;