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 0; # ^ Run only under a 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', 'encoding|e=s', 'errors=s', 85 'guesswork=s', 'help|h', 'indent|i=i', 'loose|l', 86 'margin|left-margin|m=i', 'nourls', 'overstrike|o', 'quotes|q=s', 87 'sentence|s', 'stderr', 'termcap|t', '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 EBCDIC unrepresentable 137 138=head1 NAME 139 140pod2text - Convert POD data to formatted ASCII text 141 142=head1 SYNOPSIS 143 144pod2text [B<-aclostu>] [B<--code>] S<[B<-e> I<encoding>]> 145 [B<--errors>=I<style>] [B<--guesswork>=I<rule>[,I<rule>...]] 146 S<[B<-i> I<indent>]> S<[B<-q> I<quotes>]> 147 [B<--nourls>] [B<--stderr>] S<[B<-w> I<width>]> [I<input> [I<output> ...]] 148 149pod2text B<-h> 150 151=head1 DESCRIPTION 152 153B<pod2text> is a wrapper script around the L<Pod::Text> and its subclasses. 154It uses them to generate formatted text from POD source. It can optionally 155use either termcap sequences or ANSI color escape sequences to format the 156text. 157 158I<input> is the file to read for POD source (the POD can be embedded in code). 159If I<input> isn't given, it defaults to C<STDIN>. I<output>, if given, is the 160file to which to write the formatted output. If I<output> isn't given, the 161formatted output is written to C<STDOUT>. Several POD files can be processed 162in the same B<pod2text> invocation (saving module load and compile times) by 163providing multiple pairs of I<input> and I<output> files on the command line. 164 165By default, the output encoding is the same as the encoding of the input file, 166or UTF-8 if that encoding is not set (except on EBCDIC systems). See the 167B<-e> option to explicitly set the output encoding and L<Pod::Text/Encoding> 168for more discussion. 169 170=head1 OPTIONS 171 172Each option is annotated with the version of podlators in which that option 173was added with its current meaning. 174 175=over 4 176 177=item B<-a>, B<--alt> 178 179[1.00] Use an alternate output format that, among other things, uses a 180different heading style and marks C<=item> entries with a colon in the left 181margin. 182 183=item B<--code> 184 185[1.11] Include any non-POD text from the input file in the output as well. 186Useful for viewing code documented with POD blocks with the POD rendered and 187the code left intact. 188 189=item B<-c>, B<--color> 190 191[1.00] Format the output with ANSI color escape sequences. Using this option 192requires that Term::ANSIColor be installed on your system. 193 194=item B<-e> I<encoding>, B<--encoding>=I<encoding> 195 196[5.00] Specifies the encoding of the output. I<encoding> must be an encoding 197recognized by the L<Encode> module (see L<Encode::Supported>). If the output 198contains characters that cannot be represented in this encoding, that is an 199error that will be reported as configured by the C<errors> option. If error 200handling is other than C<die>, the unrepresentable character will be replaced 201with the Encode substitution character (normally C<?>). 202 203WARNING: The input encoding of the POD source is independent from the output 204encoding, and setting this option does not affect the interpretation of the 205POD input. Unless your POD source is US-ASCII, its encoding should be 206declared with the C<=encoding> command in the source, as near to the top of 207the file as possible. If this is not done, Pod::Simple will will attempt to 208guess the encoding and may be successful if it's Latin-1 or UTF-8, but it will 209produce warnings. See L<perlpod(1)> for more information. 210 211=item B<--errors>=I<style> 212 213[2.5.0] Set the error handling style. C<die> says to throw an exception on 214any POD formatting error. C<stderr> says to report errors on standard error, 215but not to throw an exception. C<pod> says to include a POD ERRORS section in 216the resulting documentation summarizing the errors. C<none> ignores POD 217errors entirely, as much as possible. 218 219The default is C<die>. 220 221=item B<--guesswork>=I<rule>[,I<rule>...] 222 223[5.01] By default, B<pod2text> applies some default formatting rules based on 224guesswork and regular expressions that are intended to make writing Perl 225documentation easier and require less explicit markup. These rules may not 226always be appropriate, particularly for documentation that isn't about Perl. 227This option allows turning all or some of it off. 228 229The special rule C<all> enables all guesswork. This is also the default for 230backward compatibility reasons. The special rule C<none> disables all 231guesswork. Otherwise, the value of this option should be a comma-separated 232list of one or more of the following keywords: 233 234=over 4 235 236=item quoting 237 238If no guesswork is enabled, any text enclosed in CZ<><> is surrounded by 239double quotes in nroff (terminal) output unless the contents are already 240quoted. When this guesswork is enabled, quote marks will also be suppressed 241for Perl variables, function names, function calls, numbers, and hex 242constants. 243 244=back 245 246Any unknown guesswork name is silently ignored (for potential future 247compatibility), so be careful about spelling. 248 249=item B<-i> I<indent>, B<--indent=>I<indent> 250 251[1.00] Set the number of spaces to indent regular text, and the default 252indentation for C<=over> blocks. Defaults to 4 spaces if this option isn't 253given. 254 255=item B<-h>, B<--help> 256 257[1.00] Print out usage information and exit. 258 259=item B<-l>, B<--loose> 260 261[1.00] Print a blank line after a C<=head1> heading. Normally, no blank line 262is printed after C<=head1>, although one is still printed after C<=head2>, 263because this is the expected formatting for manual pages; if you're formatting 264arbitrary text documents, using this option is recommended. 265 266=item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width> 267 268[1.24] The width of the left margin in spaces. Defaults to 0. This is the 269margin for all text, including headings, not the amount by which regular text 270is indented; for the latter, see B<-i> option. 271 272=item B<--nourls> 273 274[2.5.0] Normally, LZ<><> formatting codes with a URL but anchor text are 275formatted to show both the anchor text and the URL. In other words: 276 277 L<foo|http://example.com/> 278 279is formatted as: 280 281 foo <http://example.com/> 282 283This flag, if given, suppresses the URL when anchor text is given, so this 284example would be formatted as just C<foo>. This can produce less cluttered 285output in cases where the URLs are not particularly important. 286 287=item B<-o>, B<--overstrike> 288 289[1.06] Format the output with overstrike printing. Bold text is rendered as 290character, backspace, character. Italics and file names are rendered as 291underscore, backspace, character. Many pagers, such as B<less>, know how to 292convert this to bold or underlined text. 293 294=item B<-q> I<quotes>, B<--quotes>=I<quotes> 295 296[4.00] Sets the quote marks used to surround CE<lt>> text to I<quotes>. If 297I<quotes> is a single character, it is used as both the left and right quote. 298Otherwise, it is split in half, and the first half of the string is used as 299the left quote and the second is used as the right quote. 300 301I<quotes> may also be set to the special value C<none>, in which case no quote 302marks are added around CE<lt>> text. 303 304=item B<-s>, B<--sentence> 305 306[1.00] Assume each sentence ends with two spaces and try to preserve that 307spacing. Without this option, all consecutive whitespace in non-verbatim 308paragraphs is compressed into a single space. 309 310=item B<--stderr> 311 312[2.1.3] By default, B<pod2text> dies if any errors are detected in the POD 313input. If B<--stderr> is given and no B<--errors> flag is present, errors are 314sent to standard error, but B<pod2text> does not abort. This is equivalent to 315C<--errors=stderr> and is supported for backward compatibility. 316 317=item B<-t>, B<--termcap> 318 319[1.00] Try to determine the width of the screen and the bold and underline 320sequences for the terminal from termcap, and use that information in 321formatting the output. Output will be wrapped at two columns less than the 322width of your terminal device. Using this option requires that your system 323have a termcap file somewhere where Term::Cap can find it and requires that 324your system support termios. With this option, the output of B<pod2text> will 325contain terminal control sequences for your current terminal type. 326 327=item B<-u>, B<--utf8> 328 329[2.2.0] Set the output encoding to UTF-8. This is equivalent to 330C<--encoding=UTF-8> and is supported for backward compatibility. 331 332=item B<-w>, B<--width=>I<width>, B<->I<width> 333 334[1.00] The column at which to wrap text on the right-hand side. Defaults to 33576, unless B<-t> is given, in which case it's two columns less than the width 336of your terminal device. 337 338=back 339 340=head1 EXIT STATUS 341 342As long as all documents processed result in some output, even if that output 343includes errata (a C<POD ERRORS> section generated with C<--errors=pod>), 344B<pod2text> will exit with status 0. If any of the documents being processed 345do not result in an output document, B<pod2text> will exit with status 1. If 346there are syntax errors in a POD document being processed and the error 347handling style is set to the default of C<die>, B<pod2text> will abort 348immediately with exit status 255. 349 350=head1 DIAGNOSTICS 351 352If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for 353information about what those errors might mean. Internally, it can also 354produce the following diagnostics: 355 356=over 4 357 358=item -c (--color) requires Term::ANSIColor be installed 359 360(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be loaded. 361 362=item Unknown option: %s 363 364(F) An unknown command line option was given. 365 366=back 367 368In addition, other L<Getopt::Long> error messages may result from invalid 369command-line options. 370 371=head1 ENVIRONMENT 372 373=over 4 374 375=item COLUMNS 376 377If B<-t> is given, B<pod2text> will take the current width of your screen from 378this environment variable, if available. It overrides terminal width 379information in TERMCAP. 380 381=item TERMCAP 382 383If B<-t> is given, B<pod2text> will use the contents of this environment 384variable if available to determine the correct formatting sequences for your 385current terminal device. 386 387=back 388 389=head1 AUTHOR 390 391Russ Allbery <rra@cpan.org>. 392 393=head1 COPYRIGHT AND LICENSE 394 395Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery 396<rra@cpan.org> 397 398This program is free software; you may redistribute it and/or modify it 399under the same terms as Perl itself. 400 401=head1 SEE ALSO 402 403L<Encode::Supported>, L<Pod::Text>, L<Pod::Text::Color>, 404L<Pod::Text::Overstrike>, L<Pod::Text::Termcap>, L<Pod::Simple>, L<perlpod(1)> 405 406The current version of this script is always available from its web site at 407L<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 408Perl core distribution as of 5.6.0. 409 410=cut 411SCRIPT_BODY 412 413# Finish the generation of the script. 414close($out) or die "Cannot close $file: $!\n"; 415chmod(0755, $file) or die "Cannot reset permissions for $file: $!\n"; 416if ($Config{'eunicefix'} ne ':') { 417 exec("$Config{'eunicefix'} $file"); 418} 419 420# Local Variables: 421# copyright-at-end-flag: t 422# End: 423