Commit | Line | Data |
---|---|---|
463da0ac CBW |
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 | |
71741524 | 8 | scripts and modules, based on general guidelines for writing good UNIX man |
463da0ac CBW |
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 | ||
71741524 CBW |
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 | |
e001c712 | 16 | traditionally written in italics; if you write a function as function(), |
71741524 CBW |
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. | |
463da0ac CBW |
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 | |
71741524 | 32 | BE<lt>E<gt>. |
463da0ac | 33 | |
71741524 CBW |
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. | |
463da0ac CBW |
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 | |
71741524 | 57 | CE<lt>E<gt> or BE<lt>E<gt> anywhere in this line. Functions should not be |
463da0ac CBW |
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 | |
71741524 | 199 | include your current e-mail address (or some e-mail address to which bug |
463da0ac CBW |
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 | ||
555bd962 BG |
221 | This library is free software; you may redistribute it and/or |
222 | modify it under the same terms as Perl itself. | |
463da0ac CBW |
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. | |
71741524 CBW |
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. | |
463da0ac | 270 | |
463da0ac CBW |
271 | =head1 AUTHOR |
272 | ||
cb21ff46 | 273 | Russ Allbery <rra@cpan.org>, with large portions of this documentation |
463da0ac CBW |
274 | taken from the documentation of the original B<pod2man> implementation by |
275 | Larry Wall and Tom Christiansen. | |
276 | ||
277 | =head1 COPYRIGHT AND LICENSE | |
278 | ||
f97008e2 SH |
279 | Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015, 2018 Russ |
280 | Allbery <rra@cpan.org> | |
463da0ac | 281 | |
cb21ff46 KE |
282 | Copying and distribution of this file, with or without modification, are |
283 | permitted in any medium without royalty provided the copyright notice and | |
284 | this notice are preserved. This file is offered as-is, without any | |
285 | warranty. | |
463da0ac | 286 | |
f97008e2 SH |
287 | SPDX-License-Identifier: FSFAP |
288 | ||
289 | =head1 SEE ALSO | |
290 | ||
291 | For additional information that may be more accurate for your specific | |
292 | system, see either L<man(5)> or L<man(7)> depending on your system manual | |
293 | section numbering conventions. | |
294 | ||
295 | This documentation is maintained as part of the podlators distribution. | |
296 | The current version is always available from its web site at | |
297 | L<https://www.eyrie.org/~eagle/software/podlators/>. | |
298 | ||
463da0ac | 299 | =cut |