README.vms and related updates (from Peter Prymmer <pvhp@best.com>)
[p5sagit/p5-mst-13.2.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 by Russ Allbery <rra@stanford.edu>
41 #
42 # This program is free software; you can 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 use vars qw($ID);
56
57 # Take an initial pass through our options, looking for one of the form
58 # -<number>.  We turn that into -w <number> for compatibility with the
59 # original pod2text script.
60 for (my $i = 0; $i < @ARGV; $i++) {
61     last if $ARGV[$i] =~ /^--$/;
62     if ($ARGV[$i] =~ /^-(\d+)$/) {
63         splice (@ARGV, $i++, 1, '-w', $1);
64     }
65 }
66
67 # Parse our options.  Use the same names as Pod::Text for simplicity, and
68 # default to sentence boundaries turned off for compatibility.
69 my %options;
70 $options{termcap} = -t STDOUT;
71 $options{sentence} = 0;
72 Getopt::Long::config ('bundling');
73 GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i',
74             'loose|l', 'sentence|s', 'termcap|t!', 'width|w=i') or exit 1;
75 pod2usage (1) if $options{help};
76
77 # Figure out what formatter we're going to use.  -c overrides -t.
78 my $formatter = 'Pod::Text';
79 if ($options{color}) {
80     $formatter = 'Pod::Text::Color';
81     eval { require Term::ANSIColor };
82     if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
83     require Pod::Text::Color;
84 } elsif ($options{termcap}) {
85     $formatter = 'Pod::Text::Termcap';
86     require Pod::Text::Termcap;
87 }
88 delete @options{'color', 'termcap'};
89
90 # Initialize and run the formatter.
91 my $parser = $formatter->new (%options);
92 $parser->parse_from_file (@ARGV);
93
94 __END__
95
96 =head1 NAME
97
98 pod2text - Convert POD data to formatted ASCII text
99
100 =head1 SYNOPSIS
101
102 pod2text [B<-aclst>] [B<-i> I<indent>] [B<-w> I<width>] [I<input> [I<output>]]
103
104 pod2text B<-h>
105
106 =head1 DESCRIPTION
107
108 B<pod2text> is a front-end for Pod::Text and its subclasses.  It uses them
109 to generate formatted ASCII text from POD source.  It can optionally use
110 either termcap sequences or ANSI color escape sequences to format the text.
111
112 I<input> is the file to read for POD source (the POD can be embedded in
113 code).  If I<input> isn't given, it defaults to STDIN.  I<output>, if given,
114 is the file to which to write the formatted output.  If I<output> isn't
115 given, the formatted output is written to STDOUT.
116
117 B<pod2text> defaults to trying to use Pod::Text::Termcap if STDOUT is a tty.
118 To explicitly say not to attempt termcap escape sequences, use
119 B<--notermcap>.
120
121 =head1 OPTIONS
122
123 =over 4
124
125 =item B<-a>, B<--alt>
126
127 Use an alternate output format that, among other things, uses a different
128 heading style and marks C<=item> entries with a colon in the left margin.
129
130 =item B<-c>, B<--color>
131
132 Format the output with ANSI color escape sequences.  Using this option
133 requires that Term::ANSIColor be installed on your system.
134
135 =item B<-i> I<indent>, B<--indent=>I<indent>
136
137 Set the number of spaces to indent regular text, and the default indentation
138 for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
139
140 =item B<-h>, B<--help>
141
142 Print out usage information and exit.
143
144 =item B<-l>, B<--loose>
145
146 Print a blank line after a C<=head1> heading.  Normally, no blank line is
147 printed after C<=head1>, although one is still printed after C<=head2>,
148 because this is the expected formatting for manual pages; if you're
149 formatting arbitrary text documents, using this option is recommended.
150
151 =item B<-s>, B<--sentence>
152
153 Assume each sentence ends with two spaces and try to preserve that spacing.
154 Without this option, all consecutive whitespace in non-verbatim paragraphs
155 is compressed into a single space.
156
157 =item B<-t>, B<--termcap>
158
159 Try to determine the width of the screen and the bold and underline
160 sequences for the terminal from termcap, and use that information in
161 formatting the output.  Output will be wrapped at two columns less than the
162 width of your terminal device.  Using this option requires that your system
163 have a termcap file somewhere where Term::Cap can find it.  With this
164 option, the output of B<pod2text> will contain terminal control sequences
165 for your current terminal type.
166
167 =item B<-w>, B<--width=>I<width>, B<->I<width>
168
169 The column at which to wrap text on the right-hand side.  Defaults to 76,
170 unless B<-t> is given, in which case it's two columns less than the width of
171 your terminal device.
172
173 =back
174
175 =head1 DIAGNOSTICS
176
177 If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Parser> for
178 information about what those errors might mean.  Internally, it can also
179 produce the following diagnostics:
180
181 =over 4
182
183 =item -c (--color) requires Term::ANSIColor be installed
184
185 (F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
186 loaded.
187
188 =item Unknown option: %s
189
190 (F) An unknown command line option was given.
191
192 =back
193
194 In addition, other L<Getopt::Long|Getopt::Long> error messages may result
195 from invalid command-line options.
196
197 =head1 ENVIRONMENT
198
199 =over 4
200
201 =item COLUMNS
202
203 If B<-t> is given, B<pod2text> will take the current width of your screen
204 from this environment variable, if available.  It overrides terminal width
205 information in TERMCAP.
206
207 =item TERMCAP
208
209 If B<-t> is given, B<pod2text> will use the contents of this environment
210 variable if available to determine the correct formatting sequences for your
211 current terminal device.
212
213 =back
214
215 =head1 SEE ALSO
216
217 L<Pod::Text|Pod::Text>, L<Pod::Text::Color|Pod::Text::Color>,
218 L<Pod::Text::Termcap|Pod::Text::Termcap>, L<Pod::Parser|Pod::Parser>
219
220 =head1 AUTHOR
221
222 Russ Allbery E<lt>rra@stanford.eduE<gt>.
223
224 =cut
225 !NO!SUBS!
226
227 close OUT or die "Can't close $file: $!";
228 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
229 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
230 chdir $origdir;