xref: /openbsd-src/gnu/usr.bin/perl/cpan/podlators/scripts/pod2man.PL (revision e068048151d29f2562a32185e21a8ba885482260)
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