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