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