diff options
Diffstat (limited to 'contrib/perl5/pod/pod2man.PL')
| -rw-r--r-- | contrib/perl5/pod/pod2man.PL | 1389 |
1 files changed, 321 insertions, 1068 deletions
diff --git a/contrib/perl5/pod/pod2man.PL b/contrib/perl5/pod/pod2man.PL index 3c55d6e..bf35cff 100644 --- a/contrib/perl5/pod/pod2man.PL +++ b/contrib/perl5/pod/pod2man.PL @@ -9,7 +9,6 @@ use Cwd; # have to mention them as if they were shell variables, not # %Config entries. Thus you write # $startperl -# $man3ext # to ensure Configure will look for $Config{startperl}. # This forces PL files to create target in same directory as PL file. @@ -29,1191 +28,445 @@ print "Extracting $file (with variable substitutions)\n"; print OUT <<"!GROK!THIS!"; $Config{startperl} eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' - if \$running_under_some_shell; - -\$DEF_PM_SECTION = '$Config{man3ext}' || '3'; + if \$running_under_some_shell; !GROK!THIS! # In the following, perl variables are not expanded during extraction. print OUT <<'!NO!SUBS!'; -=head1 NAME - -pod2man - translate embedded Perl pod directives into man pages - -=head1 SYNOPSIS - -B<pod2man> -[ B<--section=>I<manext> ] -[ B<--release=>I<relpatch> ] -[ B<--center=>I<string> ] -[ B<--date=>I<string> ] -[ B<--fixed=>I<font> ] -[ B<--official> ] -[ B<--lax> ] -I<inputfile> - -=head1 DESCRIPTION - -B<pod2man> converts its input file containing embedded pod directives (see -L<perlpod>) into nroff source suitable for viewing with nroff(1) or -troff(1) using the man(7) macro set. - -Besides the obvious pod conversions, B<pod2man> also takes care of -func(), func(n), and simple variable references like $foo or @bar so -you don't have to use code escapes for them; complex expressions like -C<$fred{'stuff'}> will still need to be escaped, though. Other nagging -little roffish things that it catches include translating the minus in -something like foo-bar, making a long dash--like this--into a real em -dash, fixing up "paired quotes", putting a little space after the -parens in something like func(), making C++ and PI look right, making -double underbars have a little tiny space between them, making ALLCAPS -a teeny bit smaller in troff(1), and escaping backslashes so you don't -have to. - -=head1 OPTIONS - -=over 8 - -=item center - -Set the centered header to a specific string. The default is -"User Contributed Perl Documentation", unless the C<--official> flag is -given, in which case the default is "Perl Programmers Reference Guide". - -=item date - -Set the left-hand footer string to this value. By default, -the modification date of the input file will be used. - -=item fixed - -The fixed font to use for code refs. Defaults to CW. - -=item official - -Set the default header to indicate that this page is of -the standard release in case C<--center> is not given. - -=item release - -Set the centered footer. By default, this is the current -perl release. - -=item section - -Set the section for the C<.TH> macro. The standard conventions on -sections are to use 1 for user commands, 2 for system calls, 3 for -functions, 4 for devices, 5 for file formats, 6 for games, 7 for -miscellaneous information, and 8 for administrator commands. This works -best if you put your Perl man pages in a separate tree, like -F</usr/local/perl/man/>. By default, section 1 will be used -unless the file ends in F<.pm> in which case section 3 will be selected. - -=item lax - -Don't complain when required sections aren't present. - -=back - -=head1 Anatomy of a Proper Man Page - -For those not sure of the proper layout of a man page, here's -an example of the skeleton of a proper man page. Head of the -major headers should be setout as a C<=head1> directive, and -are historically written in the rather startling ALL UPPER CASE -format, although this is not mandatory. -Minor headers may be included using C<=head2>, and are -typically in mixed case. - -=over 10 - -=item NAME +# pod2man -- Convert POD data to formatted *roff input. +# $Id: pod2man.PL,v 1.2 2000/03/16 21:08:23 eagle Exp $ +# +# Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu> +# +# This program is free software; you can redistribute it and/or modify it +# under the same terms as Perl itself. + +require 5.004; + +use Getopt::Long qw(GetOptions); +use Pod::Man (); +use Pod::Usage qw(pod2usage); + +use strict; + +# 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. +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', 'lax|l', 'help|h') or exit 1; +pod2usage (0) if $options{help}; + +# Official sets --center, but don't override things explicitly set. +if ($options{official} && !defined $options{center}) { + $options{center} = 'Perl Programmers Reference Guide'; +} -Mandatory section; should be a comma-separated list of programs or -functions documented by this podpage, such as: +# Initialize and run the formatter. +my $parser = Pod::Man->new (%options); +$parser->parse_from_file (@ARGV); - foo, bar - programs to do something +__END__ -=item SYNOPSIS +=head1 NAME -A short usage summary for programs and functions, which -may someday be deemed mandatory. +pod2man - Convert POD data to formatted *roff input -=item DESCRIPTION +=head1 SYNOPSIS -Long drawn out discussion of the program. It's a good idea to break this -up into subsections using the C<=head2> directives, like +pod2man [B<--section>=I<manext>] [B<--release>=I<version>] +[B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>] +[B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] +[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] [I<input> +[I<output>]] - =head2 A Sample Subection +pod2man B<--help> - =head2 Yet Another Sample Subection +=head1 DESCRIPTION -=item OPTIONS +B<pod2man> is a front-end for Pod::Man, using it to generate *roff input +from POD source. The resulting *roff code is suitable for display on a +terminal using nroff(1), normally via man(1), or printing using troff(1). + +I<input> is the file to read for POD source (the POD can be embedded in +code). If I<input> isn't given, it defaults to STDIN. I<output>, if given, +is the file to which to write the formatted output. If I<output> isn't +given, the formatted output is written to STDOUT. + +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 +assume various defaults. See below or L<Pod::Man> for details. + +B<pod2man> assumes that your *roff formatters have a fixed-width font named +CW. If yours is called something else (like CR), use B<--fixed> to specify +it. This generally only matters for troff output for printing. Similarly, +you can set the fonts used for bold, italic, and bold italic fixed-width +output. + +Besides the obvious pod conversions, Pod::Man, and therefore pod2man also +takes care of formatting func(), func(n), and simple variable references +like $foo or @bar so you don't have to use code escapes for them; complex +expressions like C<$fred{'stuff'}> will still need to be escaped, though. +It also translates dashes that aren't used as hyphens into en dashes, makes +long dashes--like this--into proper em dashes, fixes "paired quotes," and +takes care of several other troff-specific tweaks. See L<Pod::Man> for +complete information. -Some people make this separate from the description. +=head1 OPTIONS -=item RETURN VALUE +=over 4 -What the program or function returns if successful. +=item B<-c> I<string>, B<--center>=I<string> -=item ERRORS +Sets the centered page header to I<string>. The default is "User +Contributed Perl Documentation", but also see B<--official> below. -Exceptions, return codes, exit stati, and errno settings. +=item B<-d> I<string>, B<--date>=I<string> -=item EXAMPLES +Set the left-hand footer string to this value. By default, the modification +date of the input file will be used, or the current date if input comes from +STDIN. -Give some example uses of the program. +=item B<--fixed>=I<font> -=item ENVIRONMENT +The fixed-width font to use for vertabim text and code. Defaults to CW. +Some systems may want CR instead. Only matters for troff(1) output. -Envariables this program might care about. +=item B<--fixedbold>=I<font> -=item FILES +Bold version of the fixed-width font. Defaults to CB. Only matters for +troff(1) output. -All files used by the program. You should probably use the FE<lt>E<gt> -for these. +=item B<--fixeditalic>=I<font> -=item SEE ALSO +Italic version of the fixed-width font (actually, something of a misnomer, +since most fixed-width fonts only have an oblique version, not an italic +version). Defaults to CI. Only matters for troff(1) output. -Other man pages to check out, like man(1), man(7), makewhatis(8), or catman(8). +=item B<--fixedbolditalic>=I<font> -=item NOTES +Bold italic (probably actually oblique) version of the fixed-width font. +Pod::Man doesn't assume you have this, and defaults to CB. Some systems +(such as Solaris) have this font available as CX. Only matters for troff(1) +output. -Miscellaneous commentary. +=item B<-h>, B<--help> -=item CAVEATS +Print out usage information. -Things to take special care with; sometimes called WARNINGS. +=item B<-l>, B<--lax> -=item DIAGNOSTICS +Don't complain when required sections are missing. Not currently used, as +POD checking functionality is not yet implemented in Pod::Man. -All possible messages the program can print out--and -what they mean. +=item B<-o>, B<--official> -=item BUGS +Set the default header to indicate that this page is part of the standard +Perl release, if B<--center> is not also given. -Things that are broken or just don't work quite right. +=item B<-r>, B<--release> -=item RESTRICTIONS +Set the centered footer. By default, this is the version of Perl you run +B<pod2man> under. Note that some system an macro sets assume that the +centered footer will be a modification date and will prepend something like +"Last modified: "; if this is the case, you may want to set B<--release> to +the last modified date and B<--date> to the version number. -Bugs you don't plan to fix :-) +=item B<-s>, B<--section> -=item AUTHOR +Set the section for the C<.TH> macro. The standard section numbering +convention is to use 1 for user commands, 2 for system calls, 3 for +functions, 4 for devices, 5 for file formats, 6 for games, 7 for +miscellaneous information, and 8 for administrator commands. There is a lot +of variation here, however; some systems (like Solaris) use 4 for file +formats, 5 for miscellaneous information, and 7 for devices. Still others +use 1m instead of 8, or some mix of both. About the only section numbers +that are reliably consistent are 1, 2, and 3. -Who wrote it (or AUTHORS if multiple). +By default, section 1 will be used unless the file ends in .pm in which case +section 3 will be selected. -=item HISTORY +=back -Programs derived from other sources sometimes have this, or -you might keep a modification log here. +=head1 DIAGNOSTICS -=back +If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Parser> for +information about what those errors might mean. =head1 EXAMPLES pod2man program > program.1 - pod2man some_module.pm > /usr/perl/man/man3/some_module.3 + pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3 pod2man --section=7 note.pod > note.7 -=head1 DIAGNOSTICS +If you would like to print out a lot of man page continuously, you probably +want to set the C and D registers to set contiguous page numbering and +even/odd paging, at least on some versions of man(7). -The following diagnostics are generated by B<pod2man>. Items -marked "(W)" are non-fatal, whereas the "(F)" errors will cause -B<pod2man> to immediately exit with a non-zero status. + troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ... -=over 4 +To get index entries on stderr, turn on the F register, as in: -=item bad option in paragraph %d of %s: ``%s'' should be [%s]<%s> + troff -man -rF1 perl.1 -(W) If you start include an option, you should set it off -as bold, italic, or code. +The indexing merely outputs messages via C<.tm> for each major page, +section, subsection, item, and any C<XE<lt>E<gt>> directives. See +L<Pod::Man> for more details. -=item can't open %s: %s +=head1 BUGS -(F) The input file wasn't available for the given reason. +Lots of this documentation is duplicated from L<Pod::Man>. -=item Improper man page - no dash in NAME header in paragraph %d of %s +POD checking and the corresponding B<--lax> option don't work yet. -(W) The NAME header did not have an isolated dash in it. This is -considered important. +=head1 NOTES -=item Invalid man page - no NAME line in %s +For those not sure of the proper layout of a man page, here are some notes +on writing a proper man page. -(F) You did not include a NAME header, which is essential. +The name of the program being documented is conventionally written in bold +(using BE<lt>E<gt>) wherever it occurs, as are all program options. +Arguments should be written in italics (IE<lt>E<gt>). Functions are +traditionally written in italics; if you write a function as function(), +Pod::Man will take care of this for you. Literal code or commands should +be in CE<lt>E<gt>. References to other man pages should be in the form +C<manpage(section)>, and Pod::Man will automatically format those +appropriately. As an exception, it's traditional not to use this form when +referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead. -=item roff font should be 1 or 2 chars, not `%s' (F) +References to other programs or functions are normally in the form of man +page references so that cross-referencing tools can provide the user with +links and the like. It's possible to overdo this, though, so be careful not +to clutter your documentation with too much markup. -(F) The font specified with the C<--fixed> option was not -a one- or two-digit roff font. +The major headers should be set out using a C<=head1> directive, and are +historically written in the rather startling ALL UPPER CASE format, although +this is not mandatory. Minor headers may be included using C<=head2>, and +are typically in mixed case. -=item %s is missing required section: %s +The standard sections of a manual page are: -(W) Required sections include NAME, DESCRIPTION, and if you're -using a section starting with a 3, also a SYNOPSIS. Actually, -not having a NAME is a fatal. +=over 4 -=item Unknown escape: %s in %s +=item NAME -(W) An unknown HTML entity (probably for an 8-bit character) was given via -a C<EE<lt>E<gt>> directive. Besides amp, lt, gt, and quot, recognized -entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave, agrave, -Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute, eacute, -Ecirc, ecirc, Egrave, egrave, ETH, eth, Euml, euml, Iacute, iacute, Icirc, -icirc, Igrave, igrave, Iuml, iuml, Ntilde, ntilde, Oacute, oacute, Ocirc, -ocirc, Ograve, ograve, Oslash, oslash, Otilde, otilde, Ouml, ouml, szlig, -THORN, thorn, Uacute, uacute, Ucirc, ucirc, Ugrave, ugrave, Uuml, uuml, -Yacute, yacute, and yuml. +Mandatory section; should be a comma-separated list of programs or functions +documented by this podpage, such as: -=item Unmatched =back + foo, bar - programs to do something -(W) You have a C<=back> without a corresponding C<=over>. +Manual page indexers are often extremely picky about the format of this +section, so don't put anything in it except this line. A single dash, and +only a single dash, should separate the list of programs or functions from +the description. Functions should not be qualified with C<()> or the like. +The description should ideally fit on a single line, even if a man program +replaces the dash with a few tabs. -=item Unrecognized pod directive: %s +=item SYNOPSIS -(W) You specified a pod directive that isn't in the known list of -C<=head1>, C<=head2>, C<=item>, C<=over>, C<=back>, or C<=cut>. +A short usage summary for programs and functions. This section is mandatory +for section 3 pages. +=item DESCRIPTION -=back +Extended description and discussion of the program or functions, or the body +of the documentation for man pages that document something else. If +particularly long, it's a good idea to break this up into subsections +C<=head2> directives like: -=head1 NOTES + =head2 Normal Usage -If you would like to print out a lot of man page continuously, you -probably want to set the C and D registers to set contiguous page -numbering and even/odd paging, at least on some versions of man(7). -Settting the F register will get you some additional experimental -indexing: + =head2 Advanced Features - troff -man -rC1 -rD1 -rF1 perl.1 perldata.1 perlsyn.1 ... + =head2 Writing Configuration Files -The indexing merely outputs messages via C<.tm> for each -major page, section, subsection, item, and any C<XE<lt>E<gt>> -directives. +or whatever is appropriate for your documentation. +=item OPTIONS -=head1 RESTRICTIONS +Detailed description of each of the command-line options taken by the +program. This should be separate from the description for the use of things +like L<Pod::Usage|Pod::Usage>. This is normally presented as a list, with +each option as a separate C<=item>. The specific option string should be +enclosed in BE<lt>E<gt>. Any values that the option takes should be +enclosed in IE<lt>E<gt>. For example, the section for the option +B<--section>=I<manext> would be introduced with: -None at this time. + =item B<--section>=I<manext> -=head1 BUGS +Synonymous options (like both the short and long forms) are separated by a +comma and a space on the same C<=item> line, or optionally listed as their +own item with a reference to the canonical name. For example, since +B<--section> can also be written as B<-s>, the above would be: -The =over and =back directives don't really work right. They -take absolute positions instead of offsets, don't nest well, and -making people count is suboptimal in any event. + =item B<-s> I<manext>, B<--section>=I<manext> -=head1 AUTHORS +(Writing the short option first is arguably easier to read, since the long +option is long enough to draw the eye to it anyway and the short option can +otherwise get lost in visual noise.) -Original prototype by Larry Wall, but so massively hacked over by -Tom Christiansen such that Larry probably doesn't recognize it anymore. +=item RETURN VALUE -=cut +What the program or function returns, if successful. This section can be +omitted for programs whose precise exit codes aren't important, provided +they return 0 on success as is standard. It should always be present for +functions. -$/ = ""; -$cutting = 1; -@Indices = (); - -# We try first to get the version number from a local binary, in case we're -# running an installed version of Perl to produce documentation from an -# uninstalled newer version's pod files. -if ($^O ne 'plan9' and $^O ne 'dos' and $^O ne 'os2' and $^O ne 'MSWin32') { - my $perl = (-x './perl' && -f './perl' ) ? - './perl' : - ((-x '../perl' && -f '../perl') ? - '../perl' : - ''); - ($version,$patch) = `$perl -e 'print $]'` =~ /^(\d\.\d{3})(\d{2})?/ if $perl; -} -# No luck; we'll just go with the running Perl's version -($version,$patch) = $] =~ /^(.{5})(\d{2})?/ unless $version; -$DEF_RELEASE = "perl $version"; -$DEF_RELEASE .= ", patch $patch" if $patch; - - -sub makedate { - my $secs = shift; - my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime($secs); - my $mname = (qw{Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec})[$mon]; - $year += 1900; - return "$mday/$mname/$year"; -} +=item ERRORS -use Getopt::Long; - -$DEF_SECTION = 1; -$DEF_CENTER = "User Contributed Perl Documentation"; -$STD_CENTER = "Perl Programmers Reference Guide"; -$DEF_FIXED = 'CW'; -$DEF_LAX = 0; - -sub usage { - warn "$0: @_\n" if @_; - die <<EOF; -usage: $0 [options] podpage -Options are: - --section=manext (default "$DEF_SECTION") - --release=relpatch (default "$DEF_RELEASE") - --center=string (default "$DEF_CENTER") - --date=string (default "$DEF_DATE") - --fixed=font (default "$DEF_FIXED") - --official (default NOT) - --lax (default NOT) -EOF -} +Exceptions, error return codes, exit statuses, and errno settings. +Typically used for function documentation; program documentation uses +DIAGNOSTICS instead. The general rule of thumb is that errors printed to +STDOUT or STDERR and intended for the end user are documented in DIAGNOSTICS +while errors passed internal to the calling program and intended for other +programmers are documented in ERRORS. When documenting a function that sets +errno, a full list of the possible errno values should be given here. -$uok = GetOptions( qw( - section=s - release=s - center=s - date=s - fixed=s - official - lax - help)); +=item DIAGNOSTICS -$DEF_DATE = makedate((stat($ARGV[0]))[9] || time()); +All possible messages the program can print out--and what they mean. You +may wish to follow the same documentation style as the Perl documentation; +see perldiag(1) for more details (and look at the POD source as well). -usage("Usage error!") unless $uok; -usage() if $opt_help; -usage("Need one and only one podpage argument") unless @ARGV == 1; +If applicable, please include details on what the user should do to correct +the error; documenting an error as indicating "the input buffer is too +small" without telling the user how to increase the size of the input buffer +(or at least telling them that it isn't possible) aren't very useful. -$section = $opt_section || ($ARGV[0] =~ /\.pm$/ - ? $DEF_PM_SECTION : $DEF_SECTION); -$RP = $opt_release || $DEF_RELEASE; -$center = $opt_center || ($opt_official ? $STD_CENTER : $DEF_CENTER); -$lax = $opt_lax || $DEF_LAX; +=item EXAMPLES -$CFont = $opt_fixed || $DEF_FIXED; +Give some example uses of the program or function. Don't skimp; users often +find this the most useful part of the documentation. The examples are +generally given as verbatim paragraphs. -if (length($CFont) == 2) { - $CFont_embed = "\\f($CFont"; -} -elsif (length($CFont) == 1) { - $CFont_embed = "\\f$CFont"; -} -else { - die "roff font should be 1 or 2 chars, not `$CFont_embed'"; -} +Don't just present an example without explaining what it does. Adding a +short paragraph saying what the example will do can increase the value of +the example immensely. -$date = $opt_date || $DEF_DATE; +=item ENVIRONMENT -for (qw{NAME DESCRIPTION}) { -# for (qw{NAME DESCRIPTION AUTHOR}) { - $wanna_see{$_}++; -} -$wanna_see{SYNOPSIS}++ if $section =~ /^3/; +Environment variables that the program cares about, normally presented as a +list using C<=over>, C<=item>, and C<=back>. For example: + =over 6 -$name = @ARGV ? $ARGV[0] : "<STDIN>"; -$Filename = $name; -if ($section =~ /^1/) { - require File::Basename; - $name = uc File::Basename::basename($name); -} -$name =~ s/\.(pod|p[lm])$//i; - -# Lose everything up to the first of -# */lib/*perl* standard or site_perl module -# */*perl*/lib from -D prefix=/opt/perl -# */*perl*/ random module hierarchy -# which works. -$name =~ s-//+-/-g; -if ($name =~ s-^.*?/lib/[^/]*perl[^/]*/--i - or $name =~ s-^.*?/[^/]*perl[^/]*/lib/--i - or $name =~ s-^.*?/[^/]*perl[^/]*/--i) { - # Lose ^site(_perl)?/. - $name =~ s-^site(_perl)?/--; - # Lose ^arch/. (XXX should we use Config? Just for archname?) - $name =~ s~^(.*-$^O|$^O-.*)/~~o; - # Lose ^version/. - $name =~ s-^\d+\.\d+/--; -} + =item HOME -# Translate Getopt/Long to Getopt::Long, etc. -$name =~ s(/)(::)g; - -if ($name ne 'something') { - FCHECK: { - open(F, "< $ARGV[0]") || die "can't open $ARGV[0]: $!"; - while (<F>) { - next unless /^=\b/; - if (/^=head1\s+NAME\s*$/) { # an /m would forgive mistakes - $_ = <F>; - unless (/\s*-+\s+/) { - $oops++; - warn "$0: Improper man page - no dash in NAME header in paragraph $. of $ARGV[0]\n" - } else { - my @n = split /\s+-+\s+/; - if (@n != 2) { - $oops++; - warn "$0: Improper man page - malformed NAME header in paragraph $. of $ARGV[0]\n" - } - else { - %namedesc = @n; - } - } - last FCHECK; - } - next if /^=cut\b/; # DB_File and Net::Ping have =cut before NAME - next if /^=pod\b/; # It is OK to have =pod before NAME - die "$0: Invalid man page - 1st pod line is not NAME in $ARGV[0]\n" unless $lax; - } - die "$0: Invalid man page - no documentation in $ARGV[0]\n" unless $lax; - } - close F; -} + Used to determine the user's home directory. F<.foorc> in this + directory is read for configuration details, if it exists. -print <<"END"; -.rn '' }` -''' \$RCSfile\$\$Revision\$\$Date\$ -''' -''' \$Log\$ -''' -.de Sh -.br -.if t .Sp -.ne 5 -.PP -\\fB\\\\\$1\\fR -.PP -.. -.de Sp -.if t .sp .5v -.if n .sp -.. -.de Ip -.br -.ie \\\\n(.\$>=3 .ne \\\\\$3 -.el .ne 3 -.IP "\\\\\$1" \\\\\$2 -.. -.de Vb -.ft $CFont -.nf -.ne \\\\\$1 -.. -.de Ve -.ft R - -.fi -.. -''' -''' -''' Set up \\*(-- to give an unbreakable dash; -''' string Tr holds user defined translation string. -''' Bell System Logo is used as a dummy character. -''' -.tr \\(*W-|\\(bv\\*(Tr -.ie n \\{\\ -.ds -- \\(*W- -.ds PI pi -.if (\\n(.H=4u)&(1m=24u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-12u'-\\" diablo 10 pitch -.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch -.ds L" "" -.ds R" "" -''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of -''' \\*(L" and \\*(R", except that they are used on ".xx" lines, -''' such as .IP and .SH, which do another additional levels of -''' double-quote interpretation -.ds M" """ -.ds S" """ -.ds N" """"" -.ds T" """"" -.ds L' ' -.ds R' ' -.ds M' ' -.ds S' ' -.ds N' ' -.ds T' ' -'br\\} -.el\\{\\ -.ds -- \\(em\\| -.tr \\*(Tr -.ds L" `` -.ds R" '' -.ds M" `` -.ds S" '' -.ds N" `` -.ds T" '' -.ds L' ` -.ds R' ' -.ds M' ` -.ds S' ' -.ds N' ` -.ds T' ' -.ds PI \\(*p -'br\\} -END - -print <<'END'; -.\" If the F register is turned on, we'll generate -.\" index entries out stderr for the following things: -.\" TH Title -.\" SH Header -.\" Sh Subsection -.\" Ip Item -.\" X<> Xref (embedded -.\" Of course, you have to process the output yourself -.\" in some meaninful fashion. -.if \nF \{ -.de IX -.tm Index:\\$1\t\\n%\t"\\$2" -.. -.nr % 0 -.rr F -.\} -END - -print <<"END"; -.TH $name $section "$RP" "$date" "$center" -.UC -END - -push(@Indices, qq{.IX Title "$name $section"}); - -while (($name, $desc) = each %namedesc) { - for ($name, $desc) { s/^\s+//; s/\s+$//; } - push(@Indices, qq(.IX Name "$name - $desc"\n)); -} + =back -print <<'END'; -.if n .hy 0 -.if n .na -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.de CQ \" put $1 in typewriter font -END -print ".ft $CFont\n"; -print <<'END'; -'if n "\c -'if t \\&\\$1\c -'if n \\&\\$1\c -'if n \&" -\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 -'.ft R -.. -.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 -. \" AM - accent mark definitions -.bd B 3 -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds ? ? -. ds ! ! -. ds / -. ds q -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' -. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] -.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' -.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' -.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -.ds oe o\h'-(\w'o'u*4/10)'e -.ds Oe O\h'-(\w'O'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds v \h'-1'\o'\(aa\(ga' -. ds _ \h'-1'^ -. ds . \h'-1'. -. ds 3 3 -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -. ds oe oe -. ds Oe OE -.\} -.rm #[ #] #H #V #F C -END - -$indent = 0; - -$begun = ""; - -# Unrolling [^A-Z>]|[A-Z](?!<) gives: // MRE pp 165. -my $nonest = '(?:[^A-Z>]*(?:[A-Z](?!<)[^A-Z>]*)*)'; - -while (<>) { - if ($cutting) { - next unless /^=/; - $cutting = 0; - } - if ($begun) { - if (/^=end\s+$begun/) { - $begun = ""; - } - elsif ($begun =~ /^(roff|man)$/) { - print STDOUT $_; - } - next; - } - chomp; - - # Translate verbatim paragraph - - if (/^\s/) { - @lines = split(/\n/); - for (@lines) { - 1 while s - {^( [^\t]* ) \t ( \t* ) } - { $1 . ' ' x (8 - (length($1)%8) + 8 * (length($2))) }ex; - s/\\/\\e/g; - s/\A/\\&/s; - } - $lines = @lines; - makespace() unless $verbatim++; - print ".Vb $lines\n"; - print join("\n", @lines), "\n"; - print ".Ve\n"; - $needspace = 0; - next; - } - - $verbatim = 0; - - if (/^=for\s+(\S+)\s*/s) { - if ($1 eq "man" or $1 eq "roff") { - print STDOUT $',"\n\n"; - } else { - # ignore unknown for - } - next; - } - elsif (/^=begin\s+(\S+)\s*/s) { - $begun = $1; - if ($1 eq "man" or $1 eq "roff") { - print STDOUT $'."\n\n"; - } - next; - } - - # check for things that'll hosed our noremap scheme; affects $_ - init_noremap(); - - if (!/^=item/) { - - # trofficate backslashes; must do it before what happens below - s/\\/noremap('\\e')/ge; - - # protect leading periods and quotes against *roff - # mistaking them for directives - s/^(?:[A-Z]<)?[.']/\\&$&/gm; - - # first hide the escapes in case we need to - # intuit something and get it wrong due to fmting - - 1 while s/([A-Z]<$nonest>)/noremap($1)/ge; - - # func() is a reference to a perl function - s{ - \b - ( - [:\w]+ \(\) - ) - } {I<$1>}gx; - - # func(n) is a reference to a perl function or a man page - s{ - ([:\w]+) - ( - \( [^\051]+ \) - ) - } {I<$1>\\|$2}gx; - - # convert simple variable references - s/(\s+)([\$\@%][\w:]+)(?!\()/${1}C<$2>/g; - - if (m{ ( - [\-\w]+ - \( - [^\051]*? - [\@\$,] - [^\051]*? - \) - ) - }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/) - { - warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [LCI]<$1>\n"; - $oops++; - } - - while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) { - warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [CB]<$1>\n"; - $oops++; - } - - # put it back so we get the <> processed again; - clear_noremap(0); # 0 means leave the E's - - } else { - # trofficate backslashes - s/\\/noremap('\\e')/ge; - - } - - # need to hide E<> first; they're processed in clear_noremap - s/(E<[^<>]+>)/noremap($1)/ge; - - - $maxnest = 10; - while ($maxnest-- && /[A-Z]</) { - - # can't do C font here - s/([BI])<($nonest)>/font($1) . $2 . font('R')/eg; - - # files and filelike refs in italics - s/F<($nonest)>/I<$1>/g; - - # no break -- usually we want C<> for this - s/S<($nonest)>/nobreak($1)/eg; - - # LREF: a la HREF L<show this text|man/section> - s:L<([^|>]+)\|[^>]+>:$1:g; - - # LREF: a manpage(3f) - s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g; - - # LREF: an =item on another manpage - s{ - L< - ([^/]+) - / - ( - [:\w]+ - (\(\))? - ) - > - } {the C<$2> entry in the I<$1> manpage}gx; - - # LREF: an =item on this manpage - s{ - ((?: - L< - / - ( - [:\w]+ - (\(\))? - ) - > - (,?\s+(and\s+)?)? - )+) - } { internal_lrefs($1) }gex; - - # LREF: a =head2 (head1?), maybe on a manpage, maybe right here - # the "func" can disambiguate - s{ - L< - (?: - ([a-zA-Z]\S+?) / - )? - "?(.*?)"? - > - }{ - do { - $1 # if no $1, assume it means on this page. - ? "the section on I<$2> in the I<$1> manpage" - : "the section on I<$2>" - } - }gesx; # s in case it goes over multiple lines, so . matches \n - - s/Z<>/\\&/g; - - # comes last because not subject to reprocessing - s/C<($nonest)>/noremap("${CFont_embed}${1}\\fR")/eg; - } - - if (s/^=//) { - $needspace = 0; # Assume this. - - s/\n/ /g; - - ($Cmd, $_) = split(' ', $_, 2); - - $dotlevel = 1; - if ($Cmd eq 'head1') { - $dotlevel = 1; - } - elsif ($Cmd eq 'head2') { - $dotlevel = 1; - } - elsif ($Cmd eq 'item') { - $dotlevel = 2; - } - - if (defined $_) { - &escapes($dotlevel); - s/"/""/g; - } - - clear_noremap(1); - - if ($Cmd eq 'cut') { - $cutting = 1; - } - elsif ($Cmd eq 'head1') { - s/\s+$//; - delete $wanna_see{$_} if exists $wanna_see{$_}; - print qq{.SH "$_"\n}; - push(@Indices, qq{.IX Header "$_"\n}); - } - elsif ($Cmd eq 'head2') { - print qq{.Sh "$_"\n}; - push(@Indices, qq{.IX Subsection "$_"\n}); - } - elsif ($Cmd eq 'over') { - push(@indent,$indent); - $indent += ($_ + 0) || 5; - } - elsif ($Cmd eq 'back') { - $indent = pop(@indent); - warn "$0: Unmatched =back in paragraph $. of $ARGV\n" unless defined $indent; - $needspace = 1; - } - elsif ($Cmd eq 'item') { - s/^\*( |$)/\\(bu$1/g; - # if you know how to get ":s please do - s/\\\*\(L"([^"]+?)\\\*\(R"/'$1'/g; - s/\\\*\(L"([^"]+?)""/'$1'/g; - s/[^"]""([^"]+?)""[^"]/'$1'/g; - # here do something about the $" in perlvar? - print STDOUT qq{.Ip "$_" $indent\n}; - push(@Indices, qq{.IX Item "$_"\n}); - } - elsif ($Cmd eq 'pod') { - # this is just a comment - } - else { - warn "$0: Unrecognized pod directive in paragraph $. of $ARGV: $Cmd\n"; - } - } - else { - if ($needspace) { - &makespace; - } - &escapes(0); - clear_noremap(1); - print $_, "\n"; - $needspace = 1; - } -} +Since environment variables are normally in all uppercase, no additional +special formatting is generally needed; they're glaring enough as it is. -print <<"END"; +=item FILES -.rn }` '' -END +All files used by the program or function, normally presented as a list, and +what it uses them for. File names should be enclosed in FE<lt>E<gt>. It's +particularly important to document files that will be potentially modified. -if (%wanna_see && !$lax) { - @missing = keys %wanna_see; - warn "$0: $Filename is missing required section" - . (@missing > 1 && "s") - . ": @missing\n"; - $oops++; -} +=item CAVEATS -foreach (@Indices) { print "$_\n"; } +Things to take special care with, sometimes called WARNINGS. -exit; -#exit ($oops != 0); +=item BUGS -######################################################################### +Things that are broken or just don't work quite right. -sub nobreak { - my $string = shift; - $string =~ s/ /\\ /g; - $string; -} +=item RESTRICTIONS -sub escapes { - my $indot = shift; - - s/X<(.*?)>/mkindex($1)/ge; - - # translate the minus in foo-bar into foo\-bar for roff - s/([^0-9a-z-])-([^-])/$1\\-$2/g; - - # make -- into the string version \*(-- (defined above) - s/\b--\b/\\*(--/g; - s/"--([^"])/"\\*(--$1/g; # should be a better way - s/([^"])--"/$1\\*(--"/g; - - # fix up quotes; this is somewhat tricky - my $dotmacroL = 'L'; - my $dotmacroR = 'R'; - if ( $indot == 1 ) { - $dotmacroL = 'M'; - $dotmacroR = 'S'; - } - elsif ( $indot >= 2 ) { - $dotmacroL = 'N'; - $dotmacroR = 'T'; - } - if (!/""/) { - s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge; - s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge; - } - - #s/(?!")(?:.)--(?!")(?:.)/\\*(--/g; - #s/(?:(?!")(?:.)--(?:"))|(?:(?:")--(?!")(?:.))/\\*(--/g; - - - # make sure that func() keeps a bit a space tween the parens - ### s/\b\(\)/\\|()/g; - ### s/\b\(\)/(\\|)/g; - - # make C++ into \*C+, which is a squinched version (defined above) - s/\bC\+\+/\\*(C+/g; - - # make double underbars have a little tiny space between them - s/__/_\\|_/g; - - # PI goes to \*(PI (defined above) - s/\bPI\b/noremap('\\*(PI')/ge; - - # make all caps a teeny bit smaller, but don't muck with embedded code literals - my $hidCFont = font('C'); - if ($Cmd !~ /^head1/) { # SH already makes smaller - # /g isn't enough; 1 while or we'll be off - -# 1 while s{ -# (?!$hidCFont)(..|^.|^) -# \b -# ( -# [A-Z][\/A-Z+:\-\d_$.]+ -# ) -# (s?) -# \b -# } {$1\\s-1$2\\s0}gmox; - - 1 while s{ - (?!$hidCFont)(..|^.|^) - ( - \b[A-Z]{2,}[\/A-Z+:\-\d_\$]*\b - ) - } { - $1 . noremap( '\\s-1' . $2 . '\\s0' ) - }egmox; - - } -} +Bugs you don't plan to fix. :-) -# make troff just be normal, but make small nroff get quoted -# decided to just put the quotes in the text; sigh; -sub ccvt { - local($_,$prev) = @_; - noremap(qq{.CQ "$_" \n\\&}); -} +=item NOTES -sub makespace { - if ($indent) { - print ".Sp\n"; - } - else { - print ".PP\n"; - } -} +Miscellaneous commentary. -sub mkindex { - my ($entry) = @_; - my @entries = split m:\s*/\s*:, $entry; - push @Indices, ".IX Xref " . join ' ', map {qq("$_")} @entries; - return ''; -} +=item SEE ALSO -sub font { - local($font) = shift; - return '\\f' . noremap($font); -} +Other man pages to check out, like man(1), man(7), makewhatis(8), or +catman(8). Normally a simple list of man pages separated by commas, or a +paragraph giving the name of a reference work. Man page references, if they +use the standard C<name(section)> form, don't have to be enclosed in +LE<lt>E<gt>, but other things in this section probably should be when +appropriate. You may need to use the C<LE<lt>...|...E<gt>> syntax to keep +B<pod2man> and B<pod2text> from being too verbose; see perlpod(1). -sub noremap { - local($thing_to_hide) = shift; - $thing_to_hide =~ tr/\000-\177/\200-\377/; - return $thing_to_hide; -} +If the package has a web site, include a URL here. -sub init_noremap { - # escape high bit characters in input stream - s/([\200-\377])/"E<".ord($1).">"/ge; -} +=item AUTHOR -sub clear_noremap { - my $ready_to_print = $_[0]; - - tr/\200-\377/\000-\177/; - - # trofficate backslashes - # s/(?!\\e)(?:..|^.|^)\\/\\e/g; - - # now for the E<>s, which have been hidden until now - # otherwise the interative \w<> processing would have - # been hosed by the E<gt> - s { - E< - ( - ( \d + ) - | ( [A-Za-z]+ ) - ) - > - } { - do { - defined $2 - ? chr($2) - : - exists $HTML_Escapes{$3} - ? do { $HTML_Escapes{$3} } - : do { - warn "$0: Unknown escape in paragraph $. of $ARGV: ``$&''\n"; - "E<$1>"; - } - } - }egx if $ready_to_print; -} +Who wrote it (use AUTHORS for multiple people). Including your current +e-mail address (or some e-mail address to which bug reports should be sent) +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. -sub internal_lrefs { - local($_) = shift; - local $trailing_and = s/and\s+$// ? "and " : ""; - - s{L</([^>]+)>}{$1}g; - my(@items) = split( /(?:,?\s+(?:and\s+)?)/ ); - my $retstr = "the "; - my $i; - for ($i = 0; $i <= $#items; $i++) { - $retstr .= "C<$items[$i]>"; - $retstr .= ", " if @items > 2 && $i != $#items; - $retstr .= " and " if $i+2 == @items; - } - - $retstr .= " entr" . ( @items > 1 ? "ies" : "y" ) - . " elsewhere in this document"; - # terminal space to avoid words running together (pattern used - # strips terminal spaces) - $retstr .= " " if length $trailing_and; - $retstr .= $trailing_and; - - return $retstr; +=item HISTORY -} +Programs derived from other sources sometimes have this, or you might keep a +modification log here. -BEGIN { -%HTML_Escapes = ( - 'amp' => '&', # ampersand - 'lt' => '<', # left chevron, less-than - 'gt' => '>', # right chevron, greater-than - 'quot' => '"', # double quote - - "Aacute" => "A\\*'", # capital A, acute accent - "aacute" => "a\\*'", # small a, acute accent - "Acirc" => "A\\*^", # capital A, circumflex accent - "acirc" => "a\\*^", # small a, circumflex accent - "AElig" => '\*(AE', # capital AE diphthong (ligature) - "aelig" => '\*(ae', # small ae diphthong (ligature) - "Agrave" => "A\\*`", # capital A, grave accent - "agrave" => "A\\*`", # small a, grave accent - "Aring" => 'A\\*o', # capital A, ring - "aring" => 'a\\*o', # small a, ring - "Atilde" => 'A\\*~', # capital A, tilde - "atilde" => 'a\\*~', # small a, tilde - "Auml" => 'A\\*:', # capital A, dieresis or umlaut mark - "auml" => 'a\\*:', # small a, dieresis or umlaut mark - "Ccedil" => 'C\\*,', # capital C, cedilla - "ccedil" => 'c\\*,', # small c, cedilla - "Eacute" => "E\\*'", # capital E, acute accent - "eacute" => "e\\*'", # small e, acute accent - "Ecirc" => "E\\*^", # capital E, circumflex accent - "ecirc" => "e\\*^", # small e, circumflex accent - "Egrave" => "E\\*`", # capital E, grave accent - "egrave" => "e\\*`", # small e, grave accent - "ETH" => '\\*(D-', # capital Eth, Icelandic - "eth" => '\\*(d-', # small eth, Icelandic - "Euml" => "E\\*:", # capital E, dieresis or umlaut mark - "euml" => "e\\*:", # small e, dieresis or umlaut mark - "Iacute" => "I\\*'", # capital I, acute accent - "iacute" => "i\\*'", # small i, acute accent - "Icirc" => "I\\*^", # capital I, circumflex accent - "icirc" => "i\\*^", # small i, circumflex accent - "Igrave" => "I\\*`", # capital I, grave accent - "igrave" => "i\\*`", # small i, grave accent - "Iuml" => "I\\*:", # capital I, dieresis or umlaut mark - "iuml" => "i\\*:", # small i, dieresis or umlaut mark - "Ntilde" => 'N\*~', # capital N, tilde - "ntilde" => 'n\*~', # small n, tilde - "Oacute" => "O\\*'", # capital O, acute accent - "oacute" => "o\\*'", # small o, acute accent - "Ocirc" => "O\\*^", # capital O, circumflex accent - "ocirc" => "o\\*^", # small o, circumflex accent - "Ograve" => "O\\*`", # capital O, grave accent - "ograve" => "o\\*`", # small o, grave accent - "Oslash" => "O\\*/", # capital O, slash - "oslash" => "o\\*/", # small o, slash - "Otilde" => "O\\*~", # capital O, tilde - "otilde" => "o\\*~", # small o, tilde - "Ouml" => "O\\*:", # capital O, dieresis or umlaut mark - "ouml" => "o\\*:", # small o, dieresis or umlaut mark - "szlig" => '\*8', # small sharp s, German (sz ligature) - "THORN" => '\\*(Th', # capital THORN, Icelandic - "thorn" => '\\*(th',, # small thorn, Icelandic - "Uacute" => "U\\*'", # capital U, acute accent - "uacute" => "u\\*'", # small u, acute accent - "Ucirc" => "U\\*^", # capital U, circumflex accent - "ucirc" => "u\\*^", # small u, circumflex accent - "Ugrave" => "U\\*`", # capital U, grave accent - "ugrave" => "u\\*`", # small u, grave accent - "Uuml" => "U\\*:", # capital U, dieresis or umlaut mark - "uuml" => "u\\*:", # small u, dieresis or umlaut mark - "Yacute" => "Y\\*'", # capital Y, acute accent - "yacute" => "y\\*'", # small y, acute accent - "yuml" => "y\\*:", # small y, dieresis or umlaut mark -); -} +=back + +In addition, some systems use CONFORMING TO to note conformance to relevant +standards and MT-LEVEL to note safeness for use in threaded programs or +signal handlers. These headings are primarily useful when documenting parts +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. + +Section ordering varies, although NAME should I<always> be the first section +(you'll break some man page systems otherwise), and NAME, SYNOPSIS, +DESCRIPTION, and OPTIONS generally always occur first and in that order if +present. In general, SEE ALSO, AUTHOR, and similar material should be left +for last. Some systems also move WARNINGS and NOTES to last. The order +given above should be reasonable for most purposes. + +Finally, as a general note, try not to use an excessive amount of markup. +As documented here and in L<Pod::Man>, you can safely leave Perl variables, +function names, man page references, and the like unadorned by markup and +the POD translators will figure it out for you. This makes it much easier +to later edit the documentation. Note that many existing translators +(including this one currently) will do the wrong thing with e-mail addresses +or URLs when wrapped in LE<lt>E<gt>, 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. + +=head1 SEE ALSO + +L<Pod::Man|Pod::Man>, L<Pod::Parser|Pod::Parser>, man(1), nroff(1), +troff(1), man(7) + +The man page documenting the an macro set may be man(5) instead of man(7) on +your system. + +=head1 AUTHOR + +Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the +original B<pod2man> 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<pod2man> documentation by Tom. +=cut !NO!SUBS! +#'# (cperl-mode) close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; |
