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