Commit | Line | Data |
---|---|---|
cb1a09d0 AD |
1 | #!/usr/local/bin/perl |
2 | ||
c07a80fd | 3 | use Config; |
4 | use File::Basename qw(&basename &dirname); | |
3b5ca523 | 5 | use 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 GS |
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); | |
44a8e56a | 18 | $file = basename($0, '.PL'); |
774d564b | 19 | $file .= '.com' if $^O eq 'VMS'; |
cb1a09d0 | 20 | |
c07a80fd | 21 | open OUT,">$file" or die "Can't create $file: $!"; |
cb1a09d0 | 22 | |
c07a80fd | 23 | print "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 | 28 | print 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 | 36 | print OUT <<'!NO!SUBS!'; |
cb1a09d0 | 37 | |
6055f9d4 | 38 | # pod2text -- Convert POD data to formatted ASCII text. |
9741dab0 | 39 | # |
0e4e3f6e | 40 | # Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra@stanford.edu> |
6055f9d4 | 41 | # |
3c014959 | 42 | # This program is free software; you may redistribute it and/or modify it |
6055f9d4 GS |
43 | # under the same terms as Perl itself. |
44 | # | |
9741dab0 GS |
45 | # The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color, |
46 | # invoked by perldoc -t among other things. | |
6055f9d4 GS |
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; | |
6055f9d4 | 55 | |
59548eca JH |
56 | # Silence -w warnings. |
57 | use vars qw($running_under_some_shell); | |
58 | ||
6055f9d4 GS |
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 | ||
46bce7d0 | 69 | # Insert -- into @ARGV before any single dash argument to hide it from |
b7ae008f | 70 | # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple |
46bce7d0 GS |
71 | # does correctly). |
72 | my $stdin; | |
73 | @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; | |
74 | ||
9741dab0 GS |
75 | # Parse our options. Use the same names as Pod::Text for simplicity, and |
76 | # default to sentence boundaries turned off for compatibility. | |
6055f9d4 | 77 | my %options; |
6055f9d4 GS |
78 | $options{sentence} = 0; |
79 | Getopt::Long::config ('bundling'); | |
59548eca | 80 | GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i', |
11f72409 | 81 | 'loose|l', 'margin|left-margin|m=i', 'overstrike|o', |
9f2f055a SH |
82 | 'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t', 'utf8|u', |
83 | 'width|w=i') | |
bc9c7511 | 84 | or exit 1; |
6055f9d4 GS |
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'; | |
9741dab0 GS |
91 | eval { require Term::ANSIColor }; |
92 | if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" } | |
6055f9d4 GS |
93 | require Pod::Text::Color; |
94 | } elsif ($options{termcap}) { | |
95 | $formatter = 'Pod::Text::Termcap'; | |
96 | require Pod::Text::Termcap; | |
73849855 RA |
97 | } elsif ($options{overstrike}) { |
98 | $formatter = 'Pod::Text::Overstrike'; | |
99 | require Pod::Text::Overstrike; | |
cb1a09d0 | 100 | } |
73849855 | 101 | delete @options{'color', 'termcap', 'overstrike'}; |
6055f9d4 GS |
102 | |
103 | # Initialize and run the formatter. | |
8f202758 | 104 | my $parser = $formatter->new (%options); |
b7ae008f | 105 | do { |
b7ae008f | 106 | my ($input, $output) = splice (@ARGV, 0, 2); |
8f202758 | 107 | $parser->parse_from_file ($input, $output); |
b7ae008f | 108 | } while (@ARGV); |
6055f9d4 GS |
109 | |
110 | __END__ | |
111 | ||
112 | =head1 NAME | |
113 | ||
114 | pod2text - Convert POD data to formatted ASCII text | |
115 | ||
0e4e3f6e | 116 | =for stopwords |
9f2f055a SH |
117 | -aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8 |
118 | UTF-8 | |
0e4e3f6e | 119 | |
6055f9d4 GS |
120 | =head1 SYNOPSIS |
121 | ||
9f2f055a | 122 | pod2text [B<-aclostu>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]> |
bc9c7511 | 123 | [B<--stderr>] S<[B<-w> I<width>]> [I<input> [I<output> ...]] |
6055f9d4 GS |
124 | |
125 | pod2text B<-h> | |
126 | ||
127 | =head1 DESCRIPTION | |
128 | ||
9741dab0 GS |
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. | |
6055f9d4 GS |
132 | |
133 | I<input> is the file to read for POD source (the POD can be embedded in | |
0e4e3f6e SH |
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. | |
6055f9d4 GS |
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 | ||
59548eca JH |
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 | ||
6055f9d4 GS |
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 | ||
9741dab0 GS |
166 | =item B<-h>, B<--help> |
167 | ||
168 | Print out usage information and exit. | |
169 | ||
6055f9d4 GS |
170 | =item B<-l>, B<--loose> |
171 | ||
172 | Print a blank line after a C<=head1> heading. Normally, no blank line is | |
9741dab0 GS |
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. | |
6055f9d4 | 176 | |
11f72409 RA |
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 | ||
73849855 RA |
183 | =item B<-o>, B<--overstrike> |
184 | ||
0e4e3f6e | 185 | Format the output with overstrike printing. Bold text is rendered as |
73849855 RA |
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 | ||
ab1f1d91 JH |
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 | ||
6055f9d4 GS |
202 | =item B<-s>, B<--sentence> |
203 | ||
9741dab0 | 204 | Assume each sentence ends with two spaces and try to preserve that spacing. |
6055f9d4 GS |
205 | Without this option, all consecutive whitespace in non-verbatim paragraphs |
206 | is compressed into a single space. | |
207 | ||
bc9c7511 NC |
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 | ||
6055f9d4 GS |
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 | |
46bce7d0 GS |
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. | |
6055f9d4 | 224 | |
9f2f055a SH |
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 | ||
6055f9d4 GS |
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 | ||
9741dab0 GS |
245 | =head1 DIAGNOSTICS |
246 | ||
b7ae008f | 247 | If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for |
9741dab0 GS |
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 | ||
b7ae008f SP |
264 | In addition, other L<Getopt::Long> error messages may result from invalid |
265 | command-line options. | |
9741dab0 | 266 | |
6055f9d4 GS |
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 | ||
6055f9d4 GS |
285 | =head1 SEE ALSO |
286 | ||
fd20da51 | 287 | L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>, |
9f2f055a | 288 | L<Pod::Text::Termcap>, L<Pod::Simple>, L<perlpod(1)> |
fd20da51 JH |
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. | |
6055f9d4 GS |
293 | |
294 | =head1 AUTHOR | |
295 | ||
3c014959 JH |
296 | Russ Allbery <rra@stanford.edu>. |
297 | ||
298 | =head1 COPYRIGHT AND LICENSE | |
299 | ||
0e4e3f6e SH |
300 | Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery |
301 | <rra@stanford.edu>. | |
3c014959 JH |
302 | |
303 | This program is free software; you may redistribute it and/or modify it | |
304 | under the same terms as Perl itself. | |
cb1a09d0 | 305 | |
6055f9d4 | 306 | =cut |
c07a80fd | 307 | !NO!SUBS! |
cb1a09d0 | 308 | |
c07a80fd | 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 ':'; | |
3b5ca523 | 312 | chdir $origdir; |