1b8851fccSafresh1#!/usr/bin/perl 2b8851fccSafresh1# 3b8851fccSafresh1# Special wrapper script to generate the actual pod2man script. This is 4b8851fccSafresh1# required for proper start-up code on non-UNIX platforms, and is used inside 5b8851fccSafresh1# Perl core. 6898184e3Ssthen 756d68f1eSafresh1use 5.008; 8b8851fccSafresh1use strict; 9b8851fccSafresh1use warnings; 10898184e3Ssthen 11b8851fccSafresh1use Config qw(%Config); 12b8851fccSafresh1use Cwd qw(cwd); 13b8851fccSafresh1use File::Basename qw(basename dirname); 14b8851fccSafresh1 15b8851fccSafresh1# List explicitly here the variables you want Configure to generate. 16b8851fccSafresh1# Metaconfig only looks for shell variables, so you have to mention them as if 17b8851fccSafresh1# they were shell variables, not %Config entries. Thus you write 18898184e3Ssthen# $startperl 19898184e3Ssthen# to ensure Configure will look for $Config{startperl}. 20898184e3Ssthen 21898184e3Ssthen# This forces PL files to create target in same directory as PL file. 22898184e3Ssthen# This is so that make depend always knows where to find PL derivatives. 23b8851fccSafresh1chdir(dirname($0)) or die "Cannot change directories: $!\n"; 24b8851fccSafresh1my $file = basename($0, '.PL'); 25b8851fccSafresh1if ($^O eq 'VMS') { 26b8851fccSafresh1 $file .= '.com'; 27b8851fccSafresh1} 28898184e3Ssthen 29b8851fccSafresh1# Create the generated script. 30b8851fccSafresh1## no critic (InputOutput::RequireBriefOpen) 31b8851fccSafresh1## no critic (InputOutput::RequireCheckedSyscalls) 32b8851fccSafresh1open(my $out, '>', $file) or die "Cannot create $file: $!\n"; 33898184e3Ssthenprint "Extracting $file (with variable substitutions)\n"; 34b8851fccSafresh1## use critic 35898184e3Ssthen 36b8851fccSafresh1# In this section, Perl variables will be expanded during extraction. You can 37b8851fccSafresh1# use $Config{...} to use Configure variables. 38b8851fccSafresh1print {$out} <<"PREAMBLE" or die "Cannot write to $file: $!\n"; 39898184e3Ssthen$Config{startperl} 40898184e3Ssthen eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' 41*e0680481Safresh1 if 0; # ^ Run only under a shell 42b8851fccSafresh1PREAMBLE 43898184e3Ssthen 44b8851fccSafresh1# In the following, Perl variables are not expanded during extraction. 45b8851fccSafresh1print {$out} <<'SCRIPT_BODY' or die "Cannot write to $file: $!\n"; 46898184e3Ssthen 47b46d8ef2Safresh1# Convert POD data to formatted *roff input. 48898184e3Ssthen# 49b46d8ef2Safresh1# The driver script for Pod::Man. 50898184e3Ssthen# 51b46d8ef2Safresh1# SPDX-License-Identifier: GPL-1.0-or-later OR Artistic-1.0-Perl 52898184e3Ssthen 53b8851fccSafresh1use 5.006; 54b8851fccSafresh1use strict; 55b8851fccSafresh1use warnings; 56898184e3Ssthen 57898184e3Ssthenuse Getopt::Long qw(GetOptions); 58898184e3Ssthenuse Pod::Man (); 59898184e3Ssthenuse Pod::Usage qw(pod2usage); 60898184e3Ssthen 61898184e3Ssthenuse strict; 62898184e3Ssthen 6391f110e0Safresh1# Clean up $0 for error reporting. 6491f110e0Safresh1$0 =~ s%.*/%%; 6591f110e0Safresh1 66898184e3Ssthen# Insert -- into @ARGV before any single dash argument to hide it from 67898184e3Ssthen# Getopt::Long; we want to interpret it as meaning stdin. 68898184e3Ssthenmy $stdin; 69898184e3Ssthen@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; 70898184e3Ssthen 71898184e3Ssthen# Parse our options, trying to retain backward compatibility with pod2man but 72898184e3Ssthen# allowing short forms as well. --lax is currently ignored. 73898184e3Ssthenmy %options; 74898184e3SsthenGetopt::Long::config ('bundling_override'); 75*e0680481Safresh1GetOptions (\%options, 'center|c=s', 'date|d=s', 'encoding|e=s', 'errors=s', 76*e0680481Safresh1 'fixed=s', 'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 77*e0680481Safresh1 'guesswork=s', 'help|h', 'lax|l', 'language=s', 'lquote=s', 78*e0680481Safresh1 'name|n=s', 'nourls', 'official|o', 'quotes|q=s', 'release|r=s', 79*e0680481Safresh1 'rquote=s', 'section|s=s', 'stderr', 'verbose|v', 'utf8|u') 8091f110e0Safresh1 or exit 1; 81898184e3Ssthenpod2usage (0) if $options{help}; 82898184e3Ssthen 83898184e3Ssthen# Official sets --center, but don't override things explicitly set. 84898184e3Ssthenif ($options{official} && !defined $options{center}) { 85898184e3Ssthen $options{center} = 'Perl Programmers Reference Guide'; 86898184e3Ssthen} 87898184e3Ssthen 88898184e3Ssthen# Verbose is only our flag, not a Pod::Man flag. 89898184e3Ssthenmy $verbose = $options{verbose}; 90898184e3Ssthendelete $options{verbose}; 91898184e3Ssthen 92898184e3Ssthen# This isn't a valid Pod::Man option and is only accepted for backward 93898184e3Ssthen# compatibility. 94898184e3Ssthendelete $options{lax}; 95898184e3Ssthen 9691f110e0Safresh1# If neither stderr nor errors is set, default to errors = die. 9791f110e0Safresh1if (!defined $options{stderr} && !defined $options{errors}) { 9891f110e0Safresh1 $options{errors} = 'die'; 9991f110e0Safresh1} 10091f110e0Safresh1 101898184e3Ssthen# Initialize and run the formatter, pulling a pair of input and output off at 10291f110e0Safresh1# a time. For each file, we check whether the document was completely empty 10391f110e0Safresh1# and, if so, will remove the created file and exit with a non-zero exit 10491f110e0Safresh1# status. 105898184e3Ssthenmy $parser = Pod::Man->new (%options); 10691f110e0Safresh1my $status = 0; 107898184e3Ssthenmy @files; 108898184e3Ssthendo { 109898184e3Ssthen @files = splice (@ARGV, 0, 2); 110898184e3Ssthen print " $files[1]\n" if $verbose; 111898184e3Ssthen $parser->parse_from_file (@files); 11291f110e0Safresh1 if ($parser->{CONTENTLESS}) { 11391f110e0Safresh1 $status = 1; 1149f11ffb7Safresh1 if (defined $files[0]) { 11591f110e0Safresh1 warn "$0: unable to format $files[0]\n"; 1169f11ffb7Safresh1 } else { 1179f11ffb7Safresh1 warn "$0: unable to format standard input\n"; 1189f11ffb7Safresh1 } 11991f110e0Safresh1 if (defined ($files[1]) and $files[1] ne '-') { 12091f110e0Safresh1 unlink $files[1] unless (-s $files[1]); 12191f110e0Safresh1 } 12291f110e0Safresh1 } 123898184e3Ssthen} while (@ARGV); 12491f110e0Safresh1exit $status; 125898184e3Ssthen 126898184e3Ssthen__END__ 127898184e3Ssthen 12891f110e0Safresh1=for stopwords 129*e0680481Safresh1en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris URL 130b46d8ef2Safresh1troff troff-specific formatters uppercased Christiansen --nourls UTC prepend 131*e0680481Safresh1lquote rquote unrepresentable mandoc manref EBCDIC 13291f110e0Safresh1 133898184e3Ssthen=head1 NAME 134898184e3Ssthen 135898184e3Ssthenpod2man - Convert POD data to formatted *roff input 136898184e3Ssthen 137898184e3Ssthen=head1 SYNOPSIS 138898184e3Ssthen 139*e0680481Safresh1pod2man [B<--center>=I<string>] [B<--date>=I<string>] 140*e0680481Safresh1 [B<--encoding>=I<encoding>] [B<--errors>=I<style>] [B<--fixed>=I<font>] 141*e0680481Safresh1 [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] 142*e0680481Safresh1 [B<--fixedbolditalic>=I<font>] [B<--guesswork>=I<rule>[,I<rule>...]] 143*e0680481Safresh1 [B<--name>=I<name>] [B<--nourls>] [B<--official>] 144*e0680481Safresh1 [B<--release>=I<version>] [B<--section>=I<manext>] 1459f11ffb7Safresh1 [B<--quotes>=I<quotes>] [B<--lquote>=I<quote>] [B<--rquote>=I<quote>] 146*e0680481Safresh1 [B<--stderr>] [B<--utf8>] [B<--verbose>] [I<input> [I<output>] ...] 147898184e3Ssthen 148898184e3Ssthenpod2man B<--help> 149898184e3Ssthen 150898184e3Ssthen=head1 DESCRIPTION 151898184e3Ssthen 152*e0680481Safresh1B<pod2man> is a wrapper script around the L<Pod::Man> module, using it to 153*e0680481Safresh1generate *roff input from POD source. The resulting *roff code is suitable 154*e0680481Safresh1for display on a terminal using L<nroff(1)>, normally via L<man(1)>, or 155*e0680481Safresh1printing using L<troff(1)>. 156898184e3Ssthen 157*e0680481Safresh1By default (on non-EBCDIC systems), B<pod2man> outputs UTF-8 manual pages. 158*e0680481Safresh1Its output should work with the B<man> program on systems that use B<groff> 159*e0680481Safresh1(most Linux distributions) or B<mandoc> (most BSD variants), but may result in 160*e0680481Safresh1mangled output on older UNIX systems. To choose a different, possibly more 161*e0680481Safresh1backward-compatible output mangling on such systems, use C<--encoding=roff> 162*e0680481Safresh1(the default in earlier Pod::Man versions). See the B<--encoding> option and 163*e0680481Safresh1L<Pod::Man/ENCODING> for more details. 164898184e3Ssthen 165*e0680481Safresh1I<input> is the file to read for POD source (the POD can be embedded in code). 166*e0680481Safresh1If I<input> isn't given, it defaults to C<STDIN>. I<output>, if given, is the 167*e0680481Safresh1file to which to write the formatted output. If I<output> isn't given, the 168*e0680481Safresh1formatted output is written to C<STDOUT>. Several POD files can be processed 169*e0680481Safresh1in the same B<pod2man> invocation (saving module load and compile times) by 170*e0680481Safresh1providing multiple pairs of I<input> and I<output> files on the command line. 171898184e3Ssthen 172*e0680481Safresh1B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be 173*e0680481Safresh1used to set the headers and footers to use. If not given, Pod::Man will 174*e0680481Safresh1assume various defaults. See below for details. 175898184e3Ssthen 176898184e3Ssthen=head1 OPTIONS 177898184e3Ssthen 178*e0680481Safresh1Each option is annotated with the version of podlators in which that option 179*e0680481Safresh1was added with its current meaning. 180*e0680481Safresh1 181898184e3Ssthen=over 4 182898184e3Ssthen 183898184e3Ssthen=item B<-c> I<string>, B<--center>=I<string> 184898184e3Ssthen 185*e0680481Safresh1[1.00] Sets the centered page header for the C<.TH> macro to I<string>. The 186*e0680481Safresh1default is C<User Contributed Perl Documentation>, but also see B<--official> 187*e0680481Safresh1below. 188898184e3Ssthen 189898184e3Ssthen=item B<-d> I<string>, B<--date>=I<string> 190898184e3Ssthen 191*e0680481Safresh1[4.00] Set the left-hand footer string for the C<.TH> macro to I<string>. By 192*e0680481Safresh1default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH, the modification date 193*e0680481Safresh1of the input file, or the current date (if input comes from C<STDIN>) will be 194*e0680481Safresh1used, and the date will be in UTC. See L<Pod::Man/CLASS METHODS> for more 195*e0680481Safresh1details. 196*e0680481Safresh1 197*e0680481Safresh1=item B<-e> I<encoding>, B<--encoding>=I<encoding> 198*e0680481Safresh1 199*e0680481Safresh1[5.00] Specifies the encoding of the output. I<encoding> must be an encoding 200*e0680481Safresh1recognized by the L<Encode> module (see L<Encode::Supported>). The default on 201*e0680481Safresh1non-EBCDIC systems is UTF-8. 202*e0680481Safresh1 203*e0680481Safresh1If the output contains characters that cannot be represented in this encoding, 204*e0680481Safresh1that is an error that will be reported as configured by the B<--errors> 205*e0680481Safresh1option. If error handling is other than C<die>, the unrepresentable character 206*e0680481Safresh1will be replaced with the Encode substitution character (normally C<?>). 207*e0680481Safresh1 208*e0680481Safresh1If the C<encoding> option is set to the special value C<groff> (the default on 209*e0680481Safresh1EBCDIC systems), or if the Encode module is not available and the encoding is 210*e0680481Safresh1set to anything other than C<roff> (see below), Pod::Man will translate all 211*e0680481Safresh1non-ASCII characters to C<\[uNNNN]> Unicode escapes. These are not 212*e0680481Safresh1traditionally part of the *roff language, but are supported by B<groff> and 213*e0680481Safresh1B<mandoc> and thus by the majority of manual page processors in use today. 214*e0680481Safresh1 215*e0680481Safresh1If I<encoding> is set to the special value C<roff>, B<pod2man> will do its 216*e0680481Safresh1historic transformation of (some) ISO 8859-1 characters into *roff escapes 217*e0680481Safresh1that may be adequate in troff and may be readable (if ugly) in nroff. This 218*e0680481Safresh1was the default behavior of versions of B<pod2man> before 5.00. With this 219*e0680481Safresh1encoding, all other non-ASCII characters will be replaced with C<X>. It may 220*e0680481Safresh1be required for very old troff and nroff implementations that do not support 221*e0680481Safresh1UTF-8, but its representation of any non-ASCII character is very poor and 222*e0680481Safresh1often specific to European languages. Its use is discouraged. 223*e0680481Safresh1 224*e0680481Safresh1WARNING: The input encoding of the POD source is independent from the output 225*e0680481Safresh1encoding, and setting this option does not affect the interpretation of the 226*e0680481Safresh1POD input. Unless your POD source is US-ASCII, its encoding should be 227*e0680481Safresh1declared with the C<=encoding> command in the source. If this is not done, 228*e0680481Safresh1Pod::Simple will will attempt to guess the encoding and may be successful if 229*e0680481Safresh1it's Latin-1 or UTF-8, but it will produce warnings. See L<perlpod(1)> for 230*e0680481Safresh1more information. 231898184e3Ssthen 232b8851fccSafresh1=item B<--errors>=I<style> 23391f110e0Safresh1 234*e0680481Safresh1[2.5.0] Set the error handling style. C<die> says to throw an exception on 235*e0680481Safresh1any POD formatting error. C<stderr> says to report errors on standard error, 236*e0680481Safresh1but not to throw an exception. C<pod> says to include a POD ERRORS section in 237*e0680481Safresh1the resulting documentation summarizing the errors. C<none> ignores POD 238*e0680481Safresh1errors entirely, as much as possible. 23991f110e0Safresh1 24091f110e0Safresh1The default is C<die>. 24191f110e0Safresh1 242898184e3Ssthen=item B<--fixed>=I<font> 243898184e3Ssthen 244*e0680481Safresh1[1.0] The fixed-width font to use for verbatim text and code. Defaults to 245*e0680481Safresh1C<CW>. Some systems may want C<CR> instead. Only matters for B<troff> 246898184e3Ssthenoutput. 247898184e3Ssthen 248898184e3Ssthen=item B<--fixedbold>=I<font> 249898184e3Ssthen 250*e0680481Safresh1[1.0] Bold version of the fixed-width font. Defaults to C<CB>. Only matters 251*e0680481Safresh1for B<troff> output. 252898184e3Ssthen 253898184e3Ssthen=item B<--fixeditalic>=I<font> 254898184e3Ssthen 255*e0680481Safresh1[1.0] Italic version of the fixed-width font (something of a misnomer, since 256*e0680481Safresh1most fixed-width fonts only have an oblique version, not an italic version). 257*e0680481Safresh1Defaults to C<CI>. Only matters for B<troff> output. 258898184e3Ssthen 259898184e3Ssthen=item B<--fixedbolditalic>=I<font> 260898184e3Ssthen 261*e0680481Safresh1[1.0] Bold italic (in theory, probably oblique in practice) version of the 262*e0680481Safresh1fixed-width font. Pod::Man doesn't assume you have this, and defaults to 263*e0680481Safresh1C<CB>. Some systems (such as Solaris) have this font available as C<CX>. 264*e0680481Safresh1Only matters for B<troff> output. 265*e0680481Safresh1 266*e0680481Safresh1=item B<--guesswork>=I<rule>[,I<rule>...] 267*e0680481Safresh1 268*e0680481Safresh1[5.00] By default, B<pod2man> applies some default formatting rules based on 269*e0680481Safresh1guesswork and regular expressions that are intended to make writing Perl 270*e0680481Safresh1documentation easier and require less explicit markup. These rules may not 271*e0680481Safresh1always be appropriate, particularly for documentation that isn't about Perl. 272*e0680481Safresh1This option allows turning all or some of it off. 273*e0680481Safresh1 274*e0680481Safresh1The special rule C<all> enables all guesswork. This is also the default for 275*e0680481Safresh1backward compatibility reasons. The special rule C<none> disables all 276*e0680481Safresh1guesswork. Otherwise, the value of this option should be a comma-separated 277*e0680481Safresh1list of one or more of the following keywords: 278*e0680481Safresh1 279*e0680481Safresh1=over 4 280*e0680481Safresh1 281*e0680481Safresh1=item functions 282*e0680481Safresh1 283*e0680481Safresh1Convert function references like C<foo()> to bold even if they have no markup. 284*e0680481Safresh1The function name accepts valid Perl characters for function names (including 285*e0680481Safresh1C<:>), and the trailing parentheses must be present and empty. 286*e0680481Safresh1 287*e0680481Safresh1=item manref 288*e0680481Safresh1 289*e0680481Safresh1Make the first part (before the parentheses) of man page references like 290*e0680481Safresh1C<foo(1)> bold even if they have no markup. The section must be a single 291*e0680481Safresh1number optionally followed by lowercase letters. 292*e0680481Safresh1 293*e0680481Safresh1=item quoting 294*e0680481Safresh1 295*e0680481Safresh1If no guesswork is enabled, any text enclosed in CZ<><> is surrounded by 296*e0680481Safresh1double quotes in nroff (terminal) output unless the contents are already 297*e0680481Safresh1quoted. When this guesswork is enabled, quote marks will also be suppressed 298*e0680481Safresh1for Perl variables, function names, function calls, numbers, and hex 299*e0680481Safresh1constants. 300*e0680481Safresh1 301*e0680481Safresh1=item variables 302*e0680481Safresh1 303*e0680481Safresh1Convert Perl variable names to a fixed-width font even if they have no markup. 304*e0680481Safresh1This transformation will only be apparent in troff output, or some other 305*e0680481Safresh1output format (unlike nroff terminal output) that supports fixed-width fonts. 306*e0680481Safresh1 307*e0680481Safresh1=back 308*e0680481Safresh1 309*e0680481Safresh1Any unknown guesswork name is silently ignored (for potential future 310*e0680481Safresh1compatibility), so be careful about spelling. 311898184e3Ssthen 312898184e3Ssthen=item B<-h>, B<--help> 313898184e3Ssthen 314*e0680481Safresh1[1.00] Print out usage information. 315898184e3Ssthen 316898184e3Ssthen=item B<-l>, B<--lax> 317898184e3Ssthen 318*e0680481Safresh1[1.00] No longer used. B<pod2man> used to check its input for validity as a 319898184e3Ssthenmanual page, but this should now be done by L<podchecker(1)> instead. 320898184e3SsthenAccepted for backward compatibility; this option no longer does anything. 321898184e3Ssthen 322*e0680481Safresh1=item B<--language>=I<language> 323*e0680481Safresh1 324*e0680481Safresh1[5.00] Add commands telling B<groff> that the input file is in the given 325*e0680481Safresh1language. The value of this setting must be a language abbreviation for which 326*e0680481Safresh1B<groff> provides supplemental configuration, such as C<ja> (for Japanese) or 327*e0680481Safresh1C<zh> (for Chinese). 328*e0680481Safresh1 329*e0680481Safresh1This adds: 330*e0680481Safresh1 331*e0680481Safresh1 .mso <language>.tmac 332*e0680481Safresh1 .hla <language> 333*e0680481Safresh1 334*e0680481Safresh1to the start of the file, which configure correct line breaking for the 335*e0680481Safresh1specified language. Without these commands, groff may not know how to add 336*e0680481Safresh1proper line breaks for Chinese and Japanese text if the man page is installed 337*e0680481Safresh1into the normal man page directory, such as F</usr/share/man>. 338*e0680481Safresh1 339*e0680481Safresh1On many systems, this will be done automatically if the man page is installed 340*e0680481Safresh1into a language-specific man page directory, such as F</usr/share/man/zh_CN>. 341*e0680481Safresh1In that case, this option is not required. 342*e0680481Safresh1 343*e0680481Safresh1Unfortunately, the commands added with this option are specific to B<groff> 344*e0680481Safresh1and will not work with other B<troff> and B<nroff> implementations. 345*e0680481Safresh1 3469f11ffb7Safresh1=item B<--lquote>=I<quote> 3479f11ffb7Safresh1 3489f11ffb7Safresh1=item B<--rquote>=I<quote> 3499f11ffb7Safresh1 350*e0680481Safresh1[4.08] Sets the quote marks used to surround CE<lt>> text. B<--lquote> sets 351*e0680481Safresh1the left quote mark and B<--rquote> sets the right quote mark. Either may 352*e0680481Safresh1also be set to the special value C<none>, in which case no quote mark is added 353*e0680481Safresh1on that side of CE<lt>> text (but the font is still changed for troff output). 3549f11ffb7Safresh1 3559f11ffb7Safresh1Also see the B<--quotes> option, which can be used to set both quotes at once. 3569f11ffb7Safresh1If both B<--quotes> and one of the other options is set, B<--lquote> or 3579f11ffb7Safresh1B<--rquote> overrides B<--quotes>. 3589f11ffb7Safresh1 359898184e3Ssthen=item B<-n> I<name>, B<--name>=I<name> 360898184e3Ssthen 361*e0680481Safresh1[4.08] Set the name of the manual page for the C<.TH> macro to I<name>. 362*e0680481Safresh1Without this option, the manual name is set to the uppercased base name of the 363*e0680481Safresh1file being converted unless the manual section is 3, in which case the path is 364*e0680481Safresh1parsed to see if it is a Perl module path. If it is, a path like 365*e0680481Safresh1C<.../lib/Pod/Man.pm> is converted into a name like C<Pod::Man>. This option, 366*e0680481Safresh1if given, overrides any automatic determination of the name. 367898184e3Ssthen 368b8851fccSafresh1Although one does not have to follow this convention, be aware that the 369*e0680481Safresh1convention for UNIX manual pages is for the title to be in all-uppercase, even 370*e0680481Safresh1if the command isn't. (Perl modules traditionally use mixed case for the 371*e0680481Safresh1manual page title, however.) 372b8851fccSafresh1 373*e0680481Safresh1This option is probably not useful when converting multiple POD files at once. 374b8851fccSafresh1 3759f11ffb7Safresh1When converting POD source from standard input, the name will be set to 3769f11ffb7Safresh1C<STDIN> if this option is not provided. Providing this option is strongly 3779f11ffb7Safresh1recommended to set a meaningful manual page name. 378898184e3Ssthen 37991f110e0Safresh1=item B<--nourls> 38091f110e0Safresh1 381*e0680481Safresh1[2.5.0] Normally, LZ<><> formatting codes with a URL but anchor text are 382*e0680481Safresh1formatted to show both the anchor text and the URL. In other words: 38391f110e0Safresh1 38491f110e0Safresh1 L<foo|http://example.com/> 38591f110e0Safresh1 38691f110e0Safresh1is formatted as: 38791f110e0Safresh1 38891f110e0Safresh1 foo <http://example.com/> 38991f110e0Safresh1 39091f110e0Safresh1This flag, if given, suppresses the URL when anchor text is given, so this 39191f110e0Safresh1example would be formatted as just C<foo>. This can produce less 39291f110e0Safresh1cluttered output in cases where the URLs are not particularly important. 39391f110e0Safresh1 394898184e3Ssthen=item B<-o>, B<--official> 395898184e3Ssthen 396*e0680481Safresh1[1.00] Set the default header to indicate that this page is part of the 397*e0680481Safresh1standard Perl release, if B<--center> is not also given. 398898184e3Ssthen 399898184e3Ssthen=item B<-q> I<quotes>, B<--quotes>=I<quotes> 400898184e3Ssthen 401*e0680481Safresh1[4.00] Sets the quote marks used to surround CE<lt>> text to I<quotes>. If 402*e0680481Safresh1I<quotes> is a single character, it is used as both the left and right quote. 403*e0680481Safresh1Otherwise, it is split in half, and the first half of the string is used as 404*e0680481Safresh1the left quote and the second is used as the right quote. 405898184e3Ssthen 406*e0680481Safresh1I<quotes> may also be set to the special value C<none>, in which case no quote 407*e0680481Safresh1marks are added around CE<lt>> text (but the font is still changed for troff 408*e0680481Safresh1output). 409898184e3Ssthen 4109f11ffb7Safresh1Also see the B<--lquote> and B<--rquote> options, which can be used to set the 4119f11ffb7Safresh1left and right quotes independently. If both B<--quotes> and one of the other 4129f11ffb7Safresh1options is set, B<--lquote> or B<--rquote> overrides B<--quotes>. 4139f11ffb7Safresh1 414b8851fccSafresh1=item B<-r> I<version>, B<--release>=I<version> 415898184e3Ssthen 416*e0680481Safresh1[1.00] Set the centered footer for the C<.TH> macro to I<version>. By 417*e0680481Safresh1default, this is set to the version of Perl you run B<pod2man> under. Setting 418*e0680481Safresh1this to the empty string will cause some *roff implementations to use the 419b8851fccSafresh1system default value. 420898184e3Ssthen 421*e0680481Safresh1Note that some system C<an> macro sets assume that the centered footer will be 422*e0680481Safresh1a modification date and will prepend something like C<Last modified: >. If 423*e0680481Safresh1this is the case for your target system, you may want to set B<--release> to 424*e0680481Safresh1the last modified date and B<--date> to the version number. 425b8851fccSafresh1 426b8851fccSafresh1=item B<-s> I<string>, B<--section>=I<string> 427898184e3Ssthen 428*e0680481Safresh1[1.00] Set the section for the C<.TH> macro. The standard section numbering 429*e0680481Safresh1convention is to use 1 for user commands, 2 for system calls, 3 for functions, 430*e0680481Safresh14 for devices, 5 for file formats, 6 for games, 7 for miscellaneous 431*e0680481Safresh1information, and 8 for administrator commands. There is a lot of variation 432*e0680481Safresh1here, however; some systems (like Solaris) use 4 for file formats, 5 for 433*e0680481Safresh1miscellaneous information, and 7 for devices. Still others use 1m instead of 434*e0680481Safresh18, or some mix of both. About the only section numbers that are reliably 435*e0680481Safresh1consistent are 1, 2, and 3. 436898184e3Ssthen 437*e0680481Safresh1By default, section 1 will be used unless the file ends in C<.pm>, in which 438*e0680481Safresh1case section 3 will be selected. 439898184e3Ssthen 440898184e3Ssthen=item B<--stderr> 441898184e3Ssthen 442*e0680481Safresh1[2.1.3] By default, B<pod2man> dies if any errors are detected in the POD 443*e0680481Safresh1input. If B<--stderr> is given and no B<--errors> flag is present, errors are 444*e0680481Safresh1sent to standard error, but B<pod2man> does not abort. This is equivalent to 445*e0680481Safresh1C<--errors=stderr> and is supported for backward compatibility. 446898184e3Ssthen 447898184e3Ssthen=item B<-u>, B<--utf8> 448898184e3Ssthen 449*e0680481Safresh1[2.1.0] This option used to tell B<pod2man> to produce UTF-8 output. Since 450*e0680481Safresh1this is now the default as of version 5.00, it is ignored and does nothing. 451898184e3Ssthen 452898184e3Ssthen=item B<-v>, B<--verbose> 453898184e3Ssthen 454*e0680481Safresh1[1.11] Print out the name of each output file as it is being generated. 455898184e3Ssthen 456898184e3Ssthen=back 457898184e3Ssthen 45891f110e0Safresh1=head1 EXIT STATUS 45991f110e0Safresh1 460*e0680481Safresh1As long as all documents processed result in some output, even if that output 461*e0680481Safresh1includes errata (a C<POD ERRORS> section generated with C<--errors=pod>), 462*e0680481Safresh1B<pod2man> will exit with status 0. If any of the documents being processed 463*e0680481Safresh1do not result in an output document, B<pod2man> will exit with status 1. If 464*e0680481Safresh1there are syntax errors in a POD document being processed and the error 465*e0680481Safresh1handling style is set to the default of C<die>, B<pod2man> will abort 466*e0680481Safresh1immediately with exit status 255. 46791f110e0Safresh1 468898184e3Ssthen=head1 DIAGNOSTICS 469898184e3Ssthen 470898184e3SsthenIf B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for 471898184e3Sstheninformation about what those errors might mean. 472898184e3Ssthen 473898184e3Ssthen=head1 EXAMPLES 474898184e3Ssthen 475898184e3Ssthen pod2man program > program.1 476898184e3Ssthen pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3 477898184e3Ssthen pod2man --section=7 note.pod > note.7 478898184e3Ssthen 479898184e3SsthenIf you would like to print out a lot of man page continuously, you probably 480898184e3Ssthenwant to set the C and D registers to set contiguous page numbering and 481898184e3Sstheneven/odd paging, at least on some versions of man(7). 482898184e3Ssthen 483898184e3Ssthen troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ... 484898184e3Ssthen 485898184e3SsthenTo get index entries on C<STDERR>, turn on the F register, as in: 486898184e3Ssthen 487898184e3Ssthen troff -man -rF1 perl.1 488898184e3Ssthen 489*e0680481Safresh1The indexing merely outputs messages via C<.tm> for each major page, section, 490*e0680481Safresh1subsection, item, and any C<XE<lt>E<gt>> directives. 491898184e3Ssthen 492b46d8ef2Safresh1=head1 AUTHOR 493b46d8ef2Safresh1 494*e0680481Safresh1Russ Allbery <rra@cpan.org>, based on the original B<pod2man> by Larry Wall 495*e0680481Safresh1and Tom Christiansen. 496b46d8ef2Safresh1 497b46d8ef2Safresh1=head1 COPYRIGHT AND LICENSE 498b46d8ef2Safresh1 499*e0680481Safresh1Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery 500b46d8ef2Safresh1<rra@cpan.org> 501b46d8ef2Safresh1 502b46d8ef2Safresh1This program is free software; you may redistribute it and/or modify it 503b46d8ef2Safresh1under the same terms as Perl itself. 504b46d8ef2Safresh1 505898184e3Ssthen=head1 SEE ALSO 506898184e3Ssthen 507898184e3SsthenL<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>, 508898184e3SsthenL<podchecker(1)>, L<perlpodstyle(1)>, L<troff(1)>, L<man(7)> 509898184e3Ssthen 510898184e3SsthenThe man page documenting the an macro set may be L<man(5)> instead of 511898184e3SsthenL<man(7)> on your system. 512898184e3Ssthen 513898184e3SsthenThe current version of this script is always available from its web site at 514b46d8ef2Safresh1L<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 515898184e3SsthenPerl core distribution as of 5.6.0. 516898184e3Ssthen 517898184e3Ssthen=cut 518b8851fccSafresh1SCRIPT_BODY 519898184e3Ssthen 520b8851fccSafresh1# Finish the generation of the script. 521b8851fccSafresh1close($out) or die "Cannot close $file: $!\n"; 522b8851fccSafresh1chmod(0755, $file) or die "Cannot reset permissions for $file: $!\n"; 523b8851fccSafresh1if ($Config{'eunicefix'} ne q{:}) { 524b8851fccSafresh1 exec("$Config{'eunicefix'} $file"); 525b8851fccSafresh1} 526b46d8ef2Safresh1 527b46d8ef2Safresh1# Local Variables: 528b46d8ef2Safresh1# copyright-at-end-flag: t 529b46d8ef2Safresh1# End: 530