RE: How to load a "loadable object" that has a non-default file extension ?
[perl.git] / pod / pod2man.PL
1 #!/usr/local/bin/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 # $Id: pod2man.PL,v 1.16 2006-01-21 01:53:55 eagle Exp $
40 #
41 # Copyright 1999, 2000, 2001, 2004, 2006 by 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 # Silence -w warnings.
55 use vars qw($running_under_some_shell);
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 backwards 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, 'section|s=s', 'release|r:s', 'center|c=s',
67             'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
68             'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s',
69             'lax|l', 'help|h', 'verbose|v') or exit 1;
70 pod2usage (0) if $options{help};
71
72 # Official sets --center, but don't override things explicitly set.
73 if ($options{official} && !defined $options{center}) {
74     $options{center} = 'Perl Programmers Reference Guide';
75 }
76
77 # Verbose is only our flag, not a Pod::Man flag.
78 my $verbose = $options{verbose};
79 delete $options{verbose};
80
81 # This isn't a valid Pod::Man option and is only accepted for backwards
82 # compatibility.
83 delete $options{lax};
84
85 # Initialize and run the formatter, pulling a pair of input and output off at
86 # a time.
87 my $parser = Pod::Man->new (%options);
88 my @files;
89 do {
90     @files = splice (@ARGV, 0, 2);
91     print "  $files[1]\n" if $verbose;
92     $parser->parse_from_file (@files);
93 } while (@ARGV);
94
95 __END__
96
97 =head1 NAME
98
99 pod2man - Convert POD data to formatted *roff input
100
101 =head1 SYNOPSIS
102
103 pod2man [B<--section>=I<manext>] [B<--release>[=I<version>]]
104 [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>]
105 [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
106 [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
107 [B<--lax>] [B<--quotes>=I<quotes>] [B<--verbose>]
108 [I<input> [I<output>] ...]
109
110 pod2man B<--help>
111
112 =head1 DESCRIPTION
113
114 B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
115 from POD source.  The resulting *roff code is suitable for display on a
116 terminal using nroff(1), normally via man(1), or printing using troff(1).
117
118 I<input> is the file to read for POD source (the POD can be embedded in
119 code).  If I<input> isn't given, it defaults to STDIN.  I<output>, if given,
120 is the file to which to write the formatted output.  If I<output> isn't
121 given, the formatted output is written to STDOUT.  Several POD files can be
122 processed in the same B<pod2man> invocation (saving module load and compile
123 times) by providing multiple pairs of I<input> and I<output> files on the
124 command line.
125
126 B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be
127 used to set the headers and footers to use; if not given, Pod::Man will
128 assume various defaults.  See below or L<Pod::Man> for details.
129
130 B<pod2man> assumes that your *roff formatters have a fixed-width font named
131 CW.  If yours is called something else (like CR), use B<--fixed> to specify
132 it.  This generally only matters for troff output for printing.  Similarly,
133 you can set the fonts used for bold, italic, and bold italic fixed-width
134 output.
135
136 Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
137 takes care of formatting func(), func(n), and simple variable references
138 like $foo or @bar so you don't have to use code escapes for them; complex
139 expressions like C<$fred{'stuff'}> will still need to be escaped, though.
140 It also translates dashes that aren't used as hyphens into en dashes, makes
141 long dashes--like this--into proper em dashes, fixes "paired quotes," and
142 takes care of several other troff-specific tweaks.  See L<Pod::Man> for
143 complete information.
144
145 =head1 OPTIONS
146
147 =over 4
148
149 =item B<-c> I<string>, B<--center>=I<string>
150
151 Sets the centered page header to I<string>.  The default is "User
152 Contributed Perl Documentation", but also see B<--official> below.
153
154 =item B<-d> I<string>, B<--date>=I<string>
155
156 Set the left-hand footer string to this value.  By default, the modification
157 date of the input file will be used, or the current date if input comes from
158 STDIN.
159
160 =item B<--fixed>=I<font>
161
162 The fixed-width font to use for vertabim text and code.  Defaults to CW.
163 Some systems may want CR instead.  Only matters for troff(1) output.
164
165 =item B<--fixedbold>=I<font>
166
167 Bold version of the fixed-width font.  Defaults to CB.  Only matters for
168 troff(1) output.
169
170 =item B<--fixeditalic>=I<font>
171
172 Italic version of the fixed-width font (actually, something of a misnomer,
173 since most fixed-width fonts only have an oblique version, not an italic
174 version).  Defaults to CI.  Only matters for troff(1) output.
175
176 =item B<--fixedbolditalic>=I<font>
177
178 Bold italic (probably actually oblique) version of the fixed-width font.
179 Pod::Man doesn't assume you have this, and defaults to CB.  Some systems
180 (such as Solaris) have this font available as CX.  Only matters for troff(1)
181 output.
182
183 =item B<-h>, B<--help>
184
185 Print out usage information.
186
187 =item B<-l>, B<--lax>
188
189 No longer used.  B<pod2man> used to check its input for validity as a manual
190 page, but this should now be done by L<podchecker(1)> instead.  Accepted for
191 backwards compatibility; this option no longer does anything.
192
193 =item B<-n> I<name>, B<--name>=I<name>
194
195 Set the name of the manual page to I<name>.  Without this option, the manual
196 name is set to the uppercased base name of the file being converted unless
197 the manual section is 3, in which case the path is parsed to see if it is a
198 Perl module path.  If it is, a path like C<.../lib/Pod/Man.pm> is converted
199 into a name like C<Pod::Man>.  This option, if given, overrides any
200 automatic determination of the name.
201
202 Note that this option is probably not useful when converting multiple POD
203 files at once.  The convention for Unix man pages for commands is for the
204 man page title to be in all-uppercase even if the command isn't.
205
206 =item B<-o>, B<--official>
207
208 Set the default header to indicate that this page is part of the standard
209 Perl release, if B<--center> is not also given.
210
211 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
212
213 Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
214 I<quotes> is a single character, it is used as both the left and right
215 quote; if I<quotes> is two characters, the first character is used as the
216 left quote and the second as the right quoted; and if I<quotes> is four
217 characters, the first two are used as the left quote and the second two as
218 the right quote.
219
220 I<quotes> may also be set to the special value C<none>, in which case no
221 quote marks are added around CE<lt>> text (but the font is still changed for
222 troff output).
223
224 =item B<-r>, B<--release>
225
226 Set the centered footer.  By default, this is the version of Perl you run
227 B<pod2man> under.  Note that some system an macro sets assume that the
228 centered footer will be a modification date and will prepend something like
229 "Last modified: "; if this is the case, you may want to set B<--release> to
230 the last modified date and B<--date> to the version number.
231
232 =item B<-s>, B<--section>
233
234 Set the section for the C<.TH> macro.  The standard section numbering
235 convention is to use 1 for user commands, 2 for system calls, 3 for
236 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
237 miscellaneous information, and 8 for administrator commands.  There is a lot
238 of variation here, however; some systems (like Solaris) use 4 for file
239 formats, 5 for miscellaneous information, and 7 for devices.  Still others
240 use 1m instead of 8, or some mix of both.  About the only section numbers
241 that are reliably consistent are 1, 2, and 3.
242
243 By default, section 1 will be used unless the file ends in .pm in which case
244 section 3 will be selected.
245
246 =item B<-v>, B<--verbose>
247
248 Print out the name of each output file as it is being generated.
249
250 =back
251
252 =head1 DIAGNOSTICS
253
254 If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
255 information about what those errors might mean.
256
257 =head1 EXAMPLES
258
259     pod2man program > program.1
260     pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
261     pod2man --section=7 note.pod > note.7
262
263 If you would like to print out a lot of man page continuously, you probably
264 want to set the C and D registers to set contiguous page numbering and
265 even/odd paging, at least on some versions of man(7).
266
267     troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
268
269 To get index entries on stderr, turn on the F register, as in:
270
271     troff -man -rF1 perl.1
272
273 The indexing merely outputs messages via C<.tm> for each major page,
274 section, subsection, item, and any C<XE<lt>E<gt>> directives.  See
275 L<Pod::Man> for more details.
276
277 =head1 BUGS
278
279 Lots of this documentation is duplicated from L<Pod::Man>.
280
281 =head1 NOTES
282
283 For those not sure of the proper layout of a man page, here are some notes
284 on writing a proper man page.
285
286 The name of the program being documented is conventionally written in bold
287 (using BE<lt>E<gt>) wherever it occurs, as are all program options.
288 Arguments should be written in italics (IE<lt>E<gt>).  Functions are
289 traditionally written in italics; if you write a function as function(),
290 Pod::Man will take care of this for you.  Literal code or commands should
291 be in CE<lt>E<gt>.  References to other man pages should be in the form
292 C<manpage(section)>, and Pod::Man will automatically format those
293 appropriately.  As an exception, it's traditional not to use this form when
294 referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead.
295
296 References to other programs or functions are normally in the form of man
297 page references so that cross-referencing tools can provide the user with
298 links and the like.  It's possible to overdo this, though, so be careful not
299 to clutter your documentation with too much markup.
300
301 The major headers should be set out using a C<=head1> directive, and are
302 historically written in the rather startling ALL UPPER CASE format, although
303 this is not mandatory.  Minor headers may be included using C<=head2>, and
304 are typically in mixed case.
305
306 The standard sections of a manual page are:
307
308 =over 4
309
310 =item NAME
311
312 Mandatory section; should be a comma-separated list of programs or functions
313 documented by this podpage, such as:
314
315     foo, bar - programs to do something
316
317 Manual page indexers are often extremely picky about the format of this
318 section, so don't put anything in it except this line.  A single dash, and
319 only a single dash, should separate the list of programs or functions from
320 the description.  Functions should not be qualified with C<()> or the like.
321 The description should ideally fit on a single line, even if a man program
322 replaces the dash with a few tabs.
323
324 =item SYNOPSIS
325
326 A short usage summary for programs and functions.  This section is mandatory
327 for section 3 pages.
328
329 =item DESCRIPTION
330
331 Extended description and discussion of the program or functions, or the body
332 of the documentation for man pages that document something else.  If
333 particularly long, it's a good idea to break this up into subsections
334 C<=head2> directives like:
335
336     =head2 Normal Usage
337
338     =head2 Advanced Features
339
340     =head2 Writing Configuration Files
341
342 or whatever is appropriate for your documentation.
343
344 =item OPTIONS
345
346 Detailed description of each of the command-line options taken by the
347 program.  This should be separate from the description for the use of things
348 like L<Pod::Usage|Pod::Usage>.  This is normally presented as a list, with
349 each option as a separate C<=item>.  The specific option string should be
350 enclosed in BE<lt>E<gt>.  Any values that the option takes should be
351 enclosed in IE<lt>E<gt>.  For example, the section for the option
352 B<--section>=I<manext> would be introduced with:
353
354     =item B<--section>=I<manext>
355
356 Synonymous options (like both the short and long forms) are separated by a
357 comma and a space on the same C<=item> line, or optionally listed as their
358 own item with a reference to the canonical name.  For example, since
359 B<--section> can also be written as B<-s>, the above would be:
360
361     =item B<-s> I<manext>, B<--section>=I<manext>
362
363 (Writing the short option first is arguably easier to read, since the long
364 option is long enough to draw the eye to it anyway and the short option can
365 otherwise get lost in visual noise.)
366
367 =item RETURN VALUE
368
369 What the program or function returns, if successful.  This section can be
370 omitted for programs whose precise exit codes aren't important, provided
371 they return 0 on success as is standard.  It should always be present for
372 functions.
373
374 =item ERRORS
375
376 Exceptions, error return codes, exit statuses, and errno settings.
377 Typically used for function documentation; program documentation uses
378 DIAGNOSTICS instead.  The general rule of thumb is that errors printed to
379 STDOUT or STDERR and intended for the end user are documented in DIAGNOSTICS
380 while errors passed internal to the calling program and intended for other
381 programmers are documented in ERRORS.  When documenting a function that sets
382 errno, a full list of the possible errno values should be given here.
383
384 =item DIAGNOSTICS
385
386 All possible messages the program can print out--and what they mean.  You
387 may wish to follow the same documentation style as the Perl documentation;
388 see perldiag(1) for more details (and look at the POD source as well).
389
390 If applicable, please include details on what the user should do to correct
391 the error; documenting an error as indicating "the input buffer is too
392 small" without telling the user how to increase the size of the input buffer
393 (or at least telling them that it isn't possible) aren't very useful.
394
395 =item EXAMPLES
396
397 Give some example uses of the program or function.  Don't skimp; users often
398 find this the most useful part of the documentation.  The examples are
399 generally given as verbatim paragraphs.
400
401 Don't just present an example without explaining what it does.  Adding a
402 short paragraph saying what the example will do can increase the value of
403 the example immensely.
404
405 =item ENVIRONMENT
406
407 Environment variables that the program cares about, normally presented as a
408 list using C<=over>, C<=item>, and C<=back>.  For example:
409
410     =over 6
411
412     =item HOME
413
414     Used to determine the user's home directory.  F<.foorc> in this
415     directory is read for configuration details, if it exists.
416
417     =back
418
419 Since environment variables are normally in all uppercase, no additional
420 special formatting is generally needed; they're glaring enough as it is.
421
422 =item FILES
423
424 All files used by the program or function, normally presented as a list, and
425 what it uses them for.  File names should be enclosed in FE<lt>E<gt>.  It's
426 particularly important to document files that will be potentially modified.
427
428 =item CAVEATS
429
430 Things to take special care with, sometimes called WARNINGS.
431
432 =item BUGS
433
434 Things that are broken or just don't work quite right.
435
436 =item RESTRICTIONS
437
438 Bugs you don't plan to fix.  :-)
439
440 =item NOTES
441
442 Miscellaneous commentary.
443
444 =item AUTHOR
445
446 Who wrote it (use AUTHORS for multiple people).  Including your current
447 e-mail address (or some e-mail address to which bug reports should be sent)
448 so that users have a way of contacting you is a good idea.  Remember that
449 program documentation tends to roam the wild for far longer than you expect
450 and pick an e-mail address that's likely to last if possible.
451
452 =item HISTORY
453
454 Programs derived from other sources sometimes have this, or you might keep
455 a modification log here.  If the log gets overly long or detailed,
456 consider maintaining it in a separate file, though.
457
458 =item COPYRIGHT AND LICENSE
459
460 For copyright
461
462     Copyright YEAR(s) by YOUR NAME(s)
463
464 (No, (C) is not needed.  No, "all rights reserved" is not needed.)
465
466 For licensing the easiest way is to use the same licensing as Perl itself:
467
468     This library is free software; you may redistribute it and/or modify
469     it under the same terms as Perl itself.
470
471 This makes it easy for people to use your module with Perl.  Note that
472 this licensing is neither an endorsement or a requirement, you are of
473 course free to choose any licensing.
474
475 =item SEE ALSO
476
477 Other man pages to check out, like man(1), man(7), makewhatis(8), or
478 catman(8).  Normally a simple list of man pages separated by commas, or a
479 paragraph giving the name of a reference work.  Man page references, if they
480 use the standard C<name(section)> form, don't have to be enclosed in
481 LE<lt>E<gt> (although it's recommended), but other things in this section
482 probably should be when appropriate.
483
484 If the package has a mailing list, include a URL or subscription
485 instructions here.
486
487 If the package has a web site, include a URL here.
488
489 =back
490
491 In addition, some systems use CONFORMING TO to note conformance to relevant
492 standards and MT-LEVEL to note safeness for use in threaded programs or
493 signal handlers.  These headings are primarily useful when documenting parts
494 of a C library.  Documentation of object-oriented libraries or modules may
495 use CONSTRUCTORS and METHODS sections for detailed documentation of the
496 parts of the library and save the DESCRIPTION section for an overview; other
497 large modules may use FUNCTIONS for similar reasons.  Some people use
498 OVERVIEW to summarize the description if it's quite long.
499
500 Section ordering varies, although NAME should I<always> be the first section
501 (you'll break some man page systems otherwise), and NAME, SYNOPSIS,
502 DESCRIPTION, and OPTIONS generally always occur first and in that order if
503 present.  In general, SEE ALSO, AUTHOR, and similar material should be left
504 for last.  Some systems also move WARNINGS and NOTES to last.  The order
505 given above should be reasonable for most purposes.
506
507 Finally, as a general note, try not to use an excessive amount of markup.
508 As documented here and in L<Pod::Man>, you can safely leave Perl variables,
509 function names, man page references, and the like unadorned by markup and
510 the POD translators will figure it out for you.  This makes it much easier
511 to later edit the documentation.  Note that many existing translators
512 (including this one currently) will do the wrong thing with e-mail addresses
513 when wrapped in LE<lt>E<gt>, so don't do that.
514
515 For additional information that may be more accurate for your specific
516 system, see either L<man(5)> or L<man(7)> depending on your system manual
517 section numbering conventions.
518
519 =head1 SEE ALSO
520
521 L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<podchecker(1)>,
522 L<troff(1)>, L<man(7)>
523
524 The man page documenting the an macro set may be L<man(5)> instead of
525 L<man(7)> on your system.
526
527 The current version of this script is always available from its web site at
528 L<http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
529 Perl core distribution as of 5.6.0.
530
531 =head1 AUTHOR
532
533 Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
534 B<pod2man> by Larry Wall and Tom Christiansen.  Large portions of this
535 documentation, particularly the sections on the anatomy of a proper man
536 page, are taken from the B<pod2man> documentation by Tom.
537
538 =head1 COPYRIGHT AND LICENSE
539
540 Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
541
542 This program is free software; you may redistribute it and/or modify it
543 under the same terms as Perl itself.
544
545 =cut
546 !NO!SUBS!
547 #'# (cperl-mode)
548
549 close OUT or die "Can't close $file: $!";
550 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
551 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
552 chdir $origdir;