Commit | Line | Data |
cb1a09d0 |
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 |
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 | # |
46bce7d0 |
40 | # Copyright 1999, 2000 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 | |
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 | |
56 | # Take an initial pass through our options, looking for one of the form |
57 | # -<number>. We turn that into -w <number> for compatibility with the |
58 | # original pod2text script. |
59 | for (my $i = 0; $i < @ARGV; $i++) { |
60 | last if $ARGV[$i] =~ /^--$/; |
61 | if ($ARGV[$i] =~ /^-(\d+)$/) { |
62 | splice (@ARGV, $i++, 1, '-w', $1); |
63 | } |
64 | } |
65 | |
46bce7d0 |
66 | # Insert -- into @ARGV before any single dash argument to hide it from |
67 | # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser |
68 | # does correctly). |
69 | my $stdin; |
70 | @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; |
71 | |
9741dab0 |
72 | # Parse our options. Use the same names as Pod::Text for simplicity, and |
73 | # default to sentence boundaries turned off for compatibility. |
6055f9d4 |
74 | my %options; |
6055f9d4 |
75 | $options{sentence} = 0; |
76 | Getopt::Long::config ('bundling'); |
77 | GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i', |
73849855 |
78 | 'loose|l', 'overstrike|o', 'quotes|q=s', 'sentence|s', |
79 | 'termcap|t', 'width|w=i') or exit 1; |
6055f9d4 |
80 | pod2usage (1) if $options{help}; |
81 | |
82 | # Figure out what formatter we're going to use. -c overrides -t. |
83 | my $formatter = 'Pod::Text'; |
84 | if ($options{color}) { |
85 | $formatter = 'Pod::Text::Color'; |
9741dab0 |
86 | eval { require Term::ANSIColor }; |
87 | if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" } |
6055f9d4 |
88 | require Pod::Text::Color; |
89 | } elsif ($options{termcap}) { |
90 | $formatter = 'Pod::Text::Termcap'; |
91 | require Pod::Text::Termcap; |
73849855 |
92 | } elsif ($options{overstrike}) { |
93 | $formatter = 'Pod::Text::Overstrike'; |
94 | require Pod::Text::Overstrike; |
cb1a09d0 |
95 | } |
73849855 |
96 | delete @options{'color', 'termcap', 'overstrike'}; |
6055f9d4 |
97 | |
98 | # Initialize and run the formatter. |
99 | my $parser = $formatter->new (%options); |
100 | $parser->parse_from_file (@ARGV); |
101 | |
102 | __END__ |
103 | |
104 | =head1 NAME |
105 | |
106 | pod2text - Convert POD data to formatted ASCII text |
107 | |
108 | =head1 SYNOPSIS |
109 | |
73849855 |
110 | pod2text [B<-aclost>] [B<-i> I<indent>] [B<-q> I<quotes>] [B<-w> I<width>] |
ab1f1d91 |
111 | [I<input> [I<output>]] |
6055f9d4 |
112 | |
113 | pod2text B<-h> |
114 | |
115 | =head1 DESCRIPTION |
116 | |
9741dab0 |
117 | B<pod2text> is a front-end for Pod::Text and its subclasses. It uses them |
118 | to generate formatted ASCII text from POD source. It can optionally use |
119 | either termcap sequences or ANSI color escape sequences to format the text. |
6055f9d4 |
120 | |
121 | I<input> is the file to read for POD source (the POD can be embedded in |
122 | code). If I<input> isn't given, it defaults to STDIN. I<output>, if given, |
123 | is the file to which to write the formatted output. If I<output> isn't |
124 | given, the formatted output is written to STDOUT. |
125 | |
126 | =head1 OPTIONS |
127 | |
128 | =over 4 |
129 | |
130 | =item B<-a>, B<--alt> |
131 | |
132 | Use an alternate output format that, among other things, uses a different |
133 | heading style and marks C<=item> entries with a colon in the left margin. |
134 | |
135 | =item B<-c>, B<--color> |
136 | |
137 | Format the output with ANSI color escape sequences. Using this option |
138 | requires that Term::ANSIColor be installed on your system. |
139 | |
140 | =item B<-i> I<indent>, B<--indent=>I<indent> |
141 | |
142 | Set the number of spaces to indent regular text, and the default indentation |
143 | for C<=over> blocks. Defaults to 4 spaces if this option isn't given. |
144 | |
9741dab0 |
145 | =item B<-h>, B<--help> |
146 | |
147 | Print out usage information and exit. |
148 | |
6055f9d4 |
149 | =item B<-l>, B<--loose> |
150 | |
151 | Print a blank line after a C<=head1> heading. Normally, no blank line is |
9741dab0 |
152 | printed after C<=head1>, although one is still printed after C<=head2>, |
153 | because this is the expected formatting for manual pages; if you're |
154 | formatting arbitrary text documents, using this option is recommended. |
6055f9d4 |
155 | |
73849855 |
156 | =item B<-o>, B<--overstrike> |
157 | |
158 | Format the output with overstruck printing. Bold text is rendered as |
159 | character, backspace, character. Italics and file names are rendered as |
160 | underscore, backspace, character. Many pagers, such as B<less>, know how |
161 | to convert this to bold or underlined text. |
162 | |
ab1f1d91 |
163 | =item B<-q> I<quotes>, B<--quotes>=I<quotes> |
164 | |
165 | Sets the quote marks used to surround CE<lt>> text to I<quotes>. If |
166 | I<quotes> is a single character, it is used as both the left and right |
167 | quote; if I<quotes> is two characters, the first character is used as the |
168 | left quote and the second as the right quoted; and if I<quotes> is four |
169 | characters, the first two are used as the left quote and the second two as |
170 | the right quote. |
171 | |
172 | I<quotes> may also be set to the special value C<none>, in which case no |
173 | quote marks are added around CE<lt>> text. |
174 | |
6055f9d4 |
175 | =item B<-s>, B<--sentence> |
176 | |
9741dab0 |
177 | Assume each sentence ends with two spaces and try to preserve that spacing. |
6055f9d4 |
178 | Without this option, all consecutive whitespace in non-verbatim paragraphs |
179 | is compressed into a single space. |
180 | |
181 | =item B<-t>, B<--termcap> |
182 | |
183 | Try to determine the width of the screen and the bold and underline |
184 | sequences for the terminal from termcap, and use that information in |
185 | formatting the output. Output will be wrapped at two columns less than the |
186 | width of your terminal device. Using this option requires that your system |
46bce7d0 |
187 | have a termcap file somewhere where Term::Cap can find it and requires that |
188 | your system support termios. With this option, the output of B<pod2text> |
189 | will contain terminal control sequences for your current terminal type. |
6055f9d4 |
190 | |
191 | =item B<-w>, B<--width=>I<width>, B<->I<width> |
192 | |
193 | The column at which to wrap text on the right-hand side. Defaults to 76, |
194 | unless B<-t> is given, in which case it's two columns less than the width of |
195 | your terminal device. |
196 | |
197 | =back |
198 | |
9741dab0 |
199 | =head1 DIAGNOSTICS |
200 | |
201 | If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for |
202 | information about what those errors might mean. Internally, it can also |
203 | produce the following diagnostics: |
204 | |
205 | =over 4 |
206 | |
207 | =item -c (--color) requires Term::ANSIColor be installed |
208 | |
209 | (F) B<-c> or B<--color> were given, but Term::ANSIColor could not be |
210 | loaded. |
211 | |
212 | =item Unknown option: %s |
213 | |
214 | (F) An unknown command line option was given. |
215 | |
216 | =back |
217 | |
218 | In addition, other L<Getopt::Long|Getopt::Long> error messages may result |
219 | from invalid command-line options. |
220 | |
6055f9d4 |
221 | =head1 ENVIRONMENT |
222 | |
223 | =over 4 |
224 | |
225 | =item COLUMNS |
226 | |
227 | If B<-t> is given, B<pod2text> will take the current width of your screen |
228 | from this environment variable, if available. It overrides terminal width |
229 | information in TERMCAP. |
230 | |
231 | =item TERMCAP |
232 | |
233 | If B<-t> is given, B<pod2text> will use the contents of this environment |
234 | variable if available to determine the correct formatting sequences for your |
235 | current terminal device. |
236 | |
237 | =back |
238 | |
6055f9d4 |
239 | =head1 SEE ALSO |
240 | |
241 | L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>, |
242 | L<Pod::Text::Termcap|Pod::Text::Termcap>, L<Pod::Parser|Pod::Parser> |
243 | |
244 | =head1 AUTHOR |
245 | |
3c014959 |
246 | Russ Allbery <rra@stanford.edu>. |
247 | |
248 | =head1 COPYRIGHT AND LICENSE |
249 | |
250 | Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>. |
251 | |
252 | This program is free software; you may redistribute it and/or modify it |
253 | under the same terms as Perl itself. |
cb1a09d0 |
254 | |
6055f9d4 |
255 | =cut |
c07a80fd |
256 | !NO!SUBS! |
cb1a09d0 |
257 | |
c07a80fd |
258 | close OUT or die "Can't close $file: $!"; |
259 | chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; |
260 | exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; |
3b5ca523 |
261 | chdir $origdir; |