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