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