Update podlators to version 4.03
[perl.git] / cpan / podlators / bin / pod2man
1 #!perl
2
3 # pod2man -- Convert POD data to formatted *roff input.
4 #
5 # Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015
6 #     Russ Allbery <rra@cpan.org>
7 #
8 # This program is free software; you may redistribute it and/or modify it
9 # under the same terms as Perl itself.
10
11 use 5.006;
12 use strict;
13 use warnings;
14
15 use Getopt::Long qw(GetOptions);
16 use Pod::Man ();
17 use Pod::Usage qw(pod2usage);
18
19 use strict;
20
21 # Clean up $0 for error reporting.
22 $0 =~ s%.*/%%;
23
24 # Insert -- into @ARGV before any single dash argument to hide it from
25 # Getopt::Long; we want to interpret it as meaning stdin.
26 my $stdin;
27 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
28
29 # Parse our options, trying to retain backward compatibility with pod2man but
30 # allowing short forms as well.  --lax is currently ignored.
31 my %options;
32 Getopt::Long::config ('bundling_override');
33 GetOptions (\%options, 'center|c=s', 'date|d=s', 'errors=s', 'fixed=s',
34             'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 'help|h',
35             'lax|l', 'name|n=s', 'nourls', 'official|o', 'quotes|q=s',
36             'release|r=s', 'section|s=s', 'stderr', 'verbose|v', 'utf8|u')
37     or exit 1;
38 pod2usage (0) if $options{help};
39
40 # Official sets --center, but don't override things explicitly set.
41 if ($options{official} && !defined $options{center}) {
42     $options{center} = 'Perl Programmers Reference Guide';
43 }
44
45 # Verbose is only our flag, not a Pod::Man flag.
46 my $verbose = $options{verbose};
47 delete $options{verbose};
48
49 # This isn't a valid Pod::Man option and is only accepted for backward
50 # compatibility.
51 delete $options{lax};
52
53 # If neither stderr nor errors is set, default to errors = die.
54 if (!defined $options{stderr} && !defined $options{errors}) {
55     $options{errors} = 'die';
56 }
57
58 # Initialize and run the formatter, pulling a pair of input and output off at
59 # a time.  For each file, we check whether the document was completely empty
60 # and, if so, will remove the created file and exit with a non-zero exit
61 # status.
62 my $parser = Pod::Man->new (%options);
63 my $status = 0;
64 my @files;
65 do {
66     @files = splice (@ARGV, 0, 2);
67     print "  $files[1]\n" if $verbose;
68     $parser->parse_from_file (@files);
69     if ($parser->{CONTENTLESS}) {
70         $status = 1;
71         warn "$0: unable to format $files[0]\n";
72         if (defined ($files[1]) and $files[1] ne '-') {
73             unlink $files[1] unless (-s $files[1]);
74         }
75     }
76 } while (@ARGV);
77 exit $status;
78
79 __END__
80
81 =for stopwords
82 en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
83 URL troff troff-specific formatters uppercased Christiansen --nourls
84
85 =head1 NAME
86
87 pod2man - Convert POD data to formatted *roff input
88
89 =head1 SYNOPSIS
90
91 pod2man [B<--center>=I<string>] [B<--date>=I<string>] [B<--errors>=I<style>]
92     [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
93     [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--nourls>]
94     [B<--official>] [B<--quotes>=I<quotes>] [B<--release>=I<version>]
95     [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
96     [I<input> [I<output>] ...]
97
98 pod2man B<--help>
99
100 =head1 DESCRIPTION
101
102 B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
103 from POD source.  The resulting *roff code is suitable for display on a
104 terminal using nroff(1), normally via man(1), or printing using troff(1).
105
106 I<input> is the file to read for POD source (the POD can be embedded in
107 code).  If I<input> isn't given, it defaults to C<STDIN>.  I<output>, if
108 given, is the file to which to write the formatted output.  If I<output>
109 isn't given, the formatted output is written to C<STDOUT>.  Several POD
110 files can be processed in the same B<pod2man> invocation (saving module
111 load and compile times) by providing multiple pairs of I<input> and
112 I<output> files on the command line.
113
114 B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can
115 be used to set the headers and footers to use; if not given, Pod::Man will
116 assume various defaults.  See below or L<Pod::Man> for details.
117
118 B<pod2man> assumes that your *roff formatters have a fixed-width font
119 named C<CW>.  If yours is called something else (like C<CR>), use
120 B<--fixed> to specify it.  This generally only matters for troff output
121 for printing.  Similarly, you can set the fonts used for bold, italic, and
122 bold italic fixed-width output.
123
124 Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
125 takes care of formatting func(), func(n), and simple variable references
126 like $foo or @bar so you don't have to use code escapes for them; complex
127 expressions like C<$fred{'stuff'}> will still need to be escaped, though.
128 It also translates dashes that aren't used as hyphens into en dashes, makes
129 long dashes--like this--into proper em dashes, fixes "paired quotes," and
130 takes care of several other troff-specific tweaks.  See L<Pod::Man> for
131 complete information.
132
133 =head1 OPTIONS
134
135 =over 4
136
137 =item B<-c> I<string>, B<--center>=I<string>
138
139 Sets the centered page header for the C<.TH> macro to I<string>.  The
140 default is "User Contributed Perl Documentation", but also see
141 B<--official> below.
142
143 =item B<-d> I<string>, B<--date>=I<string>
144
145 Set the left-hand footer string for the C<.TH> macro to I<string>.  By
146 default, the modification date of the input file will be used, or the
147 current date if input comes from C<STDIN>, and will be based on UTC (so
148 that the output will be reproducible regardless of local time zone).
149
150 =item B<--errors>=I<style>
151
152 Set the error handling style.  C<die> says to throw an exception on any
153 POD formatting error.  C<stderr> says to report errors on standard error,
154 but not to throw an exception.  C<pod> says to include a POD ERRORS
155 section in the resulting documentation summarizing the errors.  C<none>
156 ignores POD errors entirely, as much as possible.
157
158 The default is C<die>.
159
160 =item B<--fixed>=I<font>
161
162 The fixed-width font to use for verbatim text and code.  Defaults to
163 C<CW>.  Some systems may want C<CR> instead.  Only matters for troff(1)
164 output.
165
166 =item B<--fixedbold>=I<font>
167
168 Bold version of the fixed-width font.  Defaults to C<CB>.  Only matters
169 for troff(1) output.
170
171 =item B<--fixeditalic>=I<font>
172
173 Italic version of the fixed-width font (actually, something of a misnomer,
174 since most fixed-width fonts only have an oblique version, not an italic
175 version).  Defaults to C<CI>.  Only matters for troff(1) output.
176
177 =item B<--fixedbolditalic>=I<font>
178
179 Bold italic (probably actually oblique) version of the fixed-width font.
180 Pod::Man doesn't assume you have this, and defaults to C<CB>.  Some
181 systems (such as Solaris) have this font available as C<CX>.  Only matters
182 for troff(1) output.
183
184 =item B<-h>, B<--help>
185
186 Print out usage information.
187
188 =item B<-l>, B<--lax>
189
190 No longer used.  B<pod2man> used to check its input for validity as a
191 manual page, but this should now be done by L<podchecker(1)> instead.
192 Accepted for backward compatibility; this option no longer does anything.
193
194 =item B<-n> I<name>, B<--name>=I<name>
195
196 Set the name of the manual page for the C<.TH> macro to I<name>.  Without
197 this option, the manual name is set to the uppercased base name of the
198 file being converted unless the manual section is 3, in which case the
199 path is parsed to see if it is a Perl module path.  If it is, a path like
200 C<.../lib/Pod/Man.pm> is converted into a name like C<Pod::Man>.  This
201 option, if given, overrides any automatic determination of the name.
202
203 Although one does not have to follow this convention, be aware that the
204 convention for UNIX man pages for commands is for the man page title to be
205 in all-uppercase, even if the command isn't.
206
207 This option is probably not useful when converting multiple POD files at
208 once.
209
210 When converting POD source from standard input, this option is required,
211 since there's otherwise no way to know what to use as the name of the
212 manual page.
213
214 =item B<--nourls>
215
216 Normally, LZ<><> formatting codes with a URL but anchor text are formatted
217 to show both the anchor text and the URL.  In other words:
218
219     L<foo|http://example.com/>
220
221 is formatted as:
222
223     foo <http://example.com/>
224
225 This flag, if given, suppresses the URL when anchor text is given, so this
226 example would be formatted as just C<foo>.  This can produce less
227 cluttered output in cases where the URLs are not particularly important.
228
229 =item B<-o>, B<--official>
230
231 Set the default header to indicate that this page is part of the standard
232 Perl release, if B<--center> is not also given.
233
234 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
235
236 Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
237 I<quotes> is a single character, it is used as both the left and right
238 quote.  Otherwise, it is split in half, and the first half of the string
239 is used as the left quote and the second is used as the right quote.
240
241 I<quotes> may also be set to the special value C<none>, in which case no
242 quote marks are added around CE<lt>> text (but the font is still changed for
243 troff output).
244
245 =item B<-r> I<version>, B<--release>=I<version>
246
247 Set the centered footer for the C<.TH> macro to I<version>.  By default,
248 this is set to the version of Perl you run B<pod2man> under.  Setting this
249 to the empty string will cause some *roff implementations to use the
250 system default value.
251
252 Note that some system C<an> macro sets assume that the centered footer
253 will be a modification date and will prepend something like "Last
254 modified: ".  If this is the case for your target system, you may want to
255 set B<--release> to the last modified date and B<--date> to the version
256 number.
257
258 =item B<-s> I<string>, B<--section>=I<string>
259
260 Set the section for the C<.TH> macro.  The standard section numbering
261 convention is to use 1 for user commands, 2 for system calls, 3 for
262 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
263 miscellaneous information, and 8 for administrator commands.  There is a lot
264 of variation here, however; some systems (like Solaris) use 4 for file
265 formats, 5 for miscellaneous information, and 7 for devices.  Still others
266 use 1m instead of 8, or some mix of both.  About the only section numbers
267 that are reliably consistent are 1, 2, and 3.
268
269 By default, section 1 will be used unless the file ends in C<.pm>, in
270 which case section 3 will be selected.
271
272 =item B<--stderr>
273
274 By default, B<pod2man> dies if any errors are detected in the POD input.
275 If B<--stderr> is given and no B<--errors> flag is present, errors are
276 sent to standard error, but B<pod2man> does not abort.  This is equivalent
277 to C<--errors=stderr> and is supported for backward compatibility.
278
279 =item B<-u>, B<--utf8>
280
281 By default, B<pod2man> produces the most conservative possible *roff
282 output to try to ensure that it will work with as many different *roff
283 implementations as possible.  Many *roff implementations cannot handle
284 non-ASCII characters, so this means all non-ASCII characters are converted
285 either to a *roff escape sequence that tries to create a properly accented
286 character (at least for troff output) or to C<X>.
287
288 This option says to instead output literal UTF-8 characters.  If your
289 *roff implementation can handle it, this is the best output format to use
290 and avoids corruption of documents containing non-ASCII characters.
291 However, be warned that *roff source with literal UTF-8 characters is not
292 supported by many implementations and may even result in segfaults and
293 other bad behavior.
294
295 Be aware that, when using this option, the input encoding of your POD
296 source should be properly declared unless it's US-ASCII.  Pod::Simple will
297 attempt to guess the encoding and may be successful if it's Latin-1 or
298 UTF-8, but it will warn, which by default results in a B<pod2man> failure.
299 Use the C<=encoding> command to declare the encoding.  See L<perlpod(1)>
300 for more information.
301
302 =item B<-v>, B<--verbose>
303
304 Print out the name of each output file as it is being generated.
305
306 =back
307
308 =head1 EXIT STATUS
309
310 As long as all documents processed result in some output, even if that
311 output includes errata (a C<POD ERRORS> section generated with
312 C<--errors=pod>), B<pod2man> will exit with status 0.  If any of the
313 documents being processed do not result in an output document, B<pod2man>
314 will exit with status 1.  If there are syntax errors in a POD document
315 being processed and the error handling style is set to the default of
316 C<die>, B<pod2man> will abort immediately with exit status 255.
317
318 =head1 DIAGNOSTICS
319
320 If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
321 information about what those errors might mean.
322
323 =head1 EXAMPLES
324
325     pod2man program > program.1
326     pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
327     pod2man --section=7 note.pod > note.7
328
329 If you would like to print out a lot of man page continuously, you probably
330 want to set the C and D registers to set contiguous page numbering and
331 even/odd paging, at least on some versions of man(7).
332
333     troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
334
335 To get index entries on C<STDERR>, turn on the F register, as in:
336
337     troff -man -rF1 perl.1
338
339 The indexing merely outputs messages via C<.tm> for each major page,
340 section, subsection, item, and any C<XE<lt>E<gt>> directives.  See
341 L<Pod::Man> for more details.
342
343 =head1 BUGS
344
345 Lots of this documentation is duplicated from L<Pod::Man>.
346
347 =head1 SEE ALSO
348
349 L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,
350 L<podchecker(1)>, L<perlpodstyle(1)>, L<troff(1)>, L<man(7)>
351
352 The man page documenting the an macro set may be L<man(5)> instead of
353 L<man(7)> on your system.
354
355 The current version of this script is always available from its web site at
356 L<http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
357 Perl core distribution as of 5.6.0.
358
359 =head1 AUTHOR
360
361 Russ Allbery <rra@cpan.org>, based I<very> heavily on the original
362 B<pod2man> by Larry Wall and Tom Christiansen.
363
364 =head1 COPYRIGHT AND LICENSE
365
366 Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014,
367 2015 Russ Allbery <rra@cpan.org>.
368
369 This program is free software; you may redistribute it and/or modify it
370 under the same terms as Perl itself.
371
372 =cut