4 use File::Basename qw(&basename &dirname);
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
12 # to ensure Configure will look for $Config{startperl}.
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.
18 $file = basename($0, '.PL');
19 $file .= '.com' if $^O eq 'VMS';
21 open OUT,">$file" or die "Can't create $file: $!";
23 print "Extracting $file (with variable substitutions)\n";
25 # In this section, perl variables will be expanded during extraction.
26 # You can use $Config{...} to use Configure variables.
28 print OUT <<"!GROK!THIS!";
30 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
31 if \$running_under_some_shell;
34 # In the following, perl variables are not expanded during extraction.
36 print OUT <<'!NO!SUBS!';
38 # pod2man -- Convert POD data to formatted *roff input.
39 # $Id: pod2man.PL,v 1.3 2000/09/03 09:20:52 eagle Exp $
41 # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
43 # This program is free software; you can redistribute it and/or modify it
44 # under the same terms as Perl itself.
48 use Getopt::Long qw(GetOptions);
50 use Pod::Usage qw(pod2usage);
54 # Insert -- into @ARGV before any single dash argument to hide it from
55 # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser
58 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
60 # Parse our options, trying to retain backwards compatibility with pod2man
61 # but allowing short forms as well. --lax is currently ignored.
63 Getopt::Long::config ('bundling_override');
64 GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s',
65 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
66 'fixedbolditalic=s', 'official|o', 'quotes|q=s', 'lax|l',
68 pod2usage (0) if $options{help};
70 # Official sets --center, but don't override things explicitly set.
71 if ($options{official} && !defined $options{center}) {
72 $options{center} = 'Perl Programmers Reference Guide';
75 # Initialize and run the formatter.
76 my $parser = Pod::Man->new (%options);
77 $parser->parse_from_file (@ARGV);
83 pod2man - Convert POD data to formatted *roff input
87 pod2man [B<--section>=I<manext>] [B<--release>=I<version>]
88 [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>]
89 [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
90 [B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>]
91 [B<--quotes>=I<quotes>] [I<input> [I<output>]]
97 B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
98 from POD source. The resulting *roff code is suitable for display on a
99 terminal using nroff(1), normally via man(1), or printing using troff(1).
101 I<input> is the file to read for POD source (the POD can be embedded in
102 code). If I<input> isn't given, it defaults to STDIN. I<output>, if given,
103 is the file to which to write the formatted output. If I<output> isn't
104 given, the formatted output is written to STDOUT.
106 B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be
107 used to set the headers and footers to use; if not given, Pod::Man will
108 assume various defaults. See below or L<Pod::Man> for details.
110 B<pod2man> assumes that your *roff formatters have a fixed-width font named
111 CW. If yours is called something else (like CR), use B<--fixed> to specify
112 it. This generally only matters for troff output for printing. Similarly,
113 you can set the fonts used for bold, italic, and bold italic fixed-width
116 Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
117 takes care of formatting func(), func(n), and simple variable references
118 like $foo or @bar so you don't have to use code escapes for them; complex
119 expressions like C<$fred{'stuff'}> will still need to be escaped, though.
120 It also translates dashes that aren't used as hyphens into en dashes, makes
121 long dashes--like this--into proper em dashes, fixes "paired quotes," and
122 takes care of several other troff-specific tweaks. See L<Pod::Man> for
123 complete information.
129 =item B<-c> I<string>, B<--center>=I<string>
131 Sets the centered page header to I<string>. The default is "User
132 Contributed Perl Documentation", but also see B<--official> below.
134 =item B<-d> I<string>, B<--date>=I<string>
136 Set the left-hand footer string to this value. By default, the modification
137 date of the input file will be used, or the current date if input comes from
140 =item B<--fixed>=I<font>
142 The fixed-width font to use for vertabim text and code. Defaults to CW.
143 Some systems may want CR instead. Only matters for troff(1) output.
145 =item B<--fixedbold>=I<font>
147 Bold version of the fixed-width font. Defaults to CB. Only matters for
150 =item B<--fixeditalic>=I<font>
152 Italic version of the fixed-width font (actually, something of a misnomer,
153 since most fixed-width fonts only have an oblique version, not an italic
154 version). Defaults to CI. Only matters for troff(1) output.
156 =item B<--fixedbolditalic>=I<font>
158 Bold italic (probably actually oblique) version of the fixed-width font.
159 Pod::Man doesn't assume you have this, and defaults to CB. Some systems
160 (such as Solaris) have this font available as CX. Only matters for troff(1)
163 =item B<-h>, B<--help>
165 Print out usage information.
167 =item B<-l>, B<--lax>
169 Don't complain when required sections are missing. Not currently used, as
170 POD checking functionality is not yet implemented in Pod::Man.
172 =item B<-o>, B<--official>
174 Set the default header to indicate that this page is part of the standard
175 Perl release, if B<--center> is not also given.
177 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
179 Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
180 I<quotes> is a single character, it is used as both the left and right
181 quote; if I<quotes> is two characters, the first character is used as the
182 left quote and the second as the right quoted; and if I<quotes> is four
183 characters, the first two are used as the left quote and the second two as
186 I<quotes> may also be set to the special value C<none>, in which case no
187 quote marks are added around CE<lt>> text (but the font is still changed for
190 =item B<-r>, B<--release>
192 Set the centered footer. By default, this is the version of Perl you run
193 B<pod2man> under. Note that some system an macro sets assume that the
194 centered footer will be a modification date and will prepend something like
195 "Last modified: "; if this is the case, you may want to set B<--release> to
196 the last modified date and B<--date> to the version number.
198 =item B<-s>, B<--section>
200 Set the section for the C<.TH> macro. The standard section numbering
201 convention is to use 1 for user commands, 2 for system calls, 3 for
202 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
203 miscellaneous information, and 8 for administrator commands. There is a lot
204 of variation here, however; some systems (like Solaris) use 4 for file
205 formats, 5 for miscellaneous information, and 7 for devices. Still others
206 use 1m instead of 8, or some mix of both. About the only section numbers
207 that are reliably consistent are 1, 2, and 3.
209 By default, section 1 will be used unless the file ends in .pm in which case
210 section 3 will be selected.
216 If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Parser> for
217 information about what those errors might mean.
221 pod2man program > program.1
222 pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
223 pod2man --section=7 note.pod > note.7
225 If you would like to print out a lot of man page continuously, you probably
226 want to set the C and D registers to set contiguous page numbering and
227 even/odd paging, at least on some versions of man(7).
229 troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
231 To get index entries on stderr, turn on the F register, as in:
233 troff -man -rF1 perl.1
235 The indexing merely outputs messages via C<.tm> for each major page,
236 section, subsection, item, and any C<XE<lt>E<gt>> directives. See
237 L<Pod::Man> for more details.
241 Lots of this documentation is duplicated from L<Pod::Man>.
243 POD checking and the corresponding B<--lax> option don't work yet.
247 For those not sure of the proper layout of a man page, here are some notes
248 on writing a proper man page.
250 The name of the program being documented is conventionally written in bold
251 (using BE<lt>E<gt>) wherever it occurs, as are all program options.
252 Arguments should be written in italics (IE<lt>E<gt>). Functions are
253 traditionally written in italics; if you write a function as function(),
254 Pod::Man will take care of this for you. Literal code or commands should
255 be in CE<lt>E<gt>. References to other man pages should be in the form
256 C<manpage(section)>, and Pod::Man will automatically format those
257 appropriately. As an exception, it's traditional not to use this form when
258 referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead.
260 References to other programs or functions are normally in the form of man
261 page references so that cross-referencing tools can provide the user with
262 links and the like. It's possible to overdo this, though, so be careful not
263 to clutter your documentation with too much markup.
265 The major headers should be set out using a C<=head1> directive, and are
266 historically written in the rather startling ALL UPPER CASE format, although
267 this is not mandatory. Minor headers may be included using C<=head2>, and
268 are typically in mixed case.
270 The standard sections of a manual page are:
276 Mandatory section; should be a comma-separated list of programs or functions
277 documented by this podpage, such as:
279 foo, bar - programs to do something
281 Manual page indexers are often extremely picky about the format of this
282 section, so don't put anything in it except this line. A single dash, and
283 only a single dash, should separate the list of programs or functions from
284 the description. Functions should not be qualified with C<()> or the like.
285 The description should ideally fit on a single line, even if a man program
286 replaces the dash with a few tabs.
290 A short usage summary for programs and functions. This section is mandatory
295 Extended description and discussion of the program or functions, or the body
296 of the documentation for man pages that document something else. If
297 particularly long, it's a good idea to break this up into subsections
298 C<=head2> directives like:
302 =head2 Advanced Features
304 =head2 Writing Configuration Files
306 or whatever is appropriate for your documentation.
310 Detailed description of each of the command-line options taken by the
311 program. This should be separate from the description for the use of things
312 like L<Pod::Usage|Pod::Usage>. This is normally presented as a list, with
313 each option as a separate C<=item>. The specific option string should be
314 enclosed in BE<lt>E<gt>. Any values that the option takes should be
315 enclosed in IE<lt>E<gt>. For example, the section for the option
316 B<--section>=I<manext> would be introduced with:
318 =item B<--section>=I<manext>
320 Synonymous options (like both the short and long forms) are separated by a
321 comma and a space on the same C<=item> line, or optionally listed as their
322 own item with a reference to the canonical name. For example, since
323 B<--section> can also be written as B<-s>, the above would be:
325 =item B<-s> I<manext>, B<--section>=I<manext>
327 (Writing the short option first is arguably easier to read, since the long
328 option is long enough to draw the eye to it anyway and the short option can
329 otherwise get lost in visual noise.)
333 What the program or function returns, if successful. This section can be
334 omitted for programs whose precise exit codes aren't important, provided
335 they return 0 on success as is standard. It should always be present for
340 Exceptions, error return codes, exit statuses, and errno settings.
341 Typically used for function documentation; program documentation uses
342 DIAGNOSTICS instead. The general rule of thumb is that errors printed to
343 STDOUT or STDERR and intended for the end user are documented in DIAGNOSTICS
344 while errors passed internal to the calling program and intended for other
345 programmers are documented in ERRORS. When documenting a function that sets
346 errno, a full list of the possible errno values should be given here.
350 All possible messages the program can print out--and what they mean. You
351 may wish to follow the same documentation style as the Perl documentation;
352 see perldiag(1) for more details (and look at the POD source as well).
354 If applicable, please include details on what the user should do to correct
355 the error; documenting an error as indicating "the input buffer is too
356 small" without telling the user how to increase the size of the input buffer
357 (or at least telling them that it isn't possible) aren't very useful.
361 Give some example uses of the program or function. Don't skimp; users often
362 find this the most useful part of the documentation. The examples are
363 generally given as verbatim paragraphs.
365 Don't just present an example without explaining what it does. Adding a
366 short paragraph saying what the example will do can increase the value of
367 the example immensely.
371 Environment variables that the program cares about, normally presented as a
372 list using C<=over>, C<=item>, and C<=back>. For example:
378 Used to determine the user's home directory. F<.foorc> in this
379 directory is read for configuration details, if it exists.
383 Since environment variables are normally in all uppercase, no additional
384 special formatting is generally needed; they're glaring enough as it is.
388 All files used by the program or function, normally presented as a list, and
389 what it uses them for. File names should be enclosed in FE<lt>E<gt>. It's
390 particularly important to document files that will be potentially modified.
394 Things to take special care with, sometimes called WARNINGS.
398 Things that are broken or just don't work quite right.
402 Bugs you don't plan to fix. :-)
406 Miscellaneous commentary.
410 Other man pages to check out, like man(1), man(7), makewhatis(8), or
411 catman(8). Normally a simple list of man pages separated by commas, or a
412 paragraph giving the name of a reference work. Man page references, if they
413 use the standard C<name(section)> form, don't have to be enclosed in
414 LE<lt>E<gt>, but other things in this section probably should be when
415 appropriate. You may need to use the C<LE<lt>...|...E<gt>> syntax to keep
416 B<pod2man> and B<pod2text> from being too verbose; see perlpod(1).
418 If the package has a web site, include a URL here.
422 Who wrote it (use AUTHORS for multiple people). Including your current
423 e-mail address (or some e-mail address to which bug reports should be sent)
424 so that users have a way of contacting you is a good idea. Remember that
425 program documentation tends to roam the wild for far longer than you expect
426 and pick an e-mail address that's likely to last if possible.
430 Programs derived from other sources sometimes have this, or you might keep a
431 modification log here.
435 In addition, some systems use CONFORMING TO to note conformance to relevant
436 standards and MT-LEVEL to note safeness for use in threaded programs or
437 signal handlers. These headings are primarily useful when documenting parts
438 of a C library. Documentation of object-oriented libraries or modules may
439 use CONSTRUCTORS and METHODS sections for detailed documentation of the
440 parts of the library and save the DESCRIPTION section for an overview; other
441 large modules may use FUNCTIONS for similar reasons. Some people use
442 OVERVIEW to summarize the description if it's quite long. Sometimes there's
443 an additional COPYRIGHT section at the bottom, for licensing terms.
444 AVAILABILITY is sometimes added, giving the canonical download site for the
445 software or a URL for updates.
447 Section ordering varies, although NAME should I<always> be the first section
448 (you'll break some man page systems otherwise), and NAME, SYNOPSIS,
449 DESCRIPTION, and OPTIONS generally always occur first and in that order if
450 present. In general, SEE ALSO, AUTHOR, and similar material should be left
451 for last. Some systems also move WARNINGS and NOTES to last. The order
452 given above should be reasonable for most purposes.
454 Finally, as a general note, try not to use an excessive amount of markup.
455 As documented here and in L<Pod::Man>, you can safely leave Perl variables,
456 function names, man page references, and the like unadorned by markup and
457 the POD translators will figure it out for you. This makes it much easier
458 to later edit the documentation. Note that many existing translators
459 (including this one currently) will do the wrong thing with e-mail addresses
460 or URLs when wrapped in LE<lt>E<gt>, so don't do that.
462 For additional information that may be more accurate for your specific
463 system, see either man(5) or man(7) depending on your system manual section
464 numbering conventions.
468 L<Pod::Man|Pod::Man>, L<Pod::Parser|Pod::Parser>, man(1), nroff(1),
471 The man page documenting the an macro set may be man(5) instead of man(7) on
476 Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the
477 original B<pod2man> by Larry Wall and Tom Christiansen. Large portions of
478 this documentation, particularly the sections on the anatomy of a proper man
479 page, are taken from the B<pod2man> documentation by Tom.
485 close OUT or die "Can't close $file: $!";
486 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
487 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';