1PERLDOCSTYLE(1)        Perl Programmers Reference Guide        PERLDOCSTYLE(1)
2
3
4

NAME

6       perldocstyle - A style guide for writing Perl's documentation
7

DESCRIPTION

9       This document is a guide for the authorship and maintenance of the
10       documentation that ships with Perl. This includes the following:
11
12       •   The several dozen manual sections whose filenames begin with
13           ""perl"", such as "perlobj", "perlre", and "perlintro". (And, yes,
14           "perl".)
15
16       •   The documentation for all the modules included with Perl (as listed
17           by "perlmodlib").
18
19       •   The hundreds of individually presented reference sections derived
20           from the "perlfunc" file.
21
22       This guide will hereafter refer to user-manual section files as man
23       pages, per Unix convention.
24
25   Purpose of this guide
26       This style guide aims to establish standards, procedures, and
27       philosophies applicable to Perl's core documentation.
28
29       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
37       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
42   Intended audience
43       Anyone interested in contributing to Perl's core documentation should
44       familiarize themselves with the standards outlined by this guide.
45
46       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
50   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
56       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

FUNDAMENTALS

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
70       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
75       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
79   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
85       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
91       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
98       Other languages and translations
99
100       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
105       That said, keeping Perl's documentation clear, simple, and short has a
106       welcome side effect of aiding any such translation project.
107
108       (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
113   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
117       As such, every core doc file (or the Pod section of every core module)
118       should commence with an "=encoding utf8" declaration.
119
120   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
128       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
136   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
145       Perl accepts documentation contributions through the same open-source
146       project pipeline as code contributions. See "perlhack" for more
147       information.
148

FORMATTING AND STRUCTURE

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
154   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
161       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
167       Name
168
169       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
173       The first few lines of a notional page named "perlpodexample":
174
175           =encoding utf8
176
177           =head1 NAME
178
179           perlpodexample - An example of formatting a manual page's title line
180
181       Description and synopsis
182
183       Most Perl man pages also contain a DESCRIPTION section featuring a
184       summary of, or introduction to, the document's content and purpose.
185
186       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
193       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
200       Other sections and subsections
201
202       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
207       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
213       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
217       Author and copyright
218
219       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
226       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
232       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
236   Formatting rules
237       Line length and line wrap
238
239       Each line within a Perl man page's Pod source file should measure 72
240       characters or fewer in length.
241
242       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
246       Code blocks
247
248       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
252       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
256       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
261       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
266           while (my $line = <$fh>) {
267               #
268               # (Do something interesting with $line here.)
269               #
270           }
271
272       Even the simplest code blocks often require the use of example
273       variables and subroutines, whose names you should choose with care.
274
275       Inline code and literals
276
277       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
280       For instance, when referring within an explanatory paragraph to Perl's
281       operator for adding two numbers together, you'd write ""C<+>"".
282
283       Function names
284
285       Use "C<...>" to render all Perl function names in monospace, whenever
286       they appear in text.
287
288       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
293       Function arguments
294
295       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
300       •   EXPR
301
302           The "generic" argument: any scalar value, or a Perl expression that
303           evaluates to one.
304
305       •   ARRAY
306
307           An array, stored in a named variable.
308
309       •   HASH
310
311           A hash, stored in a named variable.
312
313       •   BLOCK
314
315           A curly-braced code block, or a subroutine reference.
316
317       •   LIST
318
319           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
324       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
328       Apostrophes, quotes, and dashes
329
330       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
334       Render em dashes as two hyphens--like this:
335
336           Render em dashes as two hyphens--like this.
337
338       Leave it up to formatters to reformat and reshape these punctuation
339       marks as best fits their respective target media.
340
341       Unix programs and C functions
342
343       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
347       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
350       Do not otherwise style this text.
351
352       Cross-references and hyperlinks
353
354       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
359       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
366       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
370       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
373           In version 5.10, Perl added support for the
374           L<C<say>|perlfunc/say FILEHANDLE LIST> function.
375
376       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
380       Tables and diagrams
381
382       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
388           =head2 Table of fruits
389
390           =begin text
391
392            Name           Shape           Color
393            =====================================
394            Apple          Round           Red
395            Banana         Long            Yellow
396            Pear           Pear-shaped     Green
397
398           =end text
399
400           =begin html
401
402           <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
409           =end html
410
411       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
415       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
420   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
426       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
430           =for comment Using "=for comment" like this is good for short,
431           single-paragraph comments.
432
433           =begin comment
434
435           If you need to comment out more than one paragraph, use a
436           =begin/=end block, like this.
437
438           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
443           =end comment
444
445       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
450   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
455       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
461       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
465       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
470           If modern best practices prefer certain ways to invoke the function
471           over others, then those ways should lead the list.
472
473           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
477       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
483       3.  The function's definition and reference material, including all
484           explanatory text and code examples.
485
486       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
490       A fictional function ""myfunc"", which takes a list as an optional
491       argument, might have an entry in perlfunc shaped like this:
492
493           =item myfunc LIST
494           X<myfunc>
495
496           =item myfunc
497
498           =for Pod::Functions demonstrate a function's perlfunc section
499
500           [ Main part of function definition goes here, with examples ]
501
502           =over
503
504           =item Legacy uses
505
506           [ Examples of deprecated syntax still worth documenting ]
507
508           =item Security considerations
509
510           [ And so on... ]
511
512           =back
513

TONE AND STYLE

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
523       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
533       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
538       Tutorial
539
540       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
547       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
556       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
564       Cookbook
565
566       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
572       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
579       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
586       (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
590       Reference
591
592       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
598       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
604       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
611       Explainer
612
613       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
621       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
628       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
635       Further notes on documentation modes
636
637       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
644       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
653       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
658   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
665       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
672       Keep Perl's documentation about Perl
673
674       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
679       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
683       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
689       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
696       Deploy jargon when needed, but define it as well
697
698       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
703       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
713   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
721       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
730       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
734   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
745       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
751   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
760       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
769   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
775       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
783       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
789       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
796   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
803       Show the better ways first
804
805       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
811       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
822       Show the lesser ways when needed
823
824       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
832       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
844   Document Perl's present
845       Perl's documentation should stay focused on Perl's present behavior,
846       with a nod to future directions.
847
848       Recount the past only when necessary
849
850       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
855       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
861       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
867       Otherwise, keep the past in the past. A manual uncluttered with
868       outdated instruction stays more succinct and relevant.
869
870       Describe the uncertain future with care
871
872       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
878       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
885       Introductory or overview material should omit coverage of experimental
886       features altogether.
887
888       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
894   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
902       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
909       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
917       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
923       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
929       Write with a light heart, and a miserly hand.
930

INDEX OF PREFERRED TERMS

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
936       built-in function
937           Not "builtin".
938
939       Darwin
940           See macOS.
941
942       macOS
943           Use this term for Apple's operating system instead of "Mac OS X" or
944           variants thereof.
945
946           This term is also preferable to "Darwin", unless one needs to refer
947           to macOS's Unix layer specifically.
948
949       man page
950           One unit of Unix-style documentation. Not "manpage". Preferable to
951           "manual page".
952
953       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
957           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
961           Generally, unless you are specifically writing about the command-
962           line "perl" program (as, for example, "perlrun" does), use "Perl"
963           instead.
964
965       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
970           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
974       Perl 6
975           See Raku.
976
977       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
983           Not "Perl5 Porters".
984
985       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
989       Raku
990           Perl's "sister language", whose homepage is <https://raku.org>.
991
992           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
997       script
998           See program.
999
1000       semicolon
1001           Perl code's frequently overlooked punctuation mark. Not "semi-
1002           colon".
1003
1004       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

SEE ALSO

1011       •   perlpod
1012
1013       •   perlpodstyle
1014

AUTHOR

1016       This guide was initially drafted by Jason McIntosh (jmac@jmac.org),
1017       under a grant from The Perl Foundation.
1018
1019
1020
1021perl v5.34.1                      2022-03-15                   PERLDOCSTYLE(1)
Impressum