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