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