Debian Codegraph @

upstream/debian-unstable/man1/perldocstyle.1

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