summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod338
1 files changed, 0 insertions, 338 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod b/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod
deleted file mode 100644
index 850f38dc8d9..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod
+++ /dev/null
@@ -1,338 +0,0 @@
-=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.
-
-Here are some simple guidelines for markup; see L<perlpod> for details.
-
-=over
-
-=item bold (BE<lt>E<gt>)
-
-B<NOTE: Use extremely rarely.> Do I<not> use bold for emphasis; that's
-what italics are for. Restrict bold for notices like B<NOTE:> and
-B<WARNING:>. However, program arguments and options--but I<not> their
-names!--are written in bold (using BE<lt>E<gt>) to distinguish the B<-f>
-command-line option from the C<-f> filetest operator.
-
-=item italic (IE<lt>E<gt>)
-
-Use italic to emphasize text, like I<this>. Function names are
-traditionally written in italics; if you write a function as function(),
-Pod::Man will take care of this for you. Names of programs, including the
-name of the program being documented, are conventionally written in italics
-(using IE<lt>E<gt>) wherever they occur in normal roman text.
-
-=item code (CE<lt>E<gt>)
-
-Literal code should be in CE<lt>E<gt>. However metasyntactic placeholders
-should furthermore be nested in "italics" (actually, oblique) like
-CE<lt>IE<lt>E<gt>E<gt>. That way
-CE<lt>accept(IE<lt>NEWSOCKETE<gt>, E<lt>GENERICSOCKETE<gt>)E<gt>
-renders as C<accept(I<NEWSOCKET>, I<GENERICSOCKET>)>.
-
-=item files (FE<lt>E<gt>)
-
-Filenames, whether absolute or relative, are specified with the FE<lt>E<gt>
-markup. This will render as italics, but has other semantic connotations.
-
-=back
-
-References to other man pages should be in the form "manpage(section)" or
-"C<LE<lt>manpage(section)E<gt>>", and Pod::Man will automatically format
-those appropriately. Both will render as I<manpage>(section). 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 because not all systems
-place it in section 3, although that is the default. You may use
-C<LE<lt>Module::NameE<gt>> for module references instead, but this is
-optional because the translators are supposed to recognize module
-references in pod, just as they do variable references like $foo and such.
-
-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
-italics via IE<lt>E<gt>.
-
-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. The translators are
-supposed to translate all caps into small caps. 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 IE<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 email address (or some email 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,
-module names, function names, man page references, and the like unadorned
-by markup, and the POD translators will figure it all out for you. This
-makes it much easier to later edit the documentation. Note that many
-existing translators will do the wrong thing with email addresses when
-wrapped in LE<lt>E<gt>, so don't do that.
-
-You can check whether your documentation looks right by running
-
- % pod2text -o something.pod | less
-
-If you have I<groff> installed, you can get an even better look this way:
-
- % pod2man something.pod | groff -Tps -mandoc > something.ps
-
-Now view the resulting Postscript file to see whether everything checks out.
-
-=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
-<http://www.eyrie.org/~eagle/software/podlators/>.
-
-=head1 AUTHOR
-
-Russ Allbery <rra@stanford.edu>, 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 Russ Allbery
-<rra@stanford.edu>.
-
-This documentation is free software; you may redistribute it and/or modify
-it under the same terms as Perl itself.
-
-=cut