codekingpro/portable-devtools

1#!/usr/bin/perl2eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'3  if 0;    # ^ Run only under a shell4 5# Convert POD data to formatted *roff input.6#7# The driver script for Pod::Man.8#9# SPDX-License-Identifier: GPL-1.0-or-later OR Artistic-1.0-Perl10 11use 5.012;12use warnings;13 14use Getopt::Long qw(GetOptions);15use Pod::Man ();16use Pod::Usage qw(pod2usage);17 18# Format a single POD file.19#20# $parser  - Pod::Man object to use21# $input   - Input file, - or undef for standard input22# $output  - Output file, - or undef for standard output23# $verbose - Whether to print each file to standard output when converted24#25# Returns: 0 on no errors, 1 if there was an error26sub format_file {27    my ($parser, $input, $output, $verbose) = @_;28    my $to_stdout = !defined($output) || $output eq q{-};29    if ($verbose && !$to_stdout) {30        print "  $output\n" or warn "$0: cannot write to stdout: $!\n";31    }32    $parser->parse_from_file($input, $output);33    if ($parser->{CONTENTLESS}) {34        if (defined($input) && $input ne q{-}) {35            warn "$0: unable to format $input\n";36        } else {37            warn "$0: unable to format standard input\n";38        }39        if (!$to_stdout && !-s $output) {40            unlink($output);41        }42        return 1;43    }44    return 0;45}46 47# Clean up $0 for error reporting.48$0 =~ s{ .*/ }{}xms;49 50# Insert -- into @ARGV before any single dash argument to hide it from51# Getopt::Long; we want to interpret it as meaning stdin.52my $stdin;53local @ARGV = map { $_ eq q{-} && !$stdin++ ? (q{--}, $_) : $_ } @ARGV;54 55# Parse our options, trying to retain backward compatibility with pod2man but56# allowing short forms as well.  --lax is currently ignored.57my %options;58Getopt::Long::config('bundling_override');59GetOptions(60    \%options,61    'center|c=s',62    'date|d=s',63    'encoding|e=s',64    'errors=s',65    'fixed=s',66    'fixedbold=s',67    'fixeditalic=s',68    'fixedbolditalic=s',69    'guesswork=s',70    'help|h',71    'lax|l',72    'language=s',73    'lquote=s',74    'name|n=s',75    'nourls',76    'official|o',77    'quotes|q=s',78    'release|r=s',79    'rquote=s',80    'section|s=s',81    'stderr',82    'verbose|v',83    'utf8|u',84) or exit 1;85if ($options{help}) {86    pod2usage(0);87}88 89# Official sets --center, but don't override things explicitly set.90if ($options{official} && !defined($options{center})) {91    $options{center} = 'Perl Programmers Reference Guide';92}93 94# Delete flags that are only used in pod2man, not in Pod::Man. lax is accepted95# only for backward compatibility and does nothing.96my $verbose = $options{verbose};97delete @options{qw(verbose lax official)};98 99# If neither stderr nor errors is set, default to errors = die rather than the100# Pod::Man default of pod.101if (!defined($options{stderr}) && !defined($options{errors})) {102    $options{errors} = 'die';103}104 105# If given no arguments, read from stdin and write to stdout.106if (!@ARGV) {107    push(@ARGV, q{-});108}109 110# Initialize and run the formatter, pulling a pair of input and output off at111# a time. For each file, we check whether the document was completely empty112# and, if so, will remove the created file and exit with a non-zero exit113# status.114my $parser = Pod::Man->new(%options);115my $status = 0;116while (@ARGV) {117    my ($input, $output) = splice(@ARGV, 0, 2);118    my $result = format_file($parser, $input, $output, $verbose);119    $status ||= $result;120}121exit($status);122 123__END__124 125=for stopwords126en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris URL127troff troff-specific formatters uppercased Christiansen --nourls UTC prepend128lquote rquote unrepresentable mandoc manref EBCDIC129 130=head1 NAME131 132pod2man - Convert POD data to formatted *roff input133 134=head1 SYNOPSIS135 136pod2man [B<--center>=I<string>] [B<--date>=I<string>]137    [B<--encoding>=I<encoding>] [B<--errors>=I<style>] [B<--fixed>=I<font>]138    [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]139    [B<--fixedbolditalic>=I<font>] [B<--guesswork>=I<rule>[,I<rule>...]]140    [B<--name>=I<name>] [B<--nourls>] [B<--official>]141    [B<--release>=I<version>] [B<--section>=I<manext>]142    [B<--quotes>=I<quotes>] [B<--lquote>=I<quote>] [B<--rquote>=I<quote>]143    [B<--stderr>] [B<--utf8>] [B<--verbose>] [I<input> [I<output>] ...]144 145pod2man B<--help>146 147=head1 DESCRIPTION148 149B<pod2man> is a wrapper script around the L<Pod::Man> module, using it to150generate *roff input from POD source.  The resulting *roff code is suitable151for display on a terminal using L<nroff(1)>, normally via L<man(1)>, or152printing using L<troff(1)>.153 154By default (on non-EBCDIC systems), B<pod2man> outputs UTF-8 manual pages.155Its output should work with the B<man> program on systems that use B<groff>156(most Linux distributions) or B<mandoc> (most BSD variants), but may result in157mangled output on older UNIX systems.  To choose a different, possibly more158backward-compatible output mangling on such systems, use C<--encoding=roff>159(the default in earlier Pod::Man versions).  See the B<--encoding> option and160L<Pod::Man/ENCODING> for more details.161 162I<input> is the file to read for POD source (the POD can be embedded in code).163If I<input> isn't given, it defaults to C<STDIN>.  I<output>, if given, is the164file to which to write the formatted output.  If I<output> isn't given, the165formatted output is written to C<STDOUT>.  Several POD files can be processed166in the same B<pod2man> invocation (saving module load and compile times) by167providing multiple pairs of I<input> and I<output> files on the command line.168 169B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be170used to set the headers and footers to use.  If not given, Pod::Man will171assume various defaults.  See below for details.172 173For specific details and caveats about the translation from POD to *roff, see174L<Pod::Man/CAVEATS>.175 176=head1 OPTIONS177 178Each option is annotated with the version of podlators in which that option179was added with its current meaning.180 181=over 4182 183=item B<-c> I<string>, B<--center>=I<string>184 185[1.00] Sets the centered page header for the C<.TH> macro to I<string>.  The186default is C<User Contributed Perl Documentation>, but also see B<--official>187below.188 189=item B<-d> I<string>, B<--date>=I<string>190 191[4.00] Set the left-hand footer string for the C<.TH> macro to I<string>.  By192default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH, the modification date193of the input file, or the current date (if input comes from C<STDIN>) will be194used, and the date will be in UTC.  See L<Pod::Man/CLASS METHODS> for more195details.196 197=item B<-e> I<encoding>, B<--encoding>=I<encoding>198 199[5.00] Specifies the encoding of the output.  I<encoding> must be an encoding200recognized by the L<Encode> module (see L<Encode::Supported>).  The default on201non-EBCDIC systems is UTF-8.202 203If the output contains characters that cannot be represented in this encoding,204that is an error that will be reported as configured by the B<--errors>205option.  If error handling is other than C<die>, the unrepresentable character206will be replaced with the Encode substitution character (normally C<?>).207 208If the C<encoding> option is set to the special value C<groff> (the default on209EBCDIC systems), or if the Encode module is not available and the encoding is210set to anything other than C<roff> (see below), Pod::Man will translate all211non-ASCII characters to C<\[uNNNN]> Unicode escapes.  These are not212traditionally part of the *roff language, but are supported by B<groff> and213B<mandoc> and thus by the majority of manual page processors in use today.214 215If I<encoding> is set to the special value C<roff>, B<pod2man> will do its216historic transformation of (some) ISO 8859-1 characters into *roff escapes217that may be adequate in troff and may be readable (if ugly) in nroff.  This218was the default behavior of versions of B<pod2man> before 5.00.  With this219encoding, all other non-ASCII characters will be replaced with C<X>.  It may220be required for very old troff and nroff implementations that do not support221UTF-8, but its representation of any non-ASCII character is very poor and222often specific to European languages.  Its use is discouraged.223 224WARNING: The input encoding of the POD source is independent from the output225encoding, and setting this option does not affect the interpretation of the226POD input.  Unless your POD source is US-ASCII, its encoding should be227declared with the C<=encoding> command in the source.  If this is not done,228Pod::Simple will will attempt to guess the encoding and may be successful if229it's Latin-1 or UTF-8, but it will produce warnings.  See L<perlpod(1)> for230more information.231 232=item B<--errors>=I<style>233 234[2.5.0] Set the error handling style.  C<die> says to throw an exception on235any POD formatting error.  C<stderr> says to report errors on standard error,236but not to throw an exception.  C<pod> says to include a POD ERRORS section in237the resulting documentation summarizing the errors.  C<none> ignores POD238errors entirely, as much as possible.239 240The default is C<die>.241 242=item B<--fixed>=I<font>243 244[1.0] The fixed-width font to use for verbatim text and code.  Defaults to245C<CW>.  Some systems may want C<CR> instead.  Only matters for B<troff>246output.247 248=item B<--fixedbold>=I<font>249 250[1.0] Bold version of the fixed-width font.  Defaults to C<CB>.  Only matters251for B<troff> output.252 253=item B<--fixeditalic>=I<font>254 255[1.0] Italic version of the fixed-width font (something of a misnomer, since256most fixed-width fonts only have an oblique version, not an italic version).257Defaults to C<CI>.  Only matters for B<troff> output.258 259=item B<--fixedbolditalic>=I<font>260 261[1.0] Bold italic (in theory, probably oblique in practice) version of the262fixed-width font.  Pod::Man doesn't assume you have this, and defaults to263C<CB>.  Some systems (such as Solaris) have this font available as C<CX>.264Only matters for B<troff> output.265 266=item B<--guesswork>=I<rule>[,I<rule>...]267 268[5.00] By default, B<pod2man> applies some default formatting rules based on269guesswork and regular expressions that are intended to make writing Perl270documentation easier and require less explicit markup.  These rules may not271always be appropriate, particularly for documentation that isn't about Perl.272This option allows turning all or some of it off.273 274The special rule C<all> enables all guesswork.  This is also the default for275backward compatibility reasons.  The special rule C<none> disables all276guesswork.  Otherwise, the value of this option should be a comma-separated277list of one or more of the following keywords:278 279=over 4280 281=item functions282 283Convert function references like C<foo()> to bold even if they have no markup.284The function name accepts valid Perl characters for function names (including285C<:>), and the trailing parentheses must be present and empty.286 287=item manref288 289Make the first part (before the parentheses) of man page references like290C<foo(1)> bold even if they have no markup.  The section must be a single291number optionally followed by lowercase letters.292 293=item quoting294 295If no guesswork is enabled, any text enclosed in CZ<><> is surrounded by296double quotes in nroff (terminal) output unless the contents are already297quoted.  When this guesswork is enabled, quote marks will also be suppressed298for Perl variables, function names, function calls, numbers, and hex299constants.300 301=item variables302 303Convert Perl variable names to a fixed-width font even if they have no markup.304This transformation will only be apparent in troff output, or some other305output format (unlike nroff terminal output) that supports fixed-width fonts.306 307=back308 309Any unknown guesswork name is silently ignored (for potential future310compatibility), so be careful about spelling.311 312=item B<-h>, B<--help>313 314[1.00] Print out usage information.315 316=item B<-l>, B<--lax>317 318[1.00] No longer used.  B<pod2man> used to check its input for validity as a319manual page, but this should now be done by L<podchecker(1)> instead.320Accepted for backward compatibility; this option no longer does anything.321 322=item B<--language>=I<language>323 324[5.00] Add commands telling B<groff> that the input file is in the given325language.  The value of this setting must be a language abbreviation for which326B<groff> provides supplemental configuration, such as C<ja> (for Japanese) or327C<zh> (for Chinese).328 329This adds:330 331    .mso <language>.tmac332    .hla <language>333 334to the start of the file, which configure correct line breaking for the335specified language.  Without these commands, groff may not know how to add336proper line breaks for Chinese and Japanese text if the man page is installed337into the normal man page directory, such as F</usr/share/man>.338 339On many systems, this will be done automatically if the man page is installed340into a language-specific man page directory, such as F</usr/share/man/zh_CN>.341In that case, this option is not required.342 343Unfortunately, the commands added with this option are specific to B<groff>344and will not work with other B<troff> and B<nroff> implementations.345 346=item B<--lquote>=I<quote>347 348=item B<--rquote>=I<quote>349 350[4.08] Sets the quote marks used to surround CE<lt>> text.  B<--lquote> sets351the left quote mark and B<--rquote> sets the right quote mark.  Either may352also be set to the special value C<none>, in which case no quote mark is added353on that side of CE<lt>> text (but the font is still changed for troff output).354 355Also see the B<--quotes> option, which can be used to set both quotes at once.356If both B<--quotes> and one of the other options is set, B<--lquote> or357B<--rquote> overrides B<--quotes>.358 359=item B<-n> I<name>, B<--name>=I<name>360 361[4.08] Set the name of the manual page for the C<.TH> macro to I<name>.362Without this option, the manual name is set to the uppercased base name of the363file being converted unless the manual section is 3, in which case the path is364parsed to see if it is a Perl module path.  If it is, a path like365C<.../lib/Pod/Man.pm> is converted into a name like C<Pod::Man>.  This option,366if given, overrides any automatic determination of the name.367 368Although one does not have to follow this convention, be aware that the369convention for UNIX manual pages is for the title to be in all-uppercase, even370if the command isn't.  (Perl modules traditionally use mixed case for the371manual page title, however.)372 373This option is probably not useful when converting multiple POD files at once.374 375When converting POD source from standard input, the name will be set to376C<STDIN> if this option is not provided.  Providing this option is strongly377recommended to set a meaningful manual page name.378 379=item B<--nourls>380 381[2.5.0] Normally, LZ<><> formatting codes with a URL but anchor text are382formatted to show both the anchor text and the URL.  In other words:383 384=for ProhibitVerbatimMarkup allow next385 386    L<foo|http://example.com/>387 388is formatted as:389 390    foo <http://example.com/>391 392This flag, if given, suppresses the URL when anchor text is given, so this393example would be formatted as just C<foo>.  This can produce less394cluttered output in cases where the URLs are not particularly important.395 396=item B<-o>, B<--official>397 398[1.00] Set the default header to indicate that this page is part of the399standard Perl release, if B<--center> is not also given.400 401=item B<-q> I<quotes>, B<--quotes>=I<quotes>402 403[4.00] Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If404I<quotes> is a single character, it is used as both the left and right quote.405Otherwise, it is split in half, and the first half of the string is used as406the left quote and the second is used as the right quote.407 408I<quotes> may also be set to the special value C<none>, in which case no quote409marks are added around CE<lt>> text (but the font is still changed for troff410output).411 412Also see the B<--lquote> and B<--rquote> options, which can be used to set the413left and right quotes independently.  If both B<--quotes> and one of the other414options is set, B<--lquote> or B<--rquote> overrides B<--quotes>.415 416=item B<-r> I<version>, B<--release>=I<version>417 418[1.00] Set the centered footer for the C<.TH> macro to I<version>.  By419default, this is set to the version of Perl you run B<pod2man> under.  Setting420this to the empty string will cause some *roff implementations to use the421system default value.422 423Note that some system C<an> macro sets assume that the centered footer will be424a modification date and will prepend something like C<Last modified: >.  If425this is the case for your target system, you may want to set B<--release> to426the last modified date and B<--date> to the version number.427 428=item B<-s> I<string>, B<--section>=I<string>429 430[1.00] Set the section for the C<.TH> macro.  The standard section numbering431convention is to use 1 for user commands, 2 for system calls, 3 for functions,4324 for devices, 5 for file formats, 6 for games, 7 for miscellaneous433information, and 8 for administrator commands.  There is a lot of variation434here, however; some systems (like Solaris) use 4 for file formats, 5 for435miscellaneous information, and 7 for devices.  Still others use 1m instead of4368, or some mix of both.  About the only section numbers that are reliably437consistent are 1, 2, and 3.438 439By default, section 1 will be used unless the file ends in C<.pm>, in which440case section 3 will be selected.441 442=item B<--stderr>443 444[2.1.3] By default, B<pod2man> dies if any errors are detected in the POD445input.  If B<--stderr> is given and no B<--errors> flag is present, errors are446sent to standard error, but B<pod2man> does not abort.  This is equivalent to447C<--errors=stderr> and is supported for backward compatibility.448 449=item B<-u>, B<--utf8>450 451[2.1.0] This option used to tell B<pod2man> to produce UTF-8 output.  Since452this is now the default as of version 5.00, it is ignored and does nothing.453 454=item B<-v>, B<--verbose>455 456[1.11] Print out the name of each output file as it is being generated.457 458=back459 460=head1 EXIT STATUS461 462As long as all documents processed result in some output, even if that output463includes errata (a C<POD ERRORS> section generated with C<--errors=pod>),464B<pod2man> will exit with status 0.  If any of the documents being processed465do not result in an output document, B<pod2man> will exit with status 1.  If466there are syntax errors in a POD document being processed and the error467handling style is set to the default of C<die>, B<pod2man> will abort468immediately with exit status 255.469 470=head1 DIAGNOSTICS471 472If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for473information about what those errors might mean.474 475=head1 EXAMPLES476 477    pod2man program > program.1478    pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3479    pod2man --section=7 note.pod > note.7480 481If you would like to print out a lot of man page continuously, you probably482want to set the C and D registers to set contiguous page numbering and483even/odd paging, at least on some versions of man(7).484 485    troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...486 487To get index entries on C<STDERR>, turn on the F register, as in:488 489    troff -man -rF1 perl.1490 491The indexing merely outputs messages via C<.tm> for each major page, section,492subsection, item, and any C<XE<lt>E<gt>> directives.493 494=head1 AUTHOR495 496Russ Allbery <rra@cpan.org>, based on the original B<pod2man> by Larry Wall497and Tom Christiansen.498 499=head1 COPYRIGHT AND LICENSE500 501Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022-2024 Russ Allbery502<rra@cpan.org>503 504This program is free software; you may redistribute it and/or modify it505under the same terms as Perl itself.506 507=head1 SEE ALSO508 509L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,510L<podchecker(1)>, L<perlpodstyle(1)>, L<troff(1)>511 512The man page documenting the C<an> macro set is usually either L<man(7)> or513L<man(5)> depending on the system.514 515The current version of this script is always available from its web site at516L<https://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the517Perl core distribution as of 5.6.0.518 519=cut520