diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod | 338 |
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 |