X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fpod2man.PL;h=1c27bfe64dbd9d5a9bba6869bc31862ace85428c;hb=ff44e9538d55b6678e360b6132341dbc2eb5d2c3;hp=4c5831b90b5789cd1c77d4c63fa208b870ee89d1;hpb=ab1f1d91718d3ea14ab3ebc4fc169516f655f3d7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 4c5831b..1c27bfe 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -36,11 +36,11 @@ $Config{startperl} print OUT <<'!NO!SUBS!'; # pod2man -- Convert POD data to formatted *roff input. -# $Id: pod2man.PL,v 1.3 2000/09/03 09:20:52 eagle Exp $ +# $Id: pod2man.PL,v 1.9 2001/11/26 08:44:58 eagle Exp $ # -# Copyright 1999, 2000 by Russ Allbery +# Copyright 1999, 2000, 2001 by Russ Allbery # -# This program is free software; you can redistribute it and/or modify it +# This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. require 5.004; @@ -51,20 +51,23 @@ use Pod::Usage qw(pod2usage); use strict; +# Silence -w warnings. +use vars qw($running_under_some_shell); + # Insert -- into @ARGV before any single dash argument to hide it from # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser # does correctly). my $stdin; @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; -# Parse our options, trying to retain backwards compatibility with pod2man -# but allowing short forms as well. --lax is currently ignored. +# Parse our options, trying to retain backwards compatibility with pod2man but +# allowing short forms as well. --lax is currently ignored. my %options; Getopt::Long::config ('bundling_override'); GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s', - 'fixedbolditalic=s', 'official|o', 'quotes|q=s', 'lax|l', - 'help|h') or exit 1; + 'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s', + 'lax|l', 'help|h', 'verbose|v') or exit 1; pod2usage (0) if $options{help}; # Official sets --center, but don't override things explicitly set. @@ -72,9 +75,23 @@ if ($options{official} && !defined $options{center}) { $options{center} = 'Perl Programmers Reference Guide'; } -# Initialize and run the formatter. +# Verbose is only our flag, not a Pod::Man flag. +my $verbose = $options{verbose}; +delete $options{verbose}; + +# This isn't a valid Pod::Man option and is only accepted for backwards +# compatibility. +delete $options{lax}; + +# Initialize and run the formatter, pulling a pair of input and output off at +# a time. my $parser = Pod::Man->new (%options); -$parser->parse_from_file (@ARGV); +my @files; +do { + @files = splice (@ARGV, 0, 2); + print " $files[1]\n" if $verbose; + $parser->parse_from_file (@files); +} while (@ARGV); __END__ @@ -87,8 +104,9 @@ pod2man - Convert POD data to formatted *roff input pod2man [B<--section>=I] [B<--release>=I] [B<--center>=I] [B<--date>=I] [B<--fixed>=I] [B<--fixedbold>=I] [B<--fixeditalic>=I] -[B<--fixedbolditalic>=I] [B<--official>] [B<--lax>] -[B<--quotes>=I] [I [I]] +[B<--fixedbolditalic>=I] [B<--name>=I] [B<--official>] +[B<--lax>] [B<--quotes>=I] [B<--verbose>] +[I [I] ...] pod2man B<--help> @@ -101,7 +119,10 @@ terminal using nroff(1), normally via man(1), or printing using troff(1). I is the file to read for POD source (the POD can be embedded in code). If I isn't given, it defaults to STDIN. I, if given, is the file to which to write the formatted output. If I isn't -given, the formatted output is written to STDOUT. +given, the formatted output is written to STDOUT. Several POD files can be +processed in the same B invocation (saving module load and compile +times) by providing multiple pairs of I and I files on the +command line. B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be used to set the headers and footers to use; if not given, Pod::Man will @@ -166,8 +187,22 @@ Print out usage information. =item B<-l>, B<--lax> -Don't complain when required sections are missing. Not currently used, as -POD checking functionality is not yet implemented in Pod::Man. +No longer used. B used to check its input for validity as a manual +page, but this should now be done by L instead. Accepted for +backwards compatibility; this option no longer does anything. + +=item B<-n> I, B<--name>=I + +Set the name of the manual page to I. Without this option, the manual +name is set to the uppercased base name of the file being converted unless +the manual section is 3, in which case the path is parsed to see if it is a +Perl module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted +into a name like C. This option, if given, overrides any +automatic determination of the name. + +Note that this option is probably not useful when converting multiple POD +files at once. The convention for Unix man pages for commands is for the +man page title to be in all-uppercase even if the command isn't. =item B<-o>, B<--official> @@ -209,6 +244,10 @@ that are reliably consistent are 1, 2, and 3. By default, section 1 will be used unless the file ends in .pm in which case section 3 will be selected. +=item B<-v>, B<--verbose> + +Print out the name of each output file as it is being generated. + =back =head1 DIAGNOSTICS @@ -240,8 +279,6 @@ L for more details. Lots of this documentation is duplicated from L. -POD checking and the corresponding B<--lax> option don't work yet. - =head1 NOTES For those not sure of the proper layout of a man page, here are some notes @@ -415,6 +452,9 @@ LEE, but other things in this section probably should be when appropriate. You may need to use the C...|...E> syntax to keep B and B from being too verbose; see perlpod(1). +If the package has a mailing list, include a URL or subscription +instructions here. + If the package has a web site, include a URL here. =item AUTHOR @@ -425,10 +465,28 @@ so that users have a way of contacting you is a good idea. Remember that program documentation tends to roam the wild for far longer than you expect and pick an e-mail address that's likely to last if possible. +=item COPYRIGHT AND LICENSE + +For copyright + + Copyright YEAR(s) by YOUR NAME(s) + +(No, (C) is not needed. No, "all rights reserved" is not needed.) + +For licensing the easiest way is to use the same licensing as Perl itself: + + This library is free software; you may redistribute it and/or modify + it under the same terms as Perl itself. + +This makes it easy for people to use your module with Perl. Note that +this licensing is neither an endorsement or a requirement, you are of +course free to choose any licensing. + =item HISTORY -Programs derived from other sources sometimes have this, or you might keep a -modification log here. +Programs derived from other sources sometimes have this, or you might keep +a modification log here. If the log gets overly long or detailed, +consider maintaining it in a separate file, though. =back @@ -439,10 +497,7 @@ of a C library. Documentation of object-oriented libraries or modules may use CONSTRUCTORS and METHODS sections for detailed documentation of the parts of the library and save the DESCRIPTION section for an overview; other large modules may use FUNCTIONS for similar reasons. Some people use -OVERVIEW to summarize the description if it's quite long. Sometimes there's -an additional COPYRIGHT section at the bottom, for licensing terms. -AVAILABILITY is sometimes added, giving the canonical download site for the -software or a URL for updates. +OVERVIEW to summarize the description if it's quite long. Section ordering varies, although NAME should I be the first section (you'll break some man page systems otherwise), and NAME, SYNOPSIS, @@ -460,24 +515,31 @@ to later edit the documentation. Note that many existing translators or URLs when wrapped in LEE, so don't do that. For additional information that may be more accurate for your specific -system, see either man(5) or man(7) depending on your system manual section -numbering conventions. +system, see either L or L depending on your system manual +section numbering conventions. =head1 SEE ALSO -L, L, man(1), nroff(1), -troff(1), man(7) +L, L, L, L, L, +L, L -The man page documenting the an macro set may be man(5) instead of man(7) on -your system. +The man page documenting the an macro set may be L instead of +L on your system. =head1 AUTHOR -Russ Allbery Erra@stanford.eduE, based I heavily on the -original B by Larry Wall and Tom Christiansen. Large portions of -this documentation, particularly the sections on the anatomy of a proper man +Russ Allbery , based I heavily on the original +B by Larry Wall and Tom Christiansen. Large portions of this +documentation, particularly the sections on the anatomy of a proper man page, are taken from the B documentation by Tom. +=head1 COPYRIGHT AND LICENSE + +Copyright 1999, 2000, 2001 by Russ Allbery . + +This program is free software; you may redistribute it and/or modify it +under the same terms as Perl itself. + =cut !NO!SUBS! #'# (cperl-mode)