| 1 | =head1 NAME |
| 2 | |
| 3 | perlpodstyle - Perl POD style guide |
| 4 | |
| 5 | =head1 DESCRIPTION |
| 6 | |
| 7 | These are general guidelines for how to write POD documentation for Perl |
| 8 | scripts and modules, based on general guidelines for writing good UNIX man |
| 9 | pages. All of these guidelines are, of course, optional, but following |
| 10 | them will make your documentation more consistent with other documentation |
| 11 | on the system. |
| 12 | |
| 13 | The name of the program being documented is conventionally written in bold |
| 14 | (using BE<lt>E<gt>) wherever it occurs, as are all program options. |
| 15 | Arguments should be written in italics (IE<lt>E<gt>). Function names are |
| 16 | traditionally written in italics; if you write a function as function(), |
| 17 | Pod::Man will take care of this for you. Literal code or commands should |
| 18 | be in CE<lt>E<gt>. References to other man pages should be in the form |
| 19 | C<manpage(section)> or C<LE<lt>manpage(section)E<gt>>, and Pod::Man will |
| 20 | automatically format those appropriately. The second form, with |
| 21 | LE<lt>E<gt>, is used to request that a POD formatter make a link to the |
| 22 | man page if possible. As an exception, one normally omits the section |
| 23 | when referring to module documentation since it's not clear what section |
| 24 | module documentation will be in; use C<LE<lt>Module::NameE<gt>> for module |
| 25 | references instead. |
| 26 | |
| 27 | References to other programs or functions are normally in the form of man |
| 28 | page references so that cross-referencing tools can provide the user with |
| 29 | links and the like. It's possible to overdo this, though, so be careful not |
| 30 | to clutter your documentation with too much markup. References to other |
| 31 | programs that are not given as man page references should be enclosed in |
| 32 | BE<lt>E<gt>. |
| 33 | |
| 34 | The major headers should be set out using a C<=head1> directive, and are |
| 35 | historically written in the rather startling ALL UPPER CASE format; this |
| 36 | is not mandatory, but it's strongly recommended so that sections have |
| 37 | consistent naming across different software packages. Minor headers may |
| 38 | be included using C<=head2>, and are typically in mixed case. |
| 39 | |
| 40 | The standard sections of a manual page are: |
| 41 | |
| 42 | =over 4 |
| 43 | |
| 44 | =item NAME |
| 45 | |
| 46 | Mandatory section; should be a comma-separated list of programs or |
| 47 | functions documented by this POD page, such as: |
| 48 | |
| 49 | foo, bar - programs to do something |
| 50 | |
| 51 | Manual page indexers are often extremely picky about the format of this |
| 52 | section, so don't put anything in it except this line. Every program or |
| 53 | function documented by this POD page should be listed, separated by a |
| 54 | comma and a space. For a Perl module, just give the module name. A |
| 55 | single dash, and only a single dash, should separate the list of programs |
| 56 | or functions from the description. Do not use any markup such as |
| 57 | CE<lt>E<gt> or BE<lt>E<gt> anywhere in this line. Functions should not be |
| 58 | qualified with C<()> or the like. The description should ideally fit on a |
| 59 | single line, even if a man program replaces the dash with a few tabs. |
| 60 | |
| 61 | =item SYNOPSIS |
| 62 | |
| 63 | A short usage summary for programs and functions. This section is |
| 64 | mandatory for section 3 pages. For Perl module documentation, it's |
| 65 | usually convenient to have the contents of this section be a verbatim |
| 66 | block showing some (brief) examples of typical ways the module is used. |
| 67 | |
| 68 | =item DESCRIPTION |
| 69 | |
| 70 | Extended description and discussion of the program or functions, or the |
| 71 | body of the documentation for man pages that document something else. If |
| 72 | particularly long, it's a good idea to break this up into subsections |
| 73 | C<=head2> directives like: |
| 74 | |
| 75 | =head2 Normal Usage |
| 76 | |
| 77 | =head2 Advanced Features |
| 78 | |
| 79 | =head2 Writing Configuration Files |
| 80 | |
| 81 | or whatever is appropriate for your documentation. |
| 82 | |
| 83 | For a module, this is generally where the documentation of the interfaces |
| 84 | provided by the module goes, usually in the form of a list with an |
| 85 | C<=item> for each interface. Depending on how many interfaces there are, |
| 86 | you may want to put that documentation in separate METHODS, FUNCTIONS, |
| 87 | CLASS METHODS, or INSTANCE METHODS sections instead and save the |
| 88 | DESCRIPTION section for an overview. |
| 89 | |
| 90 | =item OPTIONS |
| 91 | |
| 92 | Detailed description of each of the command-line options taken by the |
| 93 | program. This should be separate from the description for the use of |
| 94 | parsers like L<Pod::Usage>. This is normally presented as a list, with |
| 95 | each option as a separate C<=item>. The specific option string should be |
| 96 | enclosed in BE<lt>E<gt>. Any values that the option takes should be |
| 97 | enclosed in IE<lt>E<gt>. For example, the section for the option |
| 98 | B<--section>=I<manext> would be introduced with: |
| 99 | |
| 100 | =item B<--section>=I<manext> |
| 101 | |
| 102 | Synonymous options (like both the short and long forms) are separated by a |
| 103 | comma and a space on the same C<=item> line, or optionally listed as their |
| 104 | own item with a reference to the canonical name. For example, since |
| 105 | B<--section> can also be written as B<-s>, the above would be: |
| 106 | |
| 107 | =item B<-s> I<manext>, B<--section>=I<manext> |
| 108 | |
| 109 | Writing the short option first is recommended because it's easier to read. |
| 110 | The long option is long enough to draw the eye to it anyway and the short |
| 111 | option can otherwise get lost in visual noise. |
| 112 | |
| 113 | =item RETURN VALUE |
| 114 | |
| 115 | What the program or function returns, if successful. This section can be |
| 116 | omitted for programs whose precise exit codes aren't important, provided |
| 117 | they return 0 on success and non-zero on failure as is standard. It |
| 118 | should always be present for functions. For modules, it may be useful to |
| 119 | summarize return values from the module interface here, or it may be more |
| 120 | useful to discuss return values separately in the documentation of each |
| 121 | function or method the module provides. |
| 122 | |
| 123 | =item ERRORS |
| 124 | |
| 125 | Exceptions, error return codes, exit statuses, and errno settings. |
| 126 | Typically used for function or module documentation; program documentation |
| 127 | uses DIAGNOSTICS instead. The general rule of thumb is that errors |
| 128 | printed to C<STDOUT> or C<STDERR> and intended for the end user are |
| 129 | documented in DIAGNOSTICS while errors passed internal to the calling |
| 130 | program and intended for other programmers are documented in ERRORS. When |
| 131 | documenting a function that sets errno, a full list of the possible errno |
| 132 | values should be given here. |
| 133 | |
| 134 | =item DIAGNOSTICS |
| 135 | |
| 136 | All possible messages the program can print out and what they mean. You |
| 137 | may wish to follow the same documentation style as the Perl documentation; |
| 138 | see perldiag(1) for more details (and look at the POD source as well). |
| 139 | |
| 140 | If applicable, please include details on what the user should do to |
| 141 | correct the error; documenting an error as indicating "the input buffer is |
| 142 | too small" without telling the user how to increase the size of the input |
| 143 | buffer (or at least telling them that it isn't possible) aren't very |
| 144 | useful. |
| 145 | |
| 146 | =item EXAMPLES |
| 147 | |
| 148 | Give some example uses of the program or function. Don't skimp; users |
| 149 | often find this the most useful part of the documentation. The examples |
| 150 | are generally given as verbatim paragraphs. |
| 151 | |
| 152 | Don't just present an example without explaining what it does. Adding a |
| 153 | short paragraph saying what the example will do can increase the value of |
| 154 | the example immensely. |
| 155 | |
| 156 | =item ENVIRONMENT |
| 157 | |
| 158 | Environment variables that the program cares about, normally presented as |
| 159 | a list using C<=over>, C<=item>, and C<=back>. For example: |
| 160 | |
| 161 | =over 6 |
| 162 | |
| 163 | =item HOME |
| 164 | |
| 165 | Used to determine the user's home directory. F<.foorc> in this |
| 166 | directory is read for configuration details, if it exists. |
| 167 | |
| 168 | =back |
| 169 | |
| 170 | Since environment variables are normally in all uppercase, no additional |
| 171 | special formatting is generally needed; they're glaring enough as it is. |
| 172 | |
| 173 | =item FILES |
| 174 | |
| 175 | All files used by the program or function, normally presented as a list, |
| 176 | and what it uses them for. File names should be enclosed in FE<lt>E<gt>. |
| 177 | It's particularly important to document files that will be potentially |
| 178 | modified. |
| 179 | |
| 180 | =item CAVEATS |
| 181 | |
| 182 | Things to take special care with, sometimes called WARNINGS. |
| 183 | |
| 184 | =item BUGS |
| 185 | |
| 186 | Things that are broken or just don't work quite right. |
| 187 | |
| 188 | =item RESTRICTIONS |
| 189 | |
| 190 | Bugs you don't plan to fix. :-) |
| 191 | |
| 192 | =item NOTES |
| 193 | |
| 194 | Miscellaneous commentary. |
| 195 | |
| 196 | =item AUTHOR |
| 197 | |
| 198 | Who wrote it (use AUTHORS for multiple people). It's a good idea to |
| 199 | include your current e-mail address (or some e-mail address to which bug |
| 200 | reports should be sent) or some other contact information so that users |
| 201 | have a way of contacting you. Remember that program documentation tends |
| 202 | to roam the wild for far longer than you expect and pick a contact method |
| 203 | that's likely to last. |
| 204 | |
| 205 | =item HISTORY |
| 206 | |
| 207 | Programs derived from other sources sometimes have this. Some people keep |
| 208 | a modification log here, but that usually gets long and is normally better |
| 209 | maintained in a separate file. |
| 210 | |
| 211 | =item COPYRIGHT AND LICENSE |
| 212 | |
| 213 | For copyright |
| 214 | |
| 215 | Copyright YEAR(s) YOUR NAME(s) |
| 216 | |
| 217 | (No, (C) is not needed. No, "all rights reserved" is not needed.) |
| 218 | |
| 219 | For licensing the easiest way is to use the same licensing as Perl itself: |
| 220 | |
| 221 | This library is free software; you may redistribute it and/or modify |
| 222 | it under the same terms as Perl itself. |
| 223 | |
| 224 | This makes it easy for people to use your module with Perl. Note that |
| 225 | this licensing example is neither an endorsement or a requirement, you are |
| 226 | of course free to choose any licensing. |
| 227 | |
| 228 | =item SEE ALSO |
| 229 | |
| 230 | Other man pages to check out, like man(1), man(7), makewhatis(8), or |
| 231 | catman(8). Normally a simple list of man pages separated by commas, or a |
| 232 | paragraph giving the name of a reference work. Man page references, if |
| 233 | they use the standard C<name(section)> form, don't have to be enclosed in |
| 234 | LE<lt>E<gt> (although it's recommended), but other things in this section |
| 235 | probably should be when appropriate. |
| 236 | |
| 237 | If the package has a mailing list, include a URL or subscription |
| 238 | instructions here. |
| 239 | |
| 240 | If the package has a web site, include a URL here. |
| 241 | |
| 242 | =back |
| 243 | |
| 244 | Documentation of object-oriented libraries or modules may want to use |
| 245 | CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS |
| 246 | sections, for detailed documentation of the parts of the library and save |
| 247 | the DESCRIPTION section for an overview. Large modules with a function |
| 248 | interface may want to use FUNCTIONS for similar reasons. Some people use |
| 249 | OVERVIEW to summarize the description if it's quite long. |
| 250 | |
| 251 | Section ordering varies, although NAME must always be the first section |
| 252 | (you'll break some man page systems otherwise), and NAME, SYNOPSIS, |
| 253 | DESCRIPTION, and OPTIONS generally always occur first and in that order if |
| 254 | present. In general, SEE ALSO, AUTHOR, and similar material should be |
| 255 | left for last. Some systems also move WARNINGS and NOTES to last. The |
| 256 | order given above should be reasonable for most purposes. |
| 257 | |
| 258 | Some systems use CONFORMING TO to note conformance to relevant standards |
| 259 | and MT-LEVEL to note safeness for use in threaded programs or signal |
| 260 | handlers. These headings are primarily useful when documenting parts of a |
| 261 | C library. |
| 262 | |
| 263 | Finally, as a general note, try not to use an excessive amount of markup. |
| 264 | As documented here and in L<Pod::Man>, you can safely leave Perl |
| 265 | variables, function names, man page references, and the like unadorned by |
| 266 | markup and the POD translators will figure it out for you. This makes it |
| 267 | much easier to later edit the documentation. Note that many existing |
| 268 | translators will do the wrong thing with e-mail addresses when wrapped in |
| 269 | LE<lt>E<gt>, so don't do that. |
| 270 | |
| 271 | =head1 SEE ALSO |
| 272 | |
| 273 | For additional information that may be more accurate for your specific |
| 274 | system, see either L<man(5)> or L<man(7)> depending on your system manual |
| 275 | section numbering conventions. |
| 276 | |
| 277 | This documentation is maintained as part of the podlators distribution. |
| 278 | The current version is always available from its web site at |
| 279 | <http://www.eyrie.org/~eagle/software/podlators/>. |
| 280 | |
| 281 | =head1 AUTHOR |
| 282 | |
| 283 | Russ Allbery <rra@stanford.edu>, with large portions of this documentation |
| 284 | taken from the documentation of the original B<pod2man> implementation by |
| 285 | Larry Wall and Tom Christiansen. |
| 286 | |
| 287 | =head1 COPYRIGHT AND LICENSE |
| 288 | |
| 289 | Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery |
| 290 | <rra@stanford.edu>. |
| 291 | |
| 292 | This documentation is free software; you may redistribute it and/or modify |
| 293 | it under the same terms as Perl itself. |
| 294 | |
| 295 | =cut |