Initial Commit

database/perl/lib/pods/perlpodstyle.pod

@@ -0,0 +1,299 @@
+=head1 NAME
+
+perlpodstyle - Perl POD style guide
+
+=head1 DESCRIPTION
+
+These are general guidelines for how to write POD documentation for Perl
+scripts and modules, based on general guidelines for writing good UNIX man
+pages.  All of these guidelines are, of course, optional, but following
+them will make your documentation more consistent with other documentation
+on the system.
+
+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>).  Function names 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)> or C<LE<lt>manpage(section)E<gt>>, and Pod::Man will
+automatically format those appropriately.  The second form, with
+LE<lt>E<gt>, is used to request that a POD formatter make a link to the
+man page if possible.  As an exception, one normally omits the section
+when referring to module documentation since it's not clear what section
+module documentation will be in; use C<LE<lt>Module::NameE<gt>> for module
+references instead.
+
+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.  References to other
+programs that are not given as man page references should be enclosed in
+BE<lt>E<gt>.
+
+The major headers should be set out using a C<=head1> directive, and are
+historically written in the rather startling ALL UPPER CASE format; this
+is not mandatory, but it's strongly recommended so that sections have
+consistent naming across different software packages.  Minor headers may
+be included using C<=head2>, and are typically in mixed case.
+
+The standard sections of a manual page are:
+
+=over 4
+
+=item NAME
+
+Mandatory section; should be a comma-separated list of programs or
+functions documented by this POD page, such as:
+
+    foo, bar - programs to do something
+
+Manual page indexers are often extremely picky about the format of this
+section, so don't put anything in it except this line.  Every program or
+function documented by this POD page should be listed, separated by a
+comma and a space.  For a Perl module, just give the module name.  A
+single dash, and only a single dash, should separate the list of programs
+or functions from the description.  Do not use any markup such as
+CE<lt>E<gt> or BE<lt>E<gt> anywhere in this line.  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 SYNOPSIS
+
+A short usage summary for programs and functions.  This section is
+mandatory for section 3 pages.  For Perl module documentation, it's
+usually convenient to have the contents of this section be a verbatim
+block showing some (brief) examples of typical ways the module is used.
+
+=item DESCRIPTION
+
+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:
+
+    =head2 Normal Usage
+
+    =head2 Advanced Features
+
+    =head2 Writing Configuration Files
+
+or whatever is appropriate for your documentation.
+
+For a module, this is generally where the documentation of the interfaces
+provided by the module goes, usually in the form of a list with an
+C<=item> for each interface.  Depending on how many interfaces there are,
+you may want to put that documentation in separate METHODS, FUNCTIONS,
+CLASS METHODS, or INSTANCE METHODS sections instead and save the
+DESCRIPTION section for an overview.
+
+=item OPTIONS
+
+Detailed description of each of the command-line options taken by the
+program.  This should be separate from the description for the use of
+parsers like L<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:
+
+    =item B<--section>=I<manext>
+
+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:
+
+    =item B<-s> I<manext>, B<--section>=I<manext>
+
+Writing the short option first is recommended because it's easier to read.
+The long option is long enough to draw the eye to it anyway and the short
+option can otherwise get lost in visual noise.
+
+=item RETURN VALUE
+
+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 and non-zero on failure as is standard.  It
+should always be present for functions.  For modules, it may be useful to
+summarize return values from the module interface here, or it may be more
+useful to discuss return values separately in the documentation of each
+function or method the module provides.
+
+=item ERRORS
+
+Exceptions, error return codes, exit statuses, and errno settings.
+Typically used for function or module documentation; program documentation
+uses DIAGNOSTICS instead.  The general rule of thumb is that errors
+printed to C<STDOUT> or C<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.
+
+=item DIAGNOSTICS
+
+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).
+
+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.
+
+=item EXAMPLES
+
+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.
+
+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.
+
+=item ENVIRONMENT
+
+Environment variables that the program cares about, normally presented as
+a list using C<=over>, C<=item>, and C<=back>.  For example:
+
+    =over 6
+
+    =item HOME
+
+    Used to determine the user's home directory.  F<.foorc> in this
+    directory is read for configuration details, if it exists.
+
+    =back
+
+Since environment variables are normally in all uppercase, no additional
+special formatting is generally needed; they're glaring enough as it is.
+
+=item FILES
+
+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.
+
+=item CAVEATS
+
+Things to take special care with, sometimes called WARNINGS.
+
+=item BUGS
+
+Things that are broken or just don't work quite right.
+
+=item RESTRICTIONS
+
+Bugs you don't plan to fix.  :-)
+
+=item NOTES
+
+Miscellaneous commentary.
+
+=item AUTHOR
+
+Who wrote it (use AUTHORS for multiple people).  It's a good idea to
+include your current e-mail address (or some e-mail address to which bug
+reports should be sent) or some other contact information so that users
+have a way of contacting you.  Remember that program documentation tends
+to roam the wild for far longer than you expect and pick a contact method
+that's likely to last.
+
+=item HISTORY
+
+Programs derived from other sources sometimes have this.  Some people keep
+a modification log here, but that usually gets long and is normally better
+maintained in a separate file.
+
+=item COPYRIGHT AND LICENSE
+
+For copyright
+
+    Copyright YEAR(s) 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 example is neither an endorsement or a requirement, you are
+of course free to choose any licensing.
+
+=item SEE ALSO
+
+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> (although it's recommended), but other things in this section
+probably should be when appropriate.
+
+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.
+
+=back
+
+Documentation of object-oriented libraries or modules may want to use
+CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS
+sections, for detailed documentation of the parts of the library and save
+the DESCRIPTION section for an overview.  Large modules with a function
+interface may want to use FUNCTIONS for similar reasons.  Some people use
+OVERVIEW to summarize the description if it's quite long.
+
+Section ordering varies, although NAME must 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.
+
+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.
+
+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 will do the wrong thing with e-mail addresses when wrapped in
+LE<lt>E<gt>, so don't do that.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@cpan.org>, with large portions of this documentation
+taken from the documentation of the original B<pod2man> implementation by
+Larry Wall and Tom Christiansen.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015, 2018 Russ
+Allbery <rra@cpan.org>
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
+
+SPDX-License-Identifier: FSFAP
+
+=head1 SEE ALSO
+
+For additional information that may be more accurate for your specific
+system, see either L<man(5)> or L<man(7)> depending on your system manual
+section numbering conventions.
+
+This documentation is maintained as part of the podlators distribution.
+The current version is always available from its web site at
+L<https://www.eyrie.org/~eagle/software/podlators/>.
+
+=cut