diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlpodstyle.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlpodstyle.1 | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlpodstyle.1 b/upstream/mageia-cauldron/man1/perlpodstyle.1 new file mode 100644 index 00000000..eb054a6f --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlpodstyle.1 @@ -0,0 +1,346 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLPODSTYLE 1" +.TH PERLPODSTYLE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlpodstyle \- Perl POD style guide +.SH DESCRIPTION +.IX Header "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. +.PP +The name of the program being documented is conventionally written in bold +(using B<>) wherever it occurs, as are all program options. +Arguments should be written in italics (I<>). Function names are +traditionally written in italics; if you write a function as \fBfunction()\fR, +Pod::Man will take care of this for you. Literal code or commands should +be in C<>. References to other man pages should be in the form +\&\f(CWmanpage(section)\fR or \f(CW\*(C`L<manpage(section)>\*(C'\fR, and Pod::Man will +automatically format those appropriately. The second form, with +L<>, 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 \f(CW\*(C`L<Module::Name>\*(C'\fR for module +references instead. +.PP +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 +B<>. +.PP +The major headers should be set out using a \f(CW\*(C`=head1\*(C'\fR 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 \f(CW\*(C`=head2\*(C'\fR, and are typically in mixed case. +.PP +The standard sections of a manual page are: +.IP NAME 4 +.IX Item "NAME" +Mandatory section; should be a comma-separated list of programs or +functions documented by this POD page, such as: +.Sp +.Vb 1 +\& foo, bar \- programs to do something +.Ve +.Sp +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 +C<> or B<> anywhere in this line. Functions should not be +qualified with \f(CW\*(C`()\*(C'\fR or the like. The description should ideally fit on a +single line, even if a man program replaces the dash with a few tabs. +.IP SYNOPSIS 4 +.IX 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. +.IP DESCRIPTION 4 +.IX 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 +\&\f(CW\*(C`=head2\*(C'\fR directives like: +.Sp +.Vb 1 +\& =head2 Normal Usage +\& +\& =head2 Advanced Features +\& +\& =head2 Writing Configuration Files +.Ve +.Sp +or whatever is appropriate for your documentation. +.Sp +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 +\&\f(CW\*(C`=item\*(C'\fR 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. +.IP OPTIONS 4 +.IX 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 Pod::Usage. This is normally presented as a list, with +each option as a separate \f(CW\*(C`=item\*(C'\fR. The specific option string should be +enclosed in B<>. Any values that the option takes should be +enclosed in I<>. For example, the section for the option +\&\fB\-\-section\fR=\fImanext\fR would be introduced with: +.Sp +.Vb 1 +\& =item B<\-\-section>=I<manext> +.Ve +.Sp +Synonymous options (like both the short and long forms) are separated by a +comma and a space on the same \f(CW\*(C`=item\*(C'\fR line, or optionally listed as their +own item with a reference to the canonical name. For example, since +\&\fB\-\-section\fR can also be written as \fB\-s\fR, the above would be: +.Sp +.Vb 1 +\& =item B<\-s> I<manext>, B<\-\-section>=I<manext> +.Ve +.Sp +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. +.IP "RETURN VALUE" 4 +.IX 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. +.IP ERRORS 4 +.IX 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 \f(CW\*(C`STDOUT\*(C'\fR or \f(CW\*(C`STDERR\*(C'\fR 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. +.IP DIAGNOSTICS 4 +.IX 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 \fBperldiag\fR\|(1) for more details (and look at the POD source as well). +.Sp +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. +.IP EXAMPLES 4 +.IX 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. +.Sp +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. +.IP ENVIRONMENT 4 +.IX Item "ENVIRONMENT" +Environment variables that the program cares about, normally presented as +a list using \f(CW\*(C`=over\*(C'\fR, \f(CW\*(C`=item\*(C'\fR, and \f(CW\*(C`=back\*(C'\fR. For example: +.Sp +.Vb 1 +\& =over 6 +\& +\& =item HOME +\& +\& Used to determine the user\*(Aqs home directory. F<.foorc> in this +\& directory is read for configuration details, if it exists. +\& +\& =back +.Ve +.Sp +Since environment variables are normally in all uppercase, no additional +special formatting is generally needed; they're glaring enough as it is. +.IP FILES 4 +.IX 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 F<>. +It's particularly important to document files that will be potentially +modified. +.IP CAVEATS 4 +.IX Item "CAVEATS" +Things to take special care with, sometimes called WARNINGS. +.IP BUGS 4 +.IX Item "BUGS" +Things that are broken or just don't work quite right. +.IP RESTRICTIONS 4 +.IX Item "RESTRICTIONS" +Bugs you don't plan to fix. :\-) +.IP NOTES 4 +.IX Item "NOTES" +Miscellaneous commentary. +.IP AUTHOR 4 +.IX 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. +.IP HISTORY 4 +.IX 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. +.IP "COPYRIGHT AND LICENSE" 4 +.IX Item "COPYRIGHT AND LICENSE" +For copyright +.Sp +.Vb 1 +\& Copyright YEAR(s) YOUR NAME(s) +.Ve +.Sp +(No, (C) is not needed. No, "all rights reserved" is not needed.) +.Sp +For licensing the easiest way is to use the same licensing as Perl itself: +.Sp +.Vb 2 +\& This library is free software; you may redistribute it and/or +\& modify it under the same terms as Perl itself. +.Ve +.Sp +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. +.IP "SEE ALSO" 4 +.IX Item "SEE ALSO" +Other man pages to check out, like \fBman\fR\|(1), \fBman\fR\|(7), \fBmakewhatis\fR\|(8), or +\&\fBcatman\fR\|(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 \f(CWname(section)\fR form, don't have to be enclosed in +L<> (although it's recommended), but other things in this section +probably should be when appropriate. +.Sp +If the package has a mailing list, include a URL or subscription +instructions here. +.Sp +If the package has a web site, include a URL here. +.PP +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. +.PP +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. +.PP +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. +.PP +Finally, as a general note, try not to use an excessive amount of markup. +As documented here and in 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 +L<>, so don't do that. +.SH AUTHOR +.IX Header "AUTHOR" +Russ Allbery <rra@cpan.org>, with large portions of this documentation +taken from the documentation of the original \fBpod2man\fR implementation by +Larry Wall and Tom Christiansen. +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015, 2018 Russ +Allbery <rra@cpan.org> +.PP +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. +.PP +SPDX-License-Identifier: FSFAP +.SH "SEE ALSO" +.IX Header "SEE ALSO" +For additional information that may be more accurate for your specific +system, see either \fBman\fR\|(5) or \fBman\fR\|(7) depending on your system manual +section numbering conventions. +.PP +This documentation is maintained as part of the podlators distribution. +The current version is always available from its web site at +<https://www.eyrie.org/~eagle/software/podlators/>. |