| 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 |