1#!/usr/bin/perl 2# 3# Special wrapper script to generate the actual pod2man script. This is 4# required for proper start-up code on non-UNIX platforms, and is used inside 5# Perl core. 6 7use 5.006; 8use strict; 9use warnings; 10 11use Config qw(%Config); 12use Cwd qw(cwd); 13use File::Basename qw(basename dirname); 14 15# List explicitly here the variables you want Configure to generate. 16# Metaconfig only looks for shell variables, so you have to mention them as if 17# they were shell variables, not %Config entries. Thus you write 18# $startperl 19# to ensure Configure will look for $Config{startperl}. 20 21# This forces PL files to create target in same directory as PL file. 22# This is so that make depend always knows where to find PL derivatives. 23chdir(dirname($0)) or die "Cannot change directories: $!\n"; 24my $file = basename($0, '.PL'); 25if ($^O eq 'VMS') { 26 $file .= '.com'; 27} 28 29# Create the generated script. 30## no critic (InputOutput::RequireBriefOpen) 31## no critic (InputOutput::RequireCheckedSyscalls) 32open(my $out, '>', $file) or die "Cannot create $file: $!\n"; 33print "Extracting $file (with variable substitutions)\n"; 34## use critic 35 36# In this section, Perl variables will be expanded during extraction. You can 37# use $Config{...} to use Configure variables. 38print {$out} <<"PREAMBLE" or die "Cannot write to $file: $!\n"; 39$Config{startperl} 40 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' 41 if \$running_under_some_shell; 42PREAMBLE 43 44# In the following, Perl variables are not expanded during extraction. 45print {$out} <<'SCRIPT_BODY' or die "Cannot write to $file: $!\n"; 46 47# pod2text -- Convert POD data to formatted ASCII text. 48# 49# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015, 50# 2016 Russ Allbery <rra@cpan.org> 51# 52# This program is free software; you may redistribute it and/or modify it 53# under the same terms as Perl itself. 54# 55# The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color, 56# invoked by perldoc -t among other things. 57 58use 5.006; 59use strict; 60use warnings; 61 62use Getopt::Long qw(GetOptions); 63use Pod::Text (); 64use Pod::Usage qw(pod2usage); 65 66# Clean up $0 for error reporting. 67$0 =~ s%.*/%%; 68 69# Take an initial pass through our options, looking for one of the form 70# -<number>. We turn that into -w <number> for compatibility with the 71# original pod2text script. 72for (my $i = 0; $i < @ARGV; $i++) { 73 last if $ARGV[$i] =~ /^--$/; 74 if ($ARGV[$i] =~ /^-(\d+)$/) { 75 splice (@ARGV, $i++, 1, '-w', $1); 76 } 77} 78 79# Insert -- into @ARGV before any single dash argument to hide it from 80# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple 81# does correctly). 82my $stdin; 83@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; 84 85# Parse our options. Use the same names as Pod::Text for simplicity, and 86# default to sentence boundaries turned off for compatibility. 87my %options; 88$options{sentence} = 0; 89Getopt::Long::config ('bundling'); 90GetOptions (\%options, 'alt|a', 'code', 'color|c', 'errors=s', 'help|h', 91 'indent|i=i', 'loose|l', 'margin|left-margin|m=i', 'nourls', 92 'overstrike|o', 'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t', 93 'utf8|u', 'width|w=i') 94 or exit 1; 95pod2usage (1) if $options{help}; 96 97# Figure out what formatter we're going to use. -c overrides -t. 98my $formatter = 'Pod::Text'; 99if ($options{color}) { 100 $formatter = 'Pod::Text::Color'; 101 eval { require Term::ANSIColor }; 102 if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" } 103 require Pod::Text::Color; 104} elsif ($options{termcap}) { 105 $formatter = 'Pod::Text::Termcap'; 106 require Pod::Text::Termcap; 107} elsif ($options{overstrike}) { 108 $formatter = 'Pod::Text::Overstrike'; 109 require Pod::Text::Overstrike; 110} 111delete @options{'color', 'termcap', 'overstrike'}; 112 113# If neither stderr nor errors is set, default to errors = die. 114if (!defined $options{stderr} && !defined $options{errors}) { 115 $options{errors} = 'die'; 116} 117 118# Initialize and run the formatter. 119my $parser = $formatter->new (%options); 120my $status = 0; 121do { 122 my ($input, $output) = splice (@ARGV, 0, 2); 123 $parser->parse_from_file ($input, $output); 124 if ($parser->{CONTENTLESS}) { 125 $status = 1; 126 warn "$0: unable to format $input\n"; 127 if (defined ($output) and $output ne '-') { 128 unlink $output unless (-s $output); 129 } 130 } 131} while (@ARGV); 132exit $status; 133 134__END__ 135 136=for stopwords 137-aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8 138UTF-8 subclasses --nourls 139 140=head1 NAME 141 142pod2text - Convert POD data to formatted ASCII text 143 144=head1 SYNOPSIS 145 146pod2text [B<-aclostu>] [B<--code>] [B<--errors>=I<style>] [B<-i> I<indent>] 147 S<[B<-q> I<quotes>]> [B<--nourls>] [B<--stderr>] S<[B<-w> I<width>]> 148 [I<input> [I<output> ...]] 149 150pod2text B<-h> 151 152=head1 DESCRIPTION 153 154B<pod2text> is a front-end for Pod::Text and its subclasses. It uses them 155to generate formatted ASCII text from POD source. It can optionally use 156either termcap sequences or ANSI color escape sequences to format the text. 157 158I<input> is the file to read for POD source (the POD can be embedded in 159code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if 160given, is the file to which to write the formatted output. If I<output> 161isn't given, the formatted output is written to C<STDOUT>. Several POD 162files can be processed in the same B<pod2text> invocation (saving module 163load and compile times) by providing multiple pairs of I<input> and 164I<output> files on the command line. 165 166=head1 OPTIONS 167 168=over 4 169 170=item B<-a>, B<--alt> 171 172Use an alternate output format that, among other things, uses a different 173heading style and marks C<=item> entries with a colon in the left margin. 174 175=item B<--code> 176 177Include any non-POD text from the input file in the output as well. Useful 178for viewing code documented with POD blocks with the POD rendered and the 179code left intact. 180 181=item B<-c>, B<--color> 182 183Format the output with ANSI color escape sequences. Using this option 184requires that Term::ANSIColor be installed on your system. 185 186=item B<--errors>=I<style> 187 188Set the error handling style. C<die> says to throw an exception on any 189POD formatting error. C<stderr> says to report errors on standard error, 190but not to throw an exception. C<pod> says to include a POD ERRORS 191section in the resulting documentation summarizing the errors. C<none> 192ignores POD errors entirely, as much as possible. 193 194The default is C<die>. 195 196=item B<-i> I<indent>, B<--indent=>I<indent> 197 198Set the number of spaces to indent regular text, and the default indentation 199for C<=over> blocks. Defaults to 4 spaces if this option isn't given. 200 201=item B<-h>, B<--help> 202 203Print out usage information and exit. 204 205=item B<-l>, B<--loose> 206 207Print a blank line after a C<=head1> heading. Normally, no blank line is 208printed after C<=head1>, although one is still printed after C<=head2>, 209because this is the expected formatting for manual pages; if you're 210formatting arbitrary text documents, using this option is recommended. 211 212=item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width> 213 214The width of the left margin in spaces. Defaults to 0. This is the margin 215for all text, including headings, not the amount by which regular text is 216indented; for the latter, see B<-i> option. 217 218=item B<--nourls> 219 220Normally, LZ<><> formatting codes with a URL but anchor text are formatted 221to show both the anchor text and the URL. In other words: 222 223 L<foo|http://example.com/> 224 225is formatted as: 226 227 foo <http://example.com/> 228 229This flag, if given, suppresses the URL when anchor text is given, so this 230example would be formatted as just C<foo>. This can produce less 231cluttered output in cases where the URLs are not particularly important. 232 233=item B<-o>, B<--overstrike> 234 235Format the output with overstrike printing. Bold text is rendered as 236character, backspace, character. Italics and file names are rendered as 237underscore, backspace, character. Many pagers, such as B<less>, know how 238to convert this to bold or underlined text. 239 240=item B<-q> I<quotes>, B<--quotes>=I<quotes> 241 242Sets the quote marks used to surround CE<lt>> text to I<quotes>. If 243I<quotes> is a single character, it is used as both the left and right 244quote. Otherwise, it is split in half, and the first half of the string 245is used as the left quote and the second is used as the right quote. 246 247I<quotes> may also be set to the special value C<none>, in which case no 248quote marks are added around CE<lt>> text. 249 250=item B<-s>, B<--sentence> 251 252Assume each sentence ends with two spaces and try to preserve that spacing. 253Without this option, all consecutive whitespace in non-verbatim paragraphs 254is compressed into a single space. 255 256=item B<--stderr> 257 258By default, B<pod2text> dies if any errors are detected in the POD input. 259If B<--stderr> is given and no B<--errors> flag is present, errors are 260sent to standard error, but B<pod2text> does not abort. This is 261equivalent to C<--errors=stderr> and is supported for backward 262compatibility. 263 264=item B<-t>, B<--termcap> 265 266Try to determine the width of the screen and the bold and underline 267sequences for the terminal from termcap, and use that information in 268formatting the output. Output will be wrapped at two columns less than the 269width of your terminal device. Using this option requires that your system 270have a termcap file somewhere where Term::Cap can find it and requires that 271your system support termios. With this option, the output of B<pod2text> 272will contain terminal control sequences for your current terminal type. 273 274=item B<-u>, B<--utf8> 275 276By default, B<pod2text> tries to use the same output encoding as its input 277encoding (to be backward-compatible with older versions). This option 278says to instead force the output encoding to UTF-8. 279 280Be aware that, when using this option, the input encoding of your POD 281source should be properly declared unless it's US-ASCII. Pod::Simple 282will attempt to guess the encoding and may be successful if it's 283Latin-1 or UTF-8, but it will warn, which by default results in a 284B<pod2text> failure. Use the C<=encoding> command to declare the 285encoding. See L<perlpod(1)> for more information. 286 287=item B<-w>, B<--width=>I<width>, B<->I<width> 288 289The column at which to wrap text on the right-hand side. Defaults to 76, 290unless B<-t> is given, in which case it's two columns less than the width of 291your terminal device. 292 293=back 294 295=head1 EXIT STATUS 296 297As long as all documents processed result in some output, even if that 298output includes errata (a C<POD ERRORS> section generated with 299C<--errors=pod>), B<pod2text> will exit with status 0. If any of the 300documents being processed do not result in an output document, B<pod2text> 301will exit with status 1. If there are syntax errors in a POD document 302being processed and the error handling style is set to the default of 303C<die>, B<pod2text> will abort immediately with exit status 255. 304 305=head1 DIAGNOSTICS 306 307If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for 308information about what those errors might mean. Internally, it can also 309produce the following diagnostics: 310 311=over 4 312 313=item -c (--color) requires Term::ANSIColor be installed 314 315(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be 316loaded. 317 318=item Unknown option: %s 319 320(F) An unknown command line option was given. 321 322=back 323 324In addition, other L<Getopt::Long> error messages may result from invalid 325command-line options. 326 327=head1 ENVIRONMENT 328 329=over 4 330 331=item COLUMNS 332 333If B<-t> is given, B<pod2text> will take the current width of your screen 334from this environment variable, if available. It overrides terminal width 335information in TERMCAP. 336 337=item TERMCAP 338 339If B<-t> is given, B<pod2text> will use the contents of this environment 340variable if available to determine the correct formatting sequences for your 341current terminal device. 342 343=back 344 345=head1 SEE ALSO 346 347L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>, 348L<Pod::Text::Termcap>, L<Pod::Simple>, L<perlpod(1)> 349 350The current version of this script is always available from its web site at 351L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 352Perl core distribution as of 5.6.0. 353 354=head1 AUTHOR 355 356Russ Allbery <rra@cpan.org>. 357 358=head1 COPYRIGHT AND LICENSE 359 360Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015, 3612016 Russ Allbery <rra@cpan.org> 362 363This program is free software; you may redistribute it and/or modify it 364under the same terms as Perl itself. 365 366=cut 367SCRIPT_BODY 368 369# Finish the generation of the script. 370close($out) or die "Cannot close $file: $!\n"; 371chmod(0755, $file) or die "Cannot reset permissions for $file: $!\n"; 372if ($Config{'eunicefix'} ne ':') { 373 exec("$Config{'eunicefix'} $file"); 374} 375