Debian Codegraph @

upstream/mageia-cauldron/man1/perldocstyle.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLDOCSTYLE 1"
61 .TH PERLDOCSTYLE 1 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perldocstyle \- A style guide for writing Perl\*(Aqs documentation
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This document is a guide for the authorship and maintenance of the
71 documentation that ships with Perl. This includes the following:
72 .IP \(bu 4
73 The several dozen manual sections whose filenames begin with "\f(CW\*(C`perl\*(C'\fR",
74 such as \f(CW\*(C`perlobj\*(C'\fR, \f(CW\*(C`perlre\*(C'\fR, and \f(CW\*(C`perlintro\*(C'\fR. (And, yes, \f(CW\*(C`perl\*(C'\fR.)
75 .IP \(bu 4
76 The documentation for all the modules included with Perl (as listed by
77 \&\f(CW\*(C`perlmodlib\*(C'\fR).
78 .IP \(bu 4
79 The hundreds of individually presented reference sections derived from
80 the \f(CW\*(C`perlfunc\*(C'\fR file.
81 .PP
82 This guide will hereafter refer to user\-manual section files as \fIman
83 pages\fR, per Unix convention.
84 .SS "Purpose of this guide"
85 .IX Subsection "Purpose of this guide"
86 This style guide aims to establish standards, procedures, and philosophies
87 applicable to Perl\*(Aqs core documentation.
88 .PP
89 Adherence to these standards will help ensure that any one part of
90 Perl\*(Aqs manual has a tone and style consistent with that of any other. As
91 with the rest of the Perl project, the language\*(Aqs documentation
92 collection is an open\-source project authored over a long period of time
93 by many people. Maintaining consistency across such a wide swath of work
94 presents a challenge; this guide provides a foundation to help mitigate
95 this difficulty.
96 .PP
97 This will help its readers\-\-especially those new to Perl\-\-to feel
98 more welcome and engaged with Perl\*(Aqs documentation, and this in turn
99 will help the Perl project itself grow stronger through having a larger,
100 more diverse, and more confident population of knowledgeable users.
101 .SS "Intended audience"
102 .IX Subsection "Intended audience"
103 Anyone interested in contributing to Perl\*(Aqs core documentation should
104 familiarize themselves with the standards outlined by this guide.
105 .PP
106 Programmers documenting their own work apart from the Perl project
107 itself may also find this guide worthwhile, especially if they wish
108 their work to extend the tone and style of Perl\*(Aqs own manual.
109 .SS "Status of this document"
110 .IX Subsection "Status of this document"
111 This guide was initially drafted in late 2020, drawing from the
112 documentation style guides of several open\-source technologies
113 contemporary with Perl. This has included Python, Raku, Rust, and the
114 Linux kernel.
115 .PP
116 The author intends to see this guide used as starting place from
117 which to launch a review of Perl\*(Aqs reams of extant documentation, with
118 the expectation that those conducting this review should grow and modify
119 this guide as needed to account for the requirements and quirks
120 particular to Perl\*(Aqs programming manual.
121 .SH FUNDAMENTALS
122 .IX Header "FUNDAMENTALS"
123 .SS "Choice of markup: Pod"
124 .IX Subsection "Choice of markup: Pod"
125 All of Perl\*(Aqs core documentation uses Pod ("Plain Old Documentation"), a
126 simple markup language, to format its source text. Pod is similar in
127 spirit to other contemporary lightweight markup technologies, such as
128 Markdown and reStructuredText, and has a decades\-long shared history
129 with Perl itself.
130 .PP
131 For a comprehensive reference to Pod syntax, see \f(CW\*(C`perlpod\*(C'\fR.
132 For the sake of reading this guide, familiarity with the Pod syntax for
133 section headers (\f(CW\*(C`=head2\*(C'\fR, et cetera) and for inline text formatting
134 (\f(CW\*(C`C<like this>\*(C'\fR) should suffice.
135 .PP
136 Perl programmers also use Pod to document their own scripts, libraries,
137 and modules. This use of Pod has its own style guide, outlined by
138 \&\f(CW\*(C`perlpodstyle\*(C'\fR.
139 .SS "Choice of language: American English"
140 .IX Subsection "Choice of language: American English"
141 Perl\*(Aqs core documentation is written in English, with a preference for
142 American spelling of words and expression of phrases. That means "color"
143 over "colour", "math" versus "maths", "the team has decided" and not
144 "the team have decided", and so on.
145 .PP
146 We name one style of English for the sake of consistency across Perl\*(Aqs
147 documentation, much as a software project might declare a four\-space
148 indentation standard\-\-even when that doesn\*(Aqt affect how well the code
149 compiles. Both efforts result in an easier read by avoiding jarring,
150 mid\-document changes in format or style.
151 .PP
152 Contributors to Perl\*(Aqs documentation should note that this rule
153 describes the ultimate, published output of the project, and does not
154 prescribe the dialect used within community contributions. The
155 documentation team enthusiastically welcomes any English\-language
156 contributions, and will actively assist in Americanizing spelling and
157 style when warranted.
158 .PP
159 \fIOther languages and translations\fR
160 .IX Subsection "Other languages and translations"
161 .PP
162 Community\-authored translations of Perl\*(Aqs documentation do exist,
163 covering a variety of languages. While the Perl project appreciates
164 these translation efforts and promotes them when applicable, it does not
165 officially support or maintain any of them.
166 .PP
167 That said, keeping Perl\*(Aqs documentation clear, simple, and short has a
168 welcome side effect of aiding any such translation project.
169 .PP
170 (Note that the Chinese, Japanese, and Korean\-language README files
171 included with Perl\*(Aqs source distributions provide an exception to this
172 choice of language\-\-but these documents fall outside the scope of this
173 guide.)
174 .SS "Choice of encoding: UTF\-8"
175 .IX Subsection "Choice of encoding: UTF-8"
176 Perl\*(Aqs core documentation files are encoded in UTF\-8, and can make use
177 of the full range of characters this encoding allows.
178 .PP
179 As such, every core doc file (or the Pod section of every core module)
180 should commence with an \f(CW\*(C`=encoding utf8\*(C'\fR declaration.
181 .SS "Choice of underlying style guide: CMOS"
182 .IX Subsection "Choice of underlying style guide: CMOS"
183 Perl\*(Aqs documentation uses the Chicago Manual of
184 Style <https://www.chicagomanualofstyle.org> (CMOS), 17th Edition, as
185 its baseline guide for style and grammar. While the document you are
186 currently reading endeavors to serve as an adequate stand\-alone style guide
187 for the purposes of documenting Perl, authors should consider CMOS the
188 fallback authority for any pertinent topics not covered here.
189 .PP
190 Because CMOS is not a free resource, access to it is not a prerequisite
191 for contributing to Perl\*(Aqs documentation; the doc team will help
192 contributors learn about and apply its guidelines as needed. However, we
193 do encourage anyone interested in significant doc contributions to
194 obtain or at least read through CMOS. (Copies are likely available
195 through most public libraries, and CMOS\-derived fundamentals can be
196 found online as well.)
197 .SS "Contributing to Perl\*(Aqs documentation"
198 .IX Subsection "Contributing to Perl's documentation"
199 Perl, like any programming language, is only as good as its
200 documentation. Perl depends upon clear, friendly, and thorough
201 documentation in order to welcome brand\-new users, teach and explain the
202 language\*(Aqs various concepts and components, and serve as a lifelong
203 reference for experienced Perl programmers. As such, the Perl project
204 welcomes and values all community efforts to improve the language\*(Aqs
205 documentation.
206 .PP
207 Perl accepts documentation contributions through the same open\-source
208 project pipeline as code contributions. See \f(CW\*(C`perlhack\*(C'\fR for
209 more information.
210 .SH "FORMATTING AND STRUCTURE"
211 .IX Header "FORMATTING AND STRUCTURE"
212 This section details specific Pod syntax and style that all core Perl
213 documentation should adhere to, in the interest of consistency and
214 readability.
215 .SS "Document structure"
216 .IX Subsection "Document structure"
217 Each individual work of core Perl documentation, whether contained
218 within a \f(CW\*(C`.pod\*(C'\fR file or in the Pod section of a standard code module,
219 patterns its structure after a number of long\-time Unix man page
220 conventions. (Hence this guide\*(Aqs use of "man page" to refer to any one
221 self\-contained part of Perl\*(Aqs documentation.)
222 .PP
223 Adhering to these conventions helps Pod formatters present a Perl man
224 page\*(Aqs content in different contexts\-\-whether a terminal, the web, or
225 even print. Many of the following requirements originate with
226 \&\f(CW\*(C`perlpodstyle\*(C'\fR, which derives its recommendations in
227 turn from these well\-established practices.
228 .PP
229 \fIName\fR
230 .IX Subsection "Name"
231 .PP
232 After its \f(CW\*(C`=encoding utf8\*(C'\fR declaration, a
233 Perl man page \fImust\fR present a level\-one header named "NAME" (literally),
234 followed by a paragraph containing the page\*(Aqs name and a very brief
235 description.
236 .PP
237 The first few lines of a notional page named \f(CW\*(C`perlpodexample\*(C'\fR:
238 .PP
239 .Vb 1
240 \& =encoding utf8
241 \&
242 \& =head1 NAME
243 \&
244 \& perlpodexample \- An example of formatting a manual page\*(Aqs title line
245 .Ve
246 .PP
247 \fIDescription and synopsis\fR
248 .IX Subsection "Description and synopsis"
249 .PP
250 Most Perl man pages also contain a DESCRIPTION section featuring a
251 summary of, or introduction to, the document\*(Aqs content and purpose.
252 .PP
253 This section should also, one way or another, clearly identify the
254 audience that the page addresses, especially if it has expectations
255 about the reader\*(Aqs prior knowledge. For example, a man page that dives
256 deep into the inner workings of Perl\*(Aqs regular expression engine should
257 state its assumptions up front\-\-and quickly redirect readers who are
258 instead looking for a more basic reference or tutorial.
259 .PP
260 Reference pages, when appropriate, can precede the DESCRIPTION with a
261 SYNOPSIS section that lists, within one or more code blocks, some very
262 brief examples of the referenced feature\*(Aqs use. This section should show
263 a handful of common\-case and best\-practice examples, rather than an
264 exhaustive list of every obscure method or alternate syntax available.
265 .PP
266 \fIOther sections and subsections\fR
267 .IX Subsection "Other sections and subsections"
268 .PP
269 Pages should conclude, when appropriate, with a SEE ALSO section
270 containing hyperlinks to relevant sections of Perl\*(Aqs manual, other Unix
271 man pages, or appropriate web pages. Hyperlink each such cross\-reference via
272 \&\f(CW\*(C`L<...>\*(C'\fR.
273 .PP
274 What other sections to include depends entirely upon the topic at hand.
275 Authors should feel free to include further \f(CW\*(C`=head1\*(C'\fR\-level sections,
276 whether other standard ones listed by \f(CW\*(C`perlpodstyle\*(C'\fR, or ones specific
277 to the page\*(Aqs topic; in either case, render these top\-level headings in
278 all\-capital letters.
279 .PP
280 You may then include as many subsections beneath them as needed to meet
281 the standards of clarity, accessibility, and cross\-reference affinity
282 suggested elsewhere in this guide.
283 .PP
284 \fIAuthor and copyright\fR
285 .IX Subsection "Author and copyright"
286 .PP
287 In most circumstances, Perl\*(Aqs stand\-alone man pages\-\-those contained
288 within \f(CW\*(C`.pod\*(C'\fR files\-\-do not need to include any copyright or license
289 information about themselves. Their source Pod files are part of Perl\*(Aqs
290 own core software repository, and that already covers them under the
291 same copyright and license terms as Perl itself. You do not need to
292 include additional "LICENSE" or "COPYRIGHT" sections of your own.
293 .PP
294 These man pages may optionally credit their primary author, or include a
295 list of significant contributors, under "AUTHOR" or "CONTRIBUTORS"
296 headings. Note that the presence of authors\*(Aq names does not preclude a
297 given page from writing in a voice consistent with the rest of Perl\*(Aqs
298 documentation.
299 .PP
300 Note that these guidelines do not apply to the core software modules
301 that ship with Perl. These have their own standards for authorship and
302 copyright statements, as found in \f(CW\*(C`perlpodstyle\*(C'\fR.
303 .SS "Formatting rules"
304 .IX Subsection "Formatting rules"
305 \fILine length and line wrap\fR
306 .IX Subsection "Line length and line wrap"
307 .PP
308 Each line within a Perl man page\*(Aqs Pod source file should measure 72
309 characters or fewer in length.
310 .PP
311 Please break paragraphs up into blocks of short lines, rather than
312 "soft wrapping" paragraphs across hundreds of characters with no line
313 breaks.
314 .PP
315 \fICode blocks\fR
316 .IX Subsection "Code blocks"
317 .PP
318 Just like the text around them, all code examples should be as short and
319 readable as possible, displaying no more complexity than absolutely
320 necessary to illustrate the concept at hand.
321 .PP
322 For the sake of consistency within and across Perl\*(Aqs man pages, all
323 examples must adhere to the code\-layout principles set out by
324 \&\f(CW\*(C`perlstyle\*(C'\fR.
325 .PP
326 Sample code should deviate from these standards only when necessary:
327 during a demonstration of how Perl disregards whitespace, for example,
328 or to temporarily switch to two\-column indentation for an unavoidably
329 verbose illustration.
330 .PP
331 You may include comments within example code to further clarify or label
332 the code\*(Aqs behavior in\-line. You may also use comments as placeholder
333 for code normally present but not relevant to the current topic, like
334 so:
335 .PP
336 .Vb 5
337 \& while (my $line = <$fh>) {
338 \& #
339 \& # (Do something interesting with $line here.)
340 \& #
341 \& }
342 .Ve
343 .PP
344 Even the simplest code blocks often require the use of example
345 variables and subroutines, whose names you should choose with
346 care.
347 .PP
348 \fIInline code and literals\fR
349 .IX Subsection "Inline code and literals"
350 .PP
351 Within a paragraph of text, use \f(CW\*(C`C<...>\*(C'\fR when quoting or
352 referring to any bit of Perl code\-\-even if it is only one character
353 long.
354 .PP
355 For instance, when referring within an explanatory paragraph to Perl\*(Aqs
356 operator for adding two numbers together, you\*(Aqd write "\f(CW\*(C`C<+>\*(C'\fR".
357 .PP
358 \fIFunction names\fR
359 .IX Subsection "Function names"
360 .PP
361 Use \f(CW\*(C`C<...>\*(C'\fR to render all Perl function names in monospace,
362 whenever they appear in text.
363 .PP
364 Unless you need to specifically quote a function call with a list of
365 arguments, do not follow a function\*(Aqs name in text with a pair of empty
366 parentheses. That is, when referring in general to Perl\*(Aqs \f(CW\*(C`print\*(C'\fR
367 function, write it as "\f(CW\*(C`print\*(C'\fR", not "\f(CWprint()\fR".
368 .PP
369 \fIFunction arguments\fR
370 .IX Subsection "Function arguments"
371 .PP
372 Represent functions\*(Aq expected arguments in all\-caps, with no sigils, and
373 using \f(CW\*(C`C<...>\*(C'\fR to render them in monospace. These arguments
374 should have short names making their nature and purpose clear.
375 Convention specifies a few ones commonly seen throughout Perl\*(Aqs
376 documentation:
377 .IP \(bu 4
378 EXPR
379 .Sp
380 The "generic" argument: any scalar value, or a Perl expression that
381 evaluates to one.
382 .IP \(bu 4
383 ARRAY
384 .Sp
385 An array, stored in a named variable.
386 .IP \(bu 4
387 HASH
388 .Sp
389 A hash, stored in a named variable.
390 .IP \(bu 4
391 BLOCK
392 .Sp
393 A curly\-braced code block, or a subroutine reference.
394 .IP \(bu 4
395 LIST
396 .Sp
397 Any number of values, stored across any number of variables or
398 expressions, which the function will "flatten" and treat as a single
399 list. (And because it can contain any number of variables, it must be
400 the \fIlast\fR argument, when present.)
401 .PP
402 When possible, give scalar arguments names that suggest their purpose
403 among the arguments. See, for example, \f(CW\*(C`substr\*(C'\fR\*(Aqs
404 documentation, whose
405 listed arguments include \f(CW\*(C`EXPR\*(C'\fR, \f(CW\*(C`OFFSET\*(C'\fR, \f(CW\*(C`LENGTH\*(C'\fR, and \f(CW\*(C`REPLACEMENT\*(C'\fR.
406 .PP
407 \fIApostrophes, quotes, and dashes\fR
408 .IX Subsection "Apostrophes, quotes, and dashes"
409 .PP
410 In Pod source, use straight quotes, and not "curly quotes": "Like
411 this", not “like this”. The same goes for apostrophes: Here\*(Aqs a
412 positive example, and here’s a negative one.
413 .PP
414 Render em dashes as two hyphens\-\-like this:
415 .PP
416 .Vb 1
417 \& Render em dashes as two hyphens\-\-like this.
418 .Ve
419 .PP
420 Leave it up to formatters to reformat and reshape these punctuation
421 marks as best fits their respective target media.
422 .PP
423 \fIUnix programs and C functions\fR
424 .IX Subsection "Unix programs and C functions"
425 .PP
426 When referring to a Unix program or C function with its own man page
427 (outside of Perl\*(Aqs documentation), include its manual section number in
428 parentheses. For example: \f(CWmalloc(3)\fR, or \f(CWmkdir(1)\fR.
429 .PP
430 If mentioning this program for the first time within a man page or
431 section, make it a cross reference, e.g. \f(CW\*(C`L<malloc(3)>\*(C'\fR.
432 .PP
433 Do not otherwise style this text.
434 .PP
435 \fICross\-references and hyperlinks\fR
436 .IX Subsection "Cross-references and hyperlinks"
437 .PP
438 Make generous use of Pod\*(Aqs \f(CW\*(C`L<...>\*(C'\fR syntax to create hyperlinks
439 to other parts of the current man page, or to other documents entirely
440 \&\-\- whether elsewhere on the reader\*(Aqs computer, or somewhere on the
441 internet, via URL.
442 .PP
443 Use \f(CW\*(C`L<...>\*(C'\fR to link to another section of the current man page
444 when mentioning it, and make use of its page\-and\-section syntax to link to
445 the most specific section of a separate page within Perl\*(Aqs
446 documentation. Generally, the first time you refer to a specific
447 function, program, or concept within a certain page or section, consider
448 linking to its full documentation.
449 .PP
450 Hyperlinks do not supersede other formatting required by this guide; Pod
451 allows nested text formats, and you should use this feature as needed.
452 .PP
453 Here is an example sentence that mentions Perl\*(Aqs \f(CW\*(C`say\*(C'\fR function, with a
454 link to its documentation section within the \f(CW\*(C`perlfunc\*(C'\fR man page:
455 .PP
456 .Vb 2
457 \& In version 5.10, Perl added support for the
458 \& L<C<say>|perlfunc/say FILEHANDLE LIST> function.
459 .Ve
460 .PP
461 Note the use of the vertical pipe ("\f(CW\*(C`|\*(C'\fR") to separate how the link will
462 appear to readers ("\f(CW\*(C`C<say>\*(C'\fR") from the full page\-and\-section specifier
463 that the formatter links to.
464 .PP
465 \fITables and diagrams\fR
466 .IX Subsection "Tables and diagrams"
467 .PP
468 Pod does not officially support tables. To best present tabular data,
469 include the table as both HTML and plain\-text representations\-\-the
470 latter as an indented code block. Use \f(CW\*(C`=begin\*(C'\fR / \f(CW\*(C`=end\*(C'\fR directives to
471 target these tables at \f(CW\*(C`html\*(C'\fR and \f(CW\*(C`text\*(C'\fR Pod formatters, respectively.
472 For example:
473 .PP
474 .Vb 1
475 \& =head2 Table of fruits
476 \&
477 \& =begin text
478 \&
479 \& Name Shape Color
480 \& =====================================
481 \& Apple Round Red
482 \& Banana Long Yellow
483 \& Pear Pear\-shaped Green
484 \&
485 \& =end text
486 \&
487 \& =begin html
488 \&
489 \& <table>
490 \& <tr><th>Name</th><th>Shape</th><th>Color</th></tr>
491 \& <tr><td>Apple</td><td>Round</td><td>Red</td></tr>
492 \& <tr><td>Banana</td><td>Long</td><td>Yellow</td></tr>
493 \& <tr><td>Pear</td><td>Pear\-shaped</td><td>Green</td></tr>
494 \& </table>
495 \&
496 \& =end html
497 .Ve
498 .PP
499 The same holds true for figures and graphical illustrations. Pod does
500 not natively support inline graphics, but you can mix HTML \f(CW\*(C`<img>\*(C'\fR tags
501 with monospaced text\-art representations of those images\*(Aq content.
502 .PP
503 Due in part to these limitations, most Perl man pages use neither tables
504 nor diagrams. Like any other tool in your documentation toolkit,
505 however, you may consider their inclusion when they would improve an
506 explanation\*(Aqs clarity without adding to its complexity.
507 .SS "Adding comments"
508 .IX Subsection "Adding comments"
509 Like any other kind of source code, Pod lets you insert comments visible
510 only to other people reading the source directly, and ignored by the
511 formatting programs that transform Pod into various human\-friendly
512 output formats (such as HTML or PDF).
513 .PP
514 To comment Pod text, use the \f(CW\*(C`=for\*(C'\fR and \f(CW\*(C`=begin\*(C'\fR / \f(CW\*(C`=end\*(C'\fR Pod
515 directives, aiming them at a (notional) formatter called "\f(CW\*(C`comment\*(C'\fR". A
516 couple of examples:
517 .PP
518 .Vb 2
519 \& =for comment Using "=for comment" like this is good for short,
520 \& single\-paragraph comments.
521 \&
522 \& =begin comment
523 \&
524 \& If you need to comment out more than one paragraph, use a
525 \& =begin/=end block, like this.
526 \&
527 \& None of the text or markup in this whole example would be visible to
528 \& someone reading the documentation through normal means, so it\*(Aqs
529 \& great for leaving notes, explanations, or suggestions for your
530 \& fellow documentation writers.
531 \&
532 \& =end comment
533 .Ve
534 .PP
535 In the tradition of any good open\-source project, you should make free
536 but judicious use of comments to leave in\-line "meta\-documentation" as
537 needed for other Perl documentation writers (including your future
538 self).
539 .SS "Perlfunc has special rules"
540 .IX Subsection "Perlfunc has special rules"
541 The \f(CW\*(C`perlfunc\*(C'\fR man page, an exhaustive reference of every
542 Perl built\-in function, has a handful of formatting rules not seen
543 elsewhere in Perl\*(Aqs documentation.
544 .PP
545 Software used during Perl\*(Aqs build process
546 (Pod::Functions) parses this page according to certain
547 rules, in order to build separate man pages for each of Perl\*(Aqs
548 functions, as well as achieve other indexing effects. As such,
549 contributors to perlfunc must know about and adhere to its particular
550 rules.
551 .PP
552 Most of the perfunc man page comprises a single list, found under the
553 header "Alphabetical Listing of Perl Functions". Each function reference is an entry on that
554 list, made of three parts, in order:
555 .IP 1. 4
556 A list of \f(CW\*(C`=item\*(C'\fR lines which each demonstrate, in template format, a
557 way to call this function. One line should exist for every combination
558 of arguments that the function accepts (including no arguments at all,
559 if applicable).
560 .Sp
561 If modern best practices prefer certain ways to invoke the function
562 over others, then those ways should lead the list.
563 .Sp
564 The first item of the list should be immediately followed by one or
565 more \f(CW\*(C`X<...>\*(C'\fR terms listing index\-worthy topics; if nothing
566 else, then the name of the function, with no arguments.
567 .IP 2. 4
568 A \f(CW\*(C`=for\*(C'\fR line, directed at \f(CW\*(C`Pod::Functions\*(C'\fR, containing a one\-line
569 description of what the function does. This is written as a phrase, led
570 with an imperative verb, with neither leading capitalization nor ending
571 punctuation. Examples include "quote a list of words" and "change a
572 filename".
573 .IP 3. 4
574 The function\*(Aqs definition and reference material, including all
575 explanatory text and code examples.
576 .PP
577 Complex functions that need their text divided into subsections (under
578 the principles of "Apply section\-breaks and examples
579 generously") may do so by
580 using sublists, with \f(CW\*(C`=item\*(C'\fR elements as header text.
581 .PP
582 A fictional function "\f(CW\*(C`myfunc\*(C'\fR", which takes a list as an optional
583 argument, might have an entry in perlfunc shaped like this:
584 .PP
585 .Vb 2
586 \& =item myfunc LIST
587 \& X<myfunc>
588 \&
589 \& =item myfunc
590 \&
591 \& =for Pod::Functions demonstrate a function\*(Aqs perlfunc section
592 \&
593 \& [ Main part of function definition goes here, with examples ]
594 \&
595 \& =over
596 \&
597 \& =item Legacy uses
598 \&
599 \& [ Examples of deprecated syntax still worth documenting ]
600 \&
601 \& =item Security considerations
602 \&
603 \& [ And so on... ]
604 \&
605 \& =back
606 .Ve
607 .SH "TONE AND STYLE"
608 .IX Header "TONE AND STYLE"
609 .SS "Apply one of the four documentation modes"
610 .IX Subsection "Apply one of the four documentation modes"
611 Aside from "meta" documentation such as \f(CW\*(C`perlhist\*(C'\fR or \f(CW\*(C`perlartistic\*(C'\fR,
612 each of Perl\*(Aqs man pages should conform to one of the four documentation
613 "modes" suggested by \fIThe Documentation System\fR by Daniele
614 Procida <https://documentation.divio.com>. These include tutorials,
615 cookbooks, explainers, and references\-\-terms that we define in further
616 detail below.
617 .PP
618 Each mode of documentation speaks to a different audience\-\-not just
619 people of different backgrounds and skill levels, but individual readers
620 whose needs from language documentation can shift depending upon
621 context. For example, a programmer with plenty of time to learn a new
622 concept about Perl can ease into a tutorial about it, and later expand
623 their knowledge further by studying an explainer. Later, that same
624 programmer, wading knee\-deep in live code and needing only to look up
625 some function\*(Aqs exact syntax, will want to reach for a reference page
626 instead.
627 .PP
628 Perl\*(Aqs documentation must strive to meet these different situational
629 expectations by limiting each man page to a single mode. This helps
630 writers ensure they provide readers with the documentation needed or
631 expected, despite ever\-evolving situations.
632 .PP
633 \fITutorial\fR
634 .IX Subsection "Tutorial"
635 .PP
636 A tutorial man page focuses on \fBlearning\fR, ideally by \fIdoing\fR. It
637 presents the reader with small, interesting examples that allow them to
638 follow along themselves using their own Perl interpreter. The tutorial
639 inspires comprehension by letting its readers immediately experience
640 (and experiment on) the concept in question. Examples include
641 \&\f(CW\*(C`perlxstut\*(C'\fR, \f(CW\*(C`perlpacktut\*(C'\fR, and
642 \&\f(CW\*(C`perlretut\*(C'\fR.
643 .PP
644 Tutorial man pages must strive for a welcoming and reassuring tone from
645 their outset; they may very well be the first things that a newcomer to
646 Perl reads, playing a significant role in whether they choose
647 to stick around. Even an experienced programmer can benefit from the
648 sense of courage imparted by a strong tutorial about a more advanced
649 topic. After completing a tutorial, a reader should feel like they\*(Aqve
650 been led from zero knowledge of its topic to having an invigorating
651 spark of basic understanding, excited to learn more and experiment
652 further.
653 .PP
654 Tutorials can certainly use real\-world examples when that helps make for
655 clear, relatable demonstrations, so long as they keep the focus on
656 teaching\-\-more practical problem\-solving should be left to the realm
657 of cookbooks (as described below). Tutorials also needn\*(Aqt concern
658 themselves with explanations into why or how things work beneath the
659 surface, or explorations of alternate syntaxes and solutions; these are
660 better handled by explainers and reference pages.
661 .PP
662 \fICookbook\fR
663 .IX Subsection "Cookbook"
664 .PP
665 A cookbook man page focuses on \fBresults\fR. Just like its name suggests,
666 it presents succinct, step\-by\-step solutions to a variety of real\-world
667 problems around some topic. A cookbook\*(Aqs code examples serve less to
668 enlighten and more to provide quick, paste\-ready solutions that the
669 reader can apply immediately to the situation facing them.
670 .PP
671 A Perl cookbook demonstrates ways that all the tools and techniques
672 explained elsewhere can work together in order to achieve practical
673 results. Any explanation deeper than that belongs in explainers and
674 reference pages, instead. (Certainly, a cookbook can cross\-reference
675 other man pages in order to satisfy the curiosity of readers who, with
676 their immediate problems solved, wish to learn more.)
677 .PP
678 The most prominent cookbook pages that ship with Perl itself are its
679 many FAQ pages, in particular \f(CW\*(C`perlfaq4\*(C'\fR and up, which provide short
680 solutions to practical questions in question\-and\-answer style.
681 \&\f(CW\*(C`perlunicook\*(C'\fR shows another example, containing a bevy of practical code
682 snippets for a variety of internationally minded text manipulations.
683 .PP
684 (An aside: \fIThe Documentation System\fR calls this mode "how\-to", but
685 Perl\*(Aqs history of creative cuisine prefers the more kitchen\-ready term
686 that we employ here.)
687 .PP
688 \fIReference\fR
689 .IX Subsection "Reference"
690 .PP
691 A reference page focuses on \fBdescription\fR. Austere, uniform, and
692 succinct, reference pages\-\-often arranged into a whole section of
693 mutually similar subpages\-\-lend themselves well to "random access" by
694 a reader who knows precisely what knowledge they need, requiring only
695 the minimum amount of information before returning to the task at hand.
696 .PP
697 Perl\*(Aqs own best example of a reference work is \f(CW\*(C`perlfunc\*(C'\fR, the
698 sprawling man page that details the operation of every function built
699 into Perl, with each function\*(Aqs documentation presenting the same kinds
700 of information in the same order as every other. For an example of a
701 shorter reference on a single topic, look at \f(CW\*(C`perlreref\*(C'\fR.
702 .PP
703 Module documentation\-\-including that of all the modules listed in
704 \&\f(CW\*(C`perlmodlib\*(C'\fR\-\-also counts as reference. They follow
705 precepts similar to those laid down by the \f(CW\*(C`perlpodstyle\*(C'\fR man page, such
706 as opening with an example\-laden "SYNOPSIS" section, or featuring a
707 "METHODS" section that succinctly lists and defines an object\-oriented
708 module\*(Aqs public interface.
709 .PP
710 \fIExplainer\fR
711 .IX Subsection "Explainer"
712 .PP
713 Explainer pages focus on \fBdiscussion\fR. Each explainer dives as deep as
714 needed into some Perl\-relevant topic, taking all the time and space
715 needed to give the reader a thorough understanding of it. Explainers
716 mean to impart knowledge through study. They don\*(Aqt assume that the
717 student has a Perl interpreter fired up and hungry for immediate examples
718 (as with a tutorial), or specific Perl problems that they need quick
719 answers for (which cookbooks and reference pages can help with).
720 .PP
721 Outside of its reference pages, most of Perl\*(Aqs manual belongs to this
722 mode. This includes the majority of the man pages whose names start with
723 "\f(CW\*(C`perl\*(C'\fR". A fine example is \f(CW\*(C`perlsyn\*(C'\fR, the Perl Syntax page, which
724 explores the whys and wherefores of Perl\*(Aqs unique syntax in a
725 wide\-ranging discussion laden with many references to the language\*(Aqs
726 history, culture, and driving philosophies.
727 .PP
728 Perl\*(Aqs explainer pages give authors a chance to explore Perl\*(Aqs penchant
729 for TMTOWTDI, illustrating alternate and even
730 obscure ways to use the language feature under discussion. However, as
731 the remainder of this guide discusses, the ideal Perl documentation
732 manages to deliver its message clearly and concisely, and not confuse
733 mere wordiness for completeness.
734 .PP
735 \fIFurther notes on documentation modes\fR
736 .IX Subsection "Further notes on documentation modes"
737 .PP
738 Keep in mind that the purpose of this categorization is not to dictate
739 content\-\-a very thorough explainer might contain short reference
740 sections of its own, for example, or a reference page about a very
741 complex function might resemble an explainer in places (e.g.
742 \&\f(CW\*(C`open\*(C'\fR). Rather, it makes sure
743 that the authors and contributors of any given man page agree on what
744 sort of audience that page addresses.
745 .PP
746 If a new or otherwise uncategorized man page presents itself as
747 resistant to fitting into only one of the four modes, consider breaking
748 it up into separate pages. That may mean creating a new "\f(CW\*(C`perl[...]\*(C'\fR"
749 man page, or (in the case of module documentation) making new packages
750 underneath that module\*(Aqs namespace that serve only to hold additional
751 documentation. For instance, \f(CW\*(C`Example::Module\*(C'\fR\*(Aqs reference documentation
752 might include a see\-also link to \f(CW\*(C`Example::Module::Cookbook\*(C'\fR.
753 .PP
754 Perl\*(Aqs several man pages about Unicode\-\-comprising a short tutorial, a
755 thorough explainer, a cookbook, and a FAQ\-\-provide a fine example of
756 spreading a complicated topic across several man pages with different
757 and clearly indicated purposes.
758 .SS "Assume readers\*(Aq intelligence, but not their knowledge"
759 .IX Subsection "Assume readers' intelligence, but not their knowledge"
760 Perl has grown a great deal from its humble beginnings as a tool for
761 people already well versed in C programming and various Unix utilities.
762 Today, a person learning Perl might come from any social or
763 technological background, with a range of possible motivations
764 stretching far beyond system administration.
765 .PP
766 Perl\*(Aqs core documentation must recognize this by making as few
767 assumptions as possible about the reader\*(Aqs prior knowledge. While you
768 should assume that readers of Perl\*(Aqs documentation are smart, curious,
769 and eager to learn, you should not confuse this for pre\-existing
770 knowledge about any other technology, or even programming in
771 general\-\-especially in tutorial or introductory material.
772 .PP
773 \fIKeep Perl\*(Aqs documentation about Perl\fR
774 .IX Subsection "Keep Perl's documentation about Perl"
775 .PP
776 Outside of pages tasked specifically with exploring Perl\*(Aqs relationship
777 with other programming languages, the documentation should keep the
778 focus on Perl. Avoid drawing analogies to other technologies that the
779 reader may not have familiarity with.
780 .PP
781 For example, when documenting one of Perl\*(Aqs built\-in functions, write as
782 if the reader is now learning about that function for the first time, in
783 any programming language.
784 .PP
785 Choosing to instead compare it to an equivalent or underlying C function
786 will probably not illuminate much understanding in a contemporary
787 reader. Worse, this can risk leaving readers unfamiliar with C feeling
788 locked out from fully understanding of the topic\-\-to say nothing of
789 readers new to computer programming altogether.
790 .PP
791 If, however, that function\*(Aqs ties to its C roots can lead to deeper
792 understanding with practical applications for a Perl programmer, you may
793 mention that link after its more immediately useful documentation.
794 Otherwise, omit this information entirely, leaving it for other
795 documentation or external articles more concerned with examining Perl\*(Aqs
796 underlying implementation details.
797 .PP
798 \fIDeploy jargon when needed, but define it as well\fR
799 .IX Subsection "Deploy jargon when needed, but define it as well"
800 .PP
801 Domain\-specific jargon has its place, especially within documentation.
802 However, if a man page makes use of jargon that a typical reader might
803 not already know, then that page should make an effort to define the
804 term in question early\-on\-\-either explicitly, or via cross reference.
805 .PP
806 For example, Perl loves working with filehandles, and as such that word
807 appears throughout its documentation. A new Perl programmer arriving at
808 a man page for the first time is quite likely to have no idea what a
809 "filehandle" is, though. Any Perl man page mentioning filehandles
810 should, at the very least, hyperlink that term to an explanation
811 elsewhere in Perl\*(Aqs documentation. If appropriate\-\-for example, in the
812 lead\-in to \f(CW\*(C`open\*(C'\fR function\*(Aqs detailed reference\-\-it can also include a very short in\-place
813 definition of the concept for the reader\*(Aqs convenience.
814 .SS "Use meaningful variable and symbol names in examples"
815 .IX Subsection "Use meaningful variable and symbol names in examples"
816 When quickly sketching out examples, English\-speaking programmers have a
817 long tradition of using short nonsense words as placeholders for
818 variables and other symbols\-\-such as the venerable \f(CW\*(C`foo\*(C'\fR, \f(CW\*(C`bar\*(C'\fR, and
819 \&\f(CW\*(C`baz\*(C'\fR. Example code found in a programming language\*(Aqs official,
820 permanent documentation, however, can and should make an effort to
821 provide a little more clarity through specificity.
822 .PP
823 Whenever possible, code examples should give variables, classes, and
824 other programmer\-defined symbols names that clearly demonstrate their
825 function and their relationship to one another. For example, if an
826 example requires that one class show an "is\-a" relationship with
827 another, consider naming them something like \f(CW\*(C`Apple\*(C'\fR and \f(CW\*(C`Fruit\*(C'\fR, rather
828 than \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR. Similarly, sample code creating an instance of
829 that class would do better to name it \f(CW$apple\fR, rather than \f(CW$baz\fR.
830 .PP
831 Even the simplest examples benefit from clear language using concrete
832 words. Prefer a construct like \f(CW\*(C`for my $item (@items) { ... }\*(C'\fR over
833 \&\f(CW\*(C`for my $blah (@blah) { ... }\*(C'\fR.
834 .SS "Write in English, but not just for English\-speakers"
835 .IX Subsection "Write in English, but not just for English-speakers"
836 While this style guide does specify American English as the
837 documentation\*(Aqs language for the sake of internal consistency, authors
838 should avoid cultural or idiomatic references available only to
839 English\-speaking Americans (or any other specific culture or society).
840 As much as possible, the language employed by Perl\*(Aqs core documentation
841 should strive towards cultural universality, if not neutrality. Regional
842 turns of phrase, examples drawing on popular\-culture knowledge, and
843 other rhetorical techniques of that nature should appear sparingly, if
844 at all.
845 .PP
846 Authors should feel free to let more freewheeling language flourish in
847 "second\-order" documentation about Perl, like books, blog entries, and
848 magazine articles, published elsewhere and with a narrower readership in
849 mind. But Perl\*(Aqs own docs should use language as accessible and
850 welcoming to as wide an audience as possible.
851 .SS "Omit placeholder text or commentary"
852 .IX Subsection "Omit placeholder text or commentary"
853 Placeholder text does not belong in the documentation that ships with
854 Perl. No section header should be followed by text reading only "Watch
855 this space", "To be included later", or the like. While Perl\*(Aqs source
856 files may shift and alter as much as any other actively maintained
857 technology, each released iteration of its technology should feel
858 complete and self\-contained, with no such future promises or other loose
859 ends visible.
860 .PP
861 Take advantage of Perl\*(Aqs regular release cycle. Instead of cluttering
862 the docs with flags promising more information later\-\-the presence of
863 which do not help readers at all today\-\-the documentation\*(Aqs
864 maintenance team should treat any known documentation absences as an
865 issue to address like any other in the Perl project. Let Perl\*(Aqs
866 contributors, testers, and release engineers address that need, and
867 resist the temptation to insert apologies, which have all the utility in
868 documentation as undeleted debug messages do in production code.
869 .SS "Apply section\-breaks and examples generously"
870 .IX Subsection "Apply section-breaks and examples generously"
871 No matter how accessible their tone, the sight of monolithic blocks of
872 text in technical documentation can present a will\-weakening challenge
873 for the reader. Authors can improve this situation through breaking long
874 passages up into subsections with short, meaningful headers.
875 .PP
876 Since every section\-header in Pod also acts as a potential end\-point for
877 a cross\-reference (made via Pod\*(Aqs \f(CW\*(C`L<...>\*(C'\fR syntax), putting
878 plenty of subsections in your documentation lets other man pages more
879 precisely link to a particular topic. This creates hyperlinks directly
880 to the most appropriate section rather than to the whole page in
881 general, and helps create a more cohesive sense of a rich, consistent,
882 and interrelated manual for readers.
883 .PP
884 Among the four documentation modes, sections belong more naturally in
885 tutorials and explainers. The step\-by\-step instructions of cookbooks, or
886 the austere definitions of reference pages, usually have no room for
887 them. But authors can always make exceptions for unusually complex
888 concepts that require further breakdown for clarity\*(Aqs sake.
889 .PP
890 Example code, on the other hand, can be a welcome addition to any mode
891 of documentation. Code blocks help break up a man page visually,
892 reassuring the reader that no matter how deep the textual explanation
893 gets, they are never far from another practical example showing how it
894 all comes together using a small, easy\-to\-read snippet of tested Perl
895 code.
896 .SS "Lead with common cases and best practices"
897 .IX Subsection "Lead with common cases and best practices"
898 Perl famously gives programmers more than one way to do things. Like any
899 other long\-lived programming language, Perl has also built up a large,
900 community\-held notion of best practices, blessing some ways to do things
901 as better than others, usually for the sake of more maintainable code.
902 .PP
903 \fIShow the better ways first\fR
904 .IX Subsection "Show the better ways first"
905 .PP
906 Whenever it needs to show the rules for a technique which Perl provides
907 many avenues for, the documentation should always lead with best
908 practices. And when discussing some part of the Perl toolkit with many
909 applications, the docs should begin with a demonstration of its
910 application to the most common cases.
911 .PP
912 The \f(CW\*(C`open\*(C'\fR function, for example, has myriad potential uses within Perl
913 programs, but \fImost of the time\fR programmers\-\-and especially those new
914 to Perl\-\-turn to this reference because they simply wish to open a
915 file for reading or writing. For this reason, \f(CW\*(C`open\*(C'\fR\*(Aqs documentation
916 begins there, and only descends into the function\*(Aqs more obscure uses
917 after thoroughly documenting and demonstrating how it works in the
918 common case. Furthermore, while engaging in this demonstration, the
919 \&\f(CW\*(C`open\*(C'\fR documentation does not burden the reader right away with detailed
920 explanations about calling \f(CW\*(C`open\*(C'\fR via any route other than the
921 best\-practice, three\-argument style.
922 .PP
923 \fIShow the lesser ways when needed\fR
924 .IX Subsection "Show the lesser ways when needed"
925 .PP
926 Sometimes, thoroughness demands documentation of deprecated techniques.
927 For example, a certain Perl function might have an alternate syntax now
928 considered outmoded and no longer best\-practice, but which a maintainer
929 of a legacy project might quite reasonably encounter when exploring old
930 code. In this case, these features deserve documentation, but couched in
931 clarity that modern Perl avoids such structures, and does not recommend
932 their use in new projects.
933 .PP
934 Another way to look at this philosophy (and one borrowed from our
935 friends <https://devguide.python.org/documenting/#affirmative-tone> on
936 Python\*(Aqs documentation team) involves writing while sympathizing with a
937 programmer new to Perl, who may feel uncertain about learning a complex
938 concept. By leading that concept\*(Aqs main documentation with clear,
939 positive examples, we can immediately give these readers a simple and
940 true picture of how it works in Perl, and boost their own confidence to
941 start making use of this new knowledge. Certainly we should include
942 alternate routes and admonitions as reasonably required, but we needn\*(Aqt
943 emphasize them. Trust the reader to understand the basics quickly, and
944 to keep reading for a deeper understanding if they feel so driven.
945 .SS "Document Perl\*(Aqs present"
946 .IX Subsection "Document Perl's present"
947 Perl\*(Aqs documentation should stay focused on Perl\*(Aqs present behavior,
948 with a nod to future directions.
949 .PP
950 \fIRecount the past only when necessary\fR
951 .IX Subsection "Recount the past only when necessary"
952 .PP
953 When some Perl feature changes its behavior, documentation about
954 that feature should change too, and just as definitively. The docs have
955 no obligation to keep descriptions of past behavior hanging around, even if
956 attaching clauses like "Prior to version 5.10, [...]".
957 .PP
958 Since Perl\*(Aqs core documentation is part of Perl\*(Aqs source distribution,
959 it enjoys the same benefits of versioning and version\-control as the
960 source code of Perl itself. Take advantage of this, and update the text
961 boldly when needed. Perl\*(Aqs history remains safe, even when you delete or
962 replace outdated information from the current version\*(Aqs docs.
963 .PP
964 Perl\*(Aqs docs can acknowledge or discuss former behavior when warranted,
965 including notes that some feature appeared in the language as of some
966 specific version number. Authors should consider applying principles
967 similar to those for deprecated techniques, as described above: make the information present, but not
968 prominent.
969 .PP
970 Otherwise, keep the past in the past. A manual uncluttered with
971 outdated instruction stays more succinct and relevant.
972 .PP
973 \fIDescribe the uncertain future with care\fR
974 .IX Subsection "Describe the uncertain future with care"
975 .PP
976 Perl features marked as "experimental"\-\-those that generate warnings
977 when used in code not invoking the \f(CW\*(C`experimental\*(C'\fR
978 pragma\-\-deserve documentation, but only in certain contexts, and even
979 then with caveats. These features represent possible new directions for
980 Perl, but they have unstable interfaces and uncertain future presence.
981 .PP
982 The documentation should take both implications of "experimental"
983 literally. It should not discourage these features\*(Aq use by programmers
984 who wish to try out new features in projects that can risk their
985 inherent instability; this experimentation can help Perl grow and
986 improve. By the same token, the docs should downplay these features\*(Aq use
987 in just about every other context.
988 .PP
989 Introductory or overview material should omit coverage of experimental
990 features altogether.
991 .PP
992 More thorough reference materials or explanatory articles can include
993 experimental features, but needs to clearly mark them as such, and not
994 treat them with the same prominence as Perl\*(Aqs stable features. Using
995 unstable features seldom coincides with best practices, and
996 documentation that puts best practices first should reflect this.
997 .SS "The documentation speaks with one voice"
998 .IX Subsection "The documentation speaks with one voice"
999 Even though it comes from many hands and minds, criss\-crossing through
1000 the many years of Perl\*(Aqs lifetime, the language\*(Aqs documentation should
1001 speak with a single, consistent voice. With few exceptions, the docs
1002 should avoid explicit first\-person\-singular statements, or similar
1003 self\-reference to any individual\*(Aqs contributor\*(Aqs philosophies or
1004 experiences.
1005 .PP
1006 Perl did begin life as a deeply personal expression by a single
1007 individual, and this famously carried through the first revisions of its
1008 documentation as well. Today, Perl\*(Aqs community understands that the
1009 language\*(Aqs continued development and support comes from many people
1010 working in concert, rather than any one person\*(Aqs vision or effort. Its
1011 documentation should not pretend otherwise.
1012 .PP
1013 The documentation should, however, carry forward the best tradition that
1014 Larry Wall set forth in the language\*(Aqs earliest days: Write both
1015 economically and with a humble, subtle wit, resulting in a technical
1016 manual that mixes concision with a friendly approachability. It avoids
1017 the dryness that one might expect from technical documentation, while
1018 not leaning so hard into overt comedy as to distract and confuse from
1019 the nonetheless\-technical topics at hand.
1020 .PP
1021 Like the best written works, Perl\*(Aqs documentation has a soul. Get
1022 familiar with it as a reader to internalize its voice, and then find
1023 your own way to express it in your own contributions. Writing clearly,
1024 succinctly, and with knowledge of your audience\*(Aqs expectations will get
1025 you most of the way there, in the meantime.
1026 .PP
1027 Every line in the docs\-\-whether English sentence or Perl
1028 statement\-\-should serve the purpose of bringing understanding to the
1029 reader. Should a sentence exist mainly to make a wry joke that doesn\*(Aqt
1030 further the reader\*(Aqs knowledge of Perl, set it aside, and consider
1031 recasting it into a personal blog post or other article instead.
1032 .PP
1033 Write with a light heart, and a miserly hand.
1034 .SH "INDEX OF PREFERRED TERMS"
1035 .IX Header "INDEX OF PREFERRED TERMS"
1036 As noted above, this guide
1037 "inherits" all the preferred terms listed in the Chicago Manual of
1038 Style, 17th edition, and adds the following terms of particular interest
1039 to Perl documentation.
1040 .IP "built\-in function" 4
1041 .IX Item "built-in function"
1042 Not "builtin".
1043 .IP Darwin 4
1044 .IX Item "Darwin"
1045 See macOS.
1046 .IP macOS 4
1047 .IX Item "macOS"
1048 Use this term for Apple\*(Aqs operating system instead of "Mac OS X" or
1049 variants thereof.
1050 .Sp
1051 This term is also preferable to "Darwin", unless one needs to refer
1052 to macOS\*(Aqs Unix layer specifically.
1053 .IP "man page" 4
1054 .IX Item "man page"
1055 One unit of Unix\-style documentation. Not "manpage". Preferable to "manual page".
1056 .IP "Perl; perl" 4
1057 .IX Item "Perl; perl"
1058 The name of the programming language is Perl, with a leading capital
1059 "P", and the remainder in lowercase. (Never "PERL".)
1060 .Sp
1061 The interpreter program that reads and executes Perl code is named
1062 "\f(CW\*(C`perl\*(C'\fR", in lowercase and in monospace (as with any other command
1063 name).
1064 .Sp
1065 Generally, unless you are specifically writing about the
1066 command\-line \f(CW\*(C`perl\*(C'\fR program (as, for example, \f(CW\*(C`perlrun\*(C'\fR
1067 does), use "Perl" instead.
1068 .IP "Perl 5" 4
1069 .IX Item "Perl 5"
1070 Documentation need not follow Perl\*(Aqs name with a "5", or any other
1071 number, except during discussions of Perl\*(Aqs history, future plans,
1072 or explicit comparisons between major Perl versions.
1073 .Sp
1074 Before 2019, specifying "Perl 5" was sometimes needed to distinguish
1075 the language from Perl 6. With the latter\*(Aqs renaming to "Raku", this
1076 practice became unnecessary.
1077 .IP "Perl 6" 4
1078 .IX Item "Perl 6"
1079 See Raku.
1080 .IP "Perl 5 Porters, the; porters, the; p5p" 4
1081 .IX Item "Perl 5 Porters, the; porters, the; p5p"
1082 The full name of the team responsible for Perl\*(Aqs ongoing maintenance
1083 and development is "the Perl 5 Porters", and this sobriquet should
1084 be spelled out in the first mention within any one document. It may
1085 thereafter call the team "the porters" or "p5p".
1086 .Sp
1087 Not "Perl5 Porters".
1088 .IP program 4
1089 .IX Item "program"
1090 The most general descriptor for a stand\-alone work made out of
1091 executable Perl code. Synonymous with, and preferable to, "script".
1092 .IP Raku 4
1093 .IX Item "Raku"
1094 Perl\*(Aqs "sister language", whose homepage is <https://raku.org>.
1095 .Sp
1096 Previously known as "Perl 6". In 2019, its design team renamed the
1097 language to better reflect its identity as a project independent from
1098 Perl. As such, Perl\*(Aqs documentation should always refer to this language
1099 as "Raku" and not "Perl 6".
1100 .IP script 4
1101 .IX Item "script"
1102 See program.
1103 .IP semicolon 4
1104 .IX Item "semicolon"
1105 Perl code\*(Aqs frequently overlooked punctuation mark. Not "semi\-colon".
1106 .IP Unix 4
1107 .IX Item "Unix"
1108 Not "UNIX", "*nix", or "Un*x". Applicable to both the original operating
1109 system from the 1970s as well as all its conceptual descendants. You may
1110 simply write "Unix" and not "a Unix\-like operating system" when
1111 referring to a Unix\-like operating system.
1112 .SH "SEE ALSO"
1113 .IX Header "SEE ALSO"
1114 .IP \(bu 4
1115 perlpod
1116 .IP \(bu 4
1117 perlpodstyle
1118 .SH AUTHOR
1119 .IX Header "AUTHOR"
1120 This guide was initially drafted by Jason McIntosh
1121 ([email protected]), under a grant from The Perl Foundation.