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
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 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
28 traditionally written in italics; if you write a function as function(),
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.
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
64 italics via IE<lt>E<gt>.
65
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.
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
90 CE<lt>E<gt> or IE<lt>E<gt> anywhere in this line.  Functions should not be
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
232 include your current email address (or some email address to which bug
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.
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.
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