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