1*256a93a4Safresh1=encoding utf8 2*256a93a4Safresh1 3*256a93a4Safresh1=head1 NAME 4*256a93a4Safresh1 5*256a93a4Safresh1perldocstyle - A style guide for writing Perl's documentation 6*256a93a4Safresh1 7*256a93a4Safresh1=head1 DESCRIPTION 8*256a93a4Safresh1 9*256a93a4Safresh1This document is a guide for the authorship and maintenance of the 10*256a93a4Safresh1documentation that ships with Perl. This includes the following: 11*256a93a4Safresh1 12*256a93a4Safresh1=over 13*256a93a4Safresh1 14*256a93a4Safresh1=item * 15*256a93a4Safresh1 16*256a93a4Safresh1The several dozen manual sections whose filenames begin with "C<perl>", 17*256a93a4Safresh1such as C<perlobj>, C<perlre>, and C<perlintro>. (And, yes, C<perl>.) 18*256a93a4Safresh1 19*256a93a4Safresh1=item * 20*256a93a4Safresh1 21*256a93a4Safresh1The documentation for all the modules included with Perl (as listed by 22*256a93a4Safresh1L<C<perlmodlib>|perlmodlib>). 23*256a93a4Safresh1 24*256a93a4Safresh1=item * 25*256a93a4Safresh1 26*256a93a4Safresh1The hundreds of individually presented reference sections derived from 27*256a93a4Safresh1the L<C<perlfunc>|perlfunc> file. 28*256a93a4Safresh1 29*256a93a4Safresh1=back 30*256a93a4Safresh1 31*256a93a4Safresh1This guide will hereafter refer to user-manual section files as I<man 32*256a93a4Safresh1pages>, per Unix convention. 33*256a93a4Safresh1 34*256a93a4Safresh1=head2 Purpose of this guide 35*256a93a4Safresh1 36*256a93a4Safresh1This style guide aims to establish standards, procedures, and philosophies 37*256a93a4Safresh1applicable to Perl's core documentation. 38*256a93a4Safresh1 39*256a93a4Safresh1Adherence to these standards will help ensure that any one part of 40*256a93a4Safresh1Perl's manual has a tone and style consistent with that of any other. As 41*256a93a4Safresh1with the rest of the Perl project, the language's documentation 42*256a93a4Safresh1collection is an open-source project authored over a long period of time 43*256a93a4Safresh1by many people. Maintaining consistency across such a wide swath of work 44*256a93a4Safresh1presents a challenge; this guide provides a foundation to help mitigate 45*256a93a4Safresh1this difficulty. 46*256a93a4Safresh1 47*256a93a4Safresh1This will help its readers--especially those new to Perl--to feel 48*256a93a4Safresh1more welcome and engaged with Perl's documentation, and this in turn 49*256a93a4Safresh1will help the Perl project itself grow stronger through having a larger, 50*256a93a4Safresh1more diverse, and more confident population of knowledgeable users. 51*256a93a4Safresh1 52*256a93a4Safresh1=head2 Intended audience 53*256a93a4Safresh1 54*256a93a4Safresh1Anyone interested in contributing to Perl's core documentation should 55*256a93a4Safresh1familiarize themselves with the standards outlined by this guide. 56*256a93a4Safresh1 57*256a93a4Safresh1Programmers documenting their own work apart from the Perl project 58*256a93a4Safresh1itself may also find this guide worthwhile, especially if they wish 59*256a93a4Safresh1their work to extend the tone and style of Perl's own manual. 60*256a93a4Safresh1 61*256a93a4Safresh1=head2 Status of this document 62*256a93a4Safresh1 63*256a93a4Safresh1This guide was initially drafted in late 2020, drawing from the 64*256a93a4Safresh1documentation style guides of several open-source technologies 65*256a93a4Safresh1contemporary with Perl. This has included Python, Raku, Rust, and the 66*256a93a4Safresh1Linux kernel. 67*256a93a4Safresh1 68*256a93a4Safresh1The author intends to see this guide used as starting place from 69*256a93a4Safresh1which to launch a review of Perl's reams of extant documentation, with 70*256a93a4Safresh1the expectation that those conducting this review should grow and modify 71*256a93a4Safresh1this guide as needed to account for the requirements and quirks 72*256a93a4Safresh1particular to Perl's programming manual. 73*256a93a4Safresh1 74*256a93a4Safresh1=head1 FUNDAMENTALS 75*256a93a4Safresh1 76*256a93a4Safresh1=head2 Choice of markup: Pod 77*256a93a4Safresh1 78*256a93a4Safresh1All of Perl's core documentation uses Pod ("Plain Old Documentation"), a 79*256a93a4Safresh1simple markup language, to format its source text. Pod is similar in 80*256a93a4Safresh1spirit to other contemporary lightweight markup technologies, such as 81*256a93a4Safresh1Markdown and reStructuredText, and has a decades-long shared history 82*256a93a4Safresh1with Perl itself. 83*256a93a4Safresh1 84*256a93a4Safresh1For a comprehensive reference to Pod syntax, see L<C<perlpod>|perlpod>. 85*256a93a4Safresh1For the sake of reading this guide, familiarity with the Pod syntax for 86*256a93a4Safresh1section headers (C<=head2>, et cetera) and for inline text formatting 87*256a93a4Safresh1(C<CE<lt>like thisE<gt>>) should suffice. 88*256a93a4Safresh1 89*256a93a4Safresh1Perl programmers also use Pod to document their own scripts, libraries, 90*256a93a4Safresh1and modules. This use of Pod has its own style guide, outlined by 91*256a93a4Safresh1L<C<perlpodstyle>|perlpodstyle>. 92*256a93a4Safresh1 93*256a93a4Safresh1=head2 Choice of language: American English 94*256a93a4Safresh1 95*256a93a4Safresh1Perl's core documentation is written in English, with a preference for 96*256a93a4Safresh1American spelling of words and expression of phrases. That means "color" 97*256a93a4Safresh1over "colour", "math" versus "maths", "the team has decided" and not 98*256a93a4Safresh1"the team have decided", and so on. 99*256a93a4Safresh1 100*256a93a4Safresh1We name one style of English for the sake of consistency across Perl's 101*256a93a4Safresh1documentation, much as a software project might declare a four-space 102*256a93a4Safresh1indentation standard--even when that doesn't affect how well the code 103*256a93a4Safresh1compiles. Both efforts result in an easier read by avoiding jarring, 104*256a93a4Safresh1mid-document changes in format or style. 105*256a93a4Safresh1 106*256a93a4Safresh1Contributors to Perl's documentation should note that this rule 107*256a93a4Safresh1describes the ultimate, published output of the project, and does not 108*256a93a4Safresh1prescribe the dialect used within community contributions. The 109*256a93a4Safresh1documentation team enthusiastically welcomes any English-language 110*256a93a4Safresh1contributions, and will actively assist in Americanizing spelling and 111*256a93a4Safresh1style when warranted. 112*256a93a4Safresh1 113*256a93a4Safresh1=head3 Other languages and translations 114*256a93a4Safresh1 115*256a93a4Safresh1Community-authored translations of Perl's documentation do exist, 116*256a93a4Safresh1covering a variety of languages. While the Perl project appreciates 117*256a93a4Safresh1these translation efforts and promotes them when applicable, it does not 118*256a93a4Safresh1officially support or maintain any of them. 119*256a93a4Safresh1 120*256a93a4Safresh1That said, keeping Perl's documentation clear, simple, and short has a 121*256a93a4Safresh1welcome side effect of aiding any such translation project. 122*256a93a4Safresh1 123*256a93a4Safresh1(Note that the Chinese, Japanese, and Korean-language README files 124*256a93a4Safresh1included with Perl's source distributions provide an exception to this 125*256a93a4Safresh1choice of language--but these documents fall outside the scope of this 126*256a93a4Safresh1guide.) 127*256a93a4Safresh1 128*256a93a4Safresh1=head2 Choice of encoding: UTF-8 129*256a93a4Safresh1 130*256a93a4Safresh1Perl's core documentation files are encoded in UTF-8, and can make use 131*256a93a4Safresh1of the full range of characters this encoding allows. 132*256a93a4Safresh1 133*256a93a4Safresh1As such, every core doc file (or the Pod section of every core module) 134*256a93a4Safresh1should commence with an C<=encoding utf8> declaration. 135*256a93a4Safresh1 136*256a93a4Safresh1=head2 Choice of underlying style guide: CMOS 137*256a93a4Safresh1 138*256a93a4Safresh1Perl's documentation uses the L<Chicago Manual of 139*256a93a4Safresh1Style|https://www.chicagomanualofstyle.org> (CMOS), 17th Edition, as 140*256a93a4Safresh1its baseline guide for style and grammar. While the document you are 141*256a93a4Safresh1currently reading endeavors to serve as an adequate stand-alone style guide 142*256a93a4Safresh1for the purposes of documenting Perl, authors should consider CMOS the 143*256a93a4Safresh1fallback authority for any pertinent topics not covered here. 144*256a93a4Safresh1 145*256a93a4Safresh1Because CMOS is not a free resource, access to it is not a prerequisite 146*256a93a4Safresh1for contributing to Perl's documentation; the doc team will help 147*256a93a4Safresh1contributors learn about and apply its guidelines as needed. However, we 148*256a93a4Safresh1do encourage anyone interested in significant doc contributions to 149*256a93a4Safresh1obtain or at least read through CMOS. (Copies are likely available 150*256a93a4Safresh1through most public libraries, and CMOS-derived fundamentals can be 151*256a93a4Safresh1found online as well.) 152*256a93a4Safresh1 153*256a93a4Safresh1=head2 Contributing to Perl's documentation 154*256a93a4Safresh1 155*256a93a4Safresh1Perl, like any programming language, is only as good as its 156*256a93a4Safresh1documentation. Perl depends upon clear, friendly, and thorough 157*256a93a4Safresh1documentation in order to welcome brand-new users, teach and explain the 158*256a93a4Safresh1language's various concepts and components, and serve as a lifelong 159*256a93a4Safresh1reference for experienced Perl programmers. As such, the Perl project 160*256a93a4Safresh1welcomes and values all community efforts to improve the language's 161*256a93a4Safresh1documentation. 162*256a93a4Safresh1 163*256a93a4Safresh1Perl accepts documentation contributions through the same open-source 164*256a93a4Safresh1project pipeline as code contributions. See L<C<perlhack>|perlhack> for 165*256a93a4Safresh1more information. 166*256a93a4Safresh1 167*256a93a4Safresh1=head1 FORMATTING AND STRUCTURE 168*256a93a4Safresh1 169*256a93a4Safresh1This section details specific Pod syntax and style that all core Perl 170*256a93a4Safresh1documentation should adhere to, in the interest of consistency and 171*256a93a4Safresh1readability. 172*256a93a4Safresh1 173*256a93a4Safresh1=head2 Document structure 174*256a93a4Safresh1 175*256a93a4Safresh1Each individual work of core Perl documentation, whether contained 176*256a93a4Safresh1within a C<.pod> file or in the Pod section of a standard code module, 177*256a93a4Safresh1patterns its structure after a number of long-time Unix man page 178*256a93a4Safresh1conventions. (Hence this guide's use of "man page" to refer to any one 179*256a93a4Safresh1self-contained part of Perl's documentation.) 180*256a93a4Safresh1 181*256a93a4Safresh1Adhering to these conventions helps Pod formatters present a Perl man 182*256a93a4Safresh1page's content in different contexts--whether a terminal, the web, or 183*256a93a4Safresh1even print. Many of the following requirements originate with 184*256a93a4Safresh1L<C<perlpodstyle>|perlpodstyle>, which derives its recommendations in 185*256a93a4Safresh1turn from these well-established practices. 186*256a93a4Safresh1 187*256a93a4Safresh1=head3 Name 188*256a93a4Safresh1 189*256a93a4Safresh1After its L<C<=encoding utf8> declaration|/Choice of encoding: UTF-8>, a 190*256a93a4Safresh1Perl man page I<must> present a level-one header named "NAME" (literally), 191*256a93a4Safresh1followed by a paragraph containing the page's name and a very brief 192*256a93a4Safresh1description. 193*256a93a4Safresh1 194*256a93a4Safresh1The first few lines of a notional page named C<perlpodexample>: 195*256a93a4Safresh1 196*256a93a4Safresh1 =encoding utf8 197*256a93a4Safresh1 198*256a93a4Safresh1 =head1 NAME 199*256a93a4Safresh1 200*256a93a4Safresh1 perlpodexample - An example of formatting a manual page's title line 201*256a93a4Safresh1 202*256a93a4Safresh1=head3 Description and synopsis 203*256a93a4Safresh1 204*256a93a4Safresh1Most Perl man pages also contain a DESCRIPTION section featuring a 205*256a93a4Safresh1summary of, or introduction to, the document's content and purpose. 206*256a93a4Safresh1 207*256a93a4Safresh1This section should also, one way or another, clearly identify the 208*256a93a4Safresh1audience that the page addresses, especially if it has expectations 209*256a93a4Safresh1about the reader's prior knowledge. For example, a man page that dives 210*256a93a4Safresh1deep into the inner workings of Perl's regular expression engine should 211*256a93a4Safresh1state its assumptions up front--and quickly redirect readers who are 212*256a93a4Safresh1instead looking for a more basic reference or tutorial. 213*256a93a4Safresh1 214*256a93a4Safresh1Reference pages, when appropriate, can precede the DESCRIPTION with a 215*256a93a4Safresh1SYNOPSIS section that lists, within one or more code blocks, some very 216*256a93a4Safresh1brief examples of the referenced feature's use. This section should show 217*256a93a4Safresh1a handful of common-case and best-practice examples, rather than an 218*256a93a4Safresh1exhaustive list of every obscure method or alternate syntax available. 219*256a93a4Safresh1 220*256a93a4Safresh1=head3 Other sections and subsections 221*256a93a4Safresh1 222*256a93a4Safresh1Pages should conclude, when appropriate, with a SEE ALSO section 223*256a93a4Safresh1containing hyperlinks to relevant sections of Perl's manual, other Unix 224*256a93a4Safresh1man pages, or appropriate web pages. Hyperlink each such cross-reference via 225*256a93a4Safresh1C<LE<lt>...E<gt>>. 226*256a93a4Safresh1 227*256a93a4Safresh1What other sections to include depends entirely upon the topic at hand. 228*256a93a4Safresh1Authors should feel free to include further C<=head1>-level sections, 229*256a93a4Safresh1whether other standard ones listed by C<perlpodstyle>, or ones specific 230*256a93a4Safresh1to the page's topic; in either case, render these top-level headings in 231*256a93a4Safresh1all-capital letters. 232*256a93a4Safresh1 233*256a93a4Safresh1You may then include as many subsections beneath them as needed to meet 234*256a93a4Safresh1the standards of clarity, accessibility, and cross-reference affinity 235*256a93a4Safresh1L<suggested elsewhere in this guide|/Apply one of the four documentation 236*256a93a4Safresh1modes>. 237*256a93a4Safresh1 238*256a93a4Safresh1=head3 Author and copyright 239*256a93a4Safresh1 240*256a93a4Safresh1In most circumstances, Perl's stand-alone man pages--those contained 241*256a93a4Safresh1within C<.pod> files--do not need to include any copyright or license 242*256a93a4Safresh1information about themselves. Their source Pod files are part of Perl's 243*256a93a4Safresh1own core software repository, and that already covers them under the 244*256a93a4Safresh1same copyright and license terms as Perl itself. You do not need to 245*256a93a4Safresh1include additional "LICENSE" or "COPYRIGHT" sections of your own. 246*256a93a4Safresh1 247*256a93a4Safresh1These man pages may optionally credit their primary author, or include a 248*256a93a4Safresh1list of significant contributors, under "AUTHOR" or "CONTRIBUTORS" 249*256a93a4Safresh1headings. Note that the presence of authors' names does not preclude a 250*256a93a4Safresh1given page from L<writing in a voice consistent with the rest of Perl's 251*256a93a4Safresh1documentation|/The documentation speaks with one voice>. 252*256a93a4Safresh1 253*256a93a4Safresh1Note that these guidelines do not apply to the core software modules 254*256a93a4Safresh1that ship with Perl. These have their own standards for authorship and 255*256a93a4Safresh1copyright statements, as found in C<perlpodstyle>. 256*256a93a4Safresh1 257*256a93a4Safresh1=head2 Formatting rules 258*256a93a4Safresh1 259*256a93a4Safresh1=head3 Line length and line wrap 260*256a93a4Safresh1 261*256a93a4Safresh1Each line within a Perl man page's Pod source file should measure 72 262*256a93a4Safresh1characters or fewer in length. 263*256a93a4Safresh1 264*256a93a4Safresh1Please break paragraphs up into blocks of short lines, rather than 265*256a93a4Safresh1"soft wrapping" paragraphs across hundreds of characters with no line 266*256a93a4Safresh1breaks. 267*256a93a4Safresh1 268*256a93a4Safresh1=head3 Code blocks 269*256a93a4Safresh1 270*256a93a4Safresh1Just like the text around them, all code examples should be as short and 271*256a93a4Safresh1readable as possible, displaying no more complexity than absolutely 272*256a93a4Safresh1necessary to illustrate the concept at hand. 273*256a93a4Safresh1 274*256a93a4Safresh1For the sake of consistency within and across Perl's man pages, all 275*256a93a4Safresh1examples must adhere to the code-layout principles set out by 276*256a93a4Safresh1L<C<perlstyle>|perlstyle>. 277*256a93a4Safresh1 278*256a93a4Safresh1Sample code should deviate from these standards only when necessary: 279*256a93a4Safresh1during a demonstration of how Perl disregards whitespace, for example, 280*256a93a4Safresh1or to temporarily switch to two-column indentation for an unavoidably 281*256a93a4Safresh1verbose illustration. 282*256a93a4Safresh1 283*256a93a4Safresh1You may include comments within example code to further clarify or label 284*256a93a4Safresh1the code's behavior in-line. You may also use comments as placeholder 285*256a93a4Safresh1for code normally present but not relevant to the current topic, like 286*256a93a4Safresh1so: 287*256a93a4Safresh1 288*256a93a4Safresh1 while (my $line = <$fh>) { 289*256a93a4Safresh1 # 290*256a93a4Safresh1 # (Do something interesting with $line here.) 291*256a93a4Safresh1 # 292*256a93a4Safresh1 } 293*256a93a4Safresh1 294*256a93a4Safresh1Even the simplest code blocks often require the use of example 295*256a93a4Safresh1variables and subroutines, L<whose names you should choose with 296*256a93a4Safresh1care|/Use meaningful variable and symbol names in examples>. 297*256a93a4Safresh1 298*256a93a4Safresh1=head3 Inline code and literals 299*256a93a4Safresh1 300*256a93a4Safresh1Within a paragraph of text, use C<CE<lt>...E<gt>> when quoting or 301*256a93a4Safresh1referring to any bit of Perl code--even if it is only one character 302*256a93a4Safresh1long. 303*256a93a4Safresh1 304*256a93a4Safresh1For instance, when referring within an explanatory paragraph to Perl's 305*256a93a4Safresh1operator for adding two numbers together, you'd write "C<CE<lt>+E<gt>>". 306*256a93a4Safresh1 307*256a93a4Safresh1=head3 Function names 308*256a93a4Safresh1 309*256a93a4Safresh1Use C<CE<lt>...E<gt>> to render all Perl function names in monospace, 310*256a93a4Safresh1whenever they appear in text. 311*256a93a4Safresh1 312*256a93a4Safresh1Unless you need to specifically quote a function call with a list of 313*256a93a4Safresh1arguments, do not follow a function's name in text with a pair of empty 314*256a93a4Safresh1parentheses. That is, when referring in general to Perl's C<print> 315*256a93a4Safresh1function, write it as "C<print>", not "C<print()>". 316*256a93a4Safresh1 317*256a93a4Safresh1=head3 Function arguments 318*256a93a4Safresh1 319*256a93a4Safresh1Represent functions' expected arguments in all-caps, with no sigils, and 320*256a93a4Safresh1using C<CE<lt>...E<gt>> to render them in monospace. These arguments 321*256a93a4Safresh1should have short names making their nature and purpose clear. 322*256a93a4Safresh1Convention specifies a few ones commonly seen throughout Perl's 323*256a93a4Safresh1documentation: 324*256a93a4Safresh1 325*256a93a4Safresh1=over 326*256a93a4Safresh1 327*256a93a4Safresh1=item * 328*256a93a4Safresh1 329*256a93a4Safresh1EXPR 330*256a93a4Safresh1 331*256a93a4Safresh1The "generic" argument: any scalar value, or a Perl expression that 332*256a93a4Safresh1evaluates to one. 333*256a93a4Safresh1 334*256a93a4Safresh1=item * 335*256a93a4Safresh1 336*256a93a4Safresh1ARRAY 337*256a93a4Safresh1 338*256a93a4Safresh1An array, stored in a named variable. 339*256a93a4Safresh1 340*256a93a4Safresh1=item * 341*256a93a4Safresh1 342*256a93a4Safresh1HASH 343*256a93a4Safresh1 344*256a93a4Safresh1A hash, stored in a named variable. 345*256a93a4Safresh1 346*256a93a4Safresh1=item * 347*256a93a4Safresh1 348*256a93a4Safresh1BLOCK 349*256a93a4Safresh1 350*256a93a4Safresh1A curly-braced code block, or a subroutine reference. 351*256a93a4Safresh1 352*256a93a4Safresh1=item * 353*256a93a4Safresh1 354*256a93a4Safresh1LIST 355*256a93a4Safresh1 356*256a93a4Safresh1Any number of values, stored across any number of variables or 357*256a93a4Safresh1expressions, which the function will "flatten" and treat as a single 358*256a93a4Safresh1list. (And because it can contain any number of variables, it must be 359*256a93a4Safresh1the I<last> argument, when present.) 360*256a93a4Safresh1 361*256a93a4Safresh1=back 362*256a93a4Safresh1 363*256a93a4Safresh1When possible, give scalar arguments names that suggest their purpose 364*256a93a4Safresh1among the arguments. See, for example, L<C<substr>'s 365*256a93a4Safresh1documentation|perlfunc/substr>, whose 366*256a93a4Safresh1listed arguments include C<EXPR>, C<OFFSET>, C<LENGTH>, and C<REPLACEMENT>. 367*256a93a4Safresh1 368*256a93a4Safresh1=head3 Apostrophes, quotes, and dashes 369*256a93a4Safresh1 370*256a93a4Safresh1In Pod source, use straight quotes, and not "curly quotes": "Like 371*256a93a4Safresh1 this", not “like this”. The same goes for apostrophes: Here's a 372*256a93a4Safresh1 positive example, and here’s a negative one. 373*256a93a4Safresh1 374*256a93a4Safresh1Render em dashes as two hyphens--like this: 375*256a93a4Safresh1 376*256a93a4Safresh1 Render em dashes as two hyphens--like this. 377*256a93a4Safresh1 378*256a93a4Safresh1Leave it up to formatters to reformat and reshape these punctuation 379*256a93a4Safresh1marks as best fits their respective target media. 380*256a93a4Safresh1 381*256a93a4Safresh1=head3 Unix programs and C functions 382*256a93a4Safresh1 383*256a93a4Safresh1When referring to a Unix program or C function with its own man page 384*256a93a4Safresh1(outside of Perl's documentation), include its manual section number in 385*256a93a4Safresh1parentheses. For example: C<malloc(3)>, or C<mkdir(1)>. 386*256a93a4Safresh1 387*256a93a4Safresh1If mentioning this program for the first time within a man page or 388*256a93a4Safresh1section, make it a cross reference, e.g. C<LE<lt>malloc(3)E<gt>>. 389*256a93a4Safresh1 390*256a93a4Safresh1Do not otherwise style this text. 391*256a93a4Safresh1 392*256a93a4Safresh1=head3 Cross-references and hyperlinks 393*256a93a4Safresh1 394*256a93a4Safresh1Make generous use of Pod's C<LE<lt>...E<gt>> syntax to create hyperlinks 395*256a93a4Safresh1to other parts of the current man page, or to other documents entirely 396*256a93a4Safresh1-- whether elsewhere on the reader's computer, or somewhere on the 397*256a93a4Safresh1internet, via URL. 398*256a93a4Safresh1 399*256a93a4Safresh1Use C<LE<lt>...E<gt>> to link to another section of the current man page 400*256a93a4Safresh1when mentioning it, and make use of its page-and-section syntax to link to 401*256a93a4Safresh1the most specific section of a separate page within Perl's 402*256a93a4Safresh1documentation. Generally, the first time you refer to a specific 403*256a93a4Safresh1function, program, or concept within a certain page or section, consider 404*256a93a4Safresh1linking to its full documentation. 405*256a93a4Safresh1 406*256a93a4Safresh1Hyperlinks do not supersede other formatting required by this guide; Pod 407*256a93a4Safresh1allows nested text formats, and you should use this feature as needed. 408*256a93a4Safresh1 409*256a93a4Safresh1Here is an example sentence that mentions Perl's C<say> function, with a 410*256a93a4Safresh1link to its documentation section within the C<perlfunc> man page: 411*256a93a4Safresh1 412*256a93a4Safresh1 In version 5.10, Perl added support for the 413*256a93a4Safresh1 L<C<say>|perlfunc/say FILEHANDLE LIST> function. 414*256a93a4Safresh1 415*256a93a4Safresh1Note the use of the vertical pipe ("C<|>") to separate how the link will 416*256a93a4Safresh1appear to readers ("C<CE<lt>sayE<gt>>") from the full page-and-section specifier 417*256a93a4Safresh1that the formatter links to. 418*256a93a4Safresh1 419*256a93a4Safresh1=head3 Tables and diagrams 420*256a93a4Safresh1 421*256a93a4Safresh1Pod does not officially support tables. To best present tabular data, 422*256a93a4Safresh1include the table as both HTML and plain-text representations--the 423*256a93a4Safresh1latter as an indented code block. Use C<=begin> / C<=end> directives to 424*256a93a4Safresh1target these tables at C<html> and C<text> Pod formatters, respectively. 425*256a93a4Safresh1For example: 426*256a93a4Safresh1 427*256a93a4Safresh1 =head2 Table of fruits 428*256a93a4Safresh1 429*256a93a4Safresh1 =begin text 430*256a93a4Safresh1 431*256a93a4Safresh1 Name Shape Color 432*256a93a4Safresh1 ===================================== 433*256a93a4Safresh1 Apple Round Red 434*256a93a4Safresh1 Banana Long Yellow 435*256a93a4Safresh1 Pear Pear-shaped Green 436*256a93a4Safresh1 437*256a93a4Safresh1 =end text 438*256a93a4Safresh1 439*256a93a4Safresh1 =begin html 440*256a93a4Safresh1 441*256a93a4Safresh1 <table> 442*256a93a4Safresh1 <tr><th>Name</th><th>Shape</th><th>Color</th></tr> 443*256a93a4Safresh1 <tr><td>Apple</td><td>Round</td><td>Red</td></tr> 444*256a93a4Safresh1 <tr><td>Banana</td><td>Long</td><td>Yellow</td></tr> 445*256a93a4Safresh1 <tr><td>Pear</td><td>Pear-shaped</td><td>Green</td></tr> 446*256a93a4Safresh1 </table> 447*256a93a4Safresh1 448*256a93a4Safresh1 =end html 449*256a93a4Safresh1 450*256a93a4Safresh1The same holds true for figures and graphical illustrations. Pod does 451*256a93a4Safresh1not natively support inline graphics, but you can mix HTML C<<< <img> >>> tags 452*256a93a4Safresh1with monospaced text-art representations of those images' content. 453*256a93a4Safresh1 454*256a93a4Safresh1Due in part to these limitations, most Perl man pages use neither tables 455*256a93a4Safresh1nor diagrams. Like any other tool in your documentation toolkit, 456*256a93a4Safresh1however, you may consider their inclusion when they would improve an 457*256a93a4Safresh1explanation's clarity without adding to its complexity. 458*256a93a4Safresh1 459*256a93a4Safresh1=head2 Adding comments 460*256a93a4Safresh1 461*256a93a4Safresh1Like any other kind of source code, Pod lets you insert comments visible 462*256a93a4Safresh1only to other people reading the source directly, and ignored by the 463*256a93a4Safresh1formatting programs that transform Pod into various human-friendly 464*256a93a4Safresh1output formats (such as HTML or PDF). 465*256a93a4Safresh1 466*256a93a4Safresh1To comment Pod text, use the C<=for> and C<=begin> / C<=end> Pod 467*256a93a4Safresh1directives, aiming them at a (notional) formatter called "C<comment>". A 468*256a93a4Safresh1couple of examples: 469*256a93a4Safresh1 470*256a93a4Safresh1 =for comment Using "=for comment" like this is good for short, 471*256a93a4Safresh1 single-paragraph comments. 472*256a93a4Safresh1 473*256a93a4Safresh1 =begin comment 474*256a93a4Safresh1 475*256a93a4Safresh1 If you need to comment out more than one paragraph, use a 476*256a93a4Safresh1 =begin/=end block, like this. 477*256a93a4Safresh1 478*256a93a4Safresh1 None of the text or markup in this whole example would be visible to 479*256a93a4Safresh1 someone reading the documentation through normal means, so it's 480*256a93a4Safresh1 great for leaving notes, explanations, or suggestions for your 481*256a93a4Safresh1 fellow documentation writers. 482*256a93a4Safresh1 483*256a93a4Safresh1 =end comment 484*256a93a4Safresh1 485*256a93a4Safresh1In the tradition of any good open-source project, you should make free 486*256a93a4Safresh1but judicious use of comments to leave in-line "meta-documentation" as 487*256a93a4Safresh1needed for other Perl documentation writers (including your future 488*256a93a4Safresh1self). 489*256a93a4Safresh1 490*256a93a4Safresh1=head2 Perlfunc has special rules 491*256a93a4Safresh1 492*256a93a4Safresh1The L<C<perlfunc> man page|perlfunc>, an exhaustive reference of every 493*256a93a4Safresh1Perl built-in function, has a handful of formatting rules not seen 494*256a93a4Safresh1elsewhere in Perl's documentation. 495*256a93a4Safresh1 496*256a93a4Safresh1Software used during Perl's build process 497*256a93a4Safresh1(L<Pod::Functions|Pod::Functions>) parses this page according to certain 498*256a93a4Safresh1rules, in order to build separate man pages for each of Perl's 499*256a93a4Safresh1functions, as well as achieve other indexing effects. As such, 500*256a93a4Safresh1contributors to perlfunc must know about and adhere to its particular 501*256a93a4Safresh1rules. 502*256a93a4Safresh1 503*256a93a4Safresh1Most of the perfunc man page comprises a single list, found under the 504*256a93a4Safresh1header L<"Alphabetical Listing of Perl Functions"|perlfunc/Alphabetical 505*256a93a4Safresh1Listing of Perl Functions>. Each function reference is an entry on that 506*256a93a4Safresh1list, made of three parts, in order: 507*256a93a4Safresh1 508*256a93a4Safresh1=over 509*256a93a4Safresh1 510*256a93a4Safresh1=item 1. 511*256a93a4Safresh1 512*256a93a4Safresh1A list of C<=item> lines which each demonstrate, in template format, a 513*256a93a4Safresh1way to call this function. One line should exist for every combination 514*256a93a4Safresh1of arguments that the function accepts (including no arguments at all, 515*256a93a4Safresh1if applicable). 516*256a93a4Safresh1 517*256a93a4Safresh1If modern best practices prefer certain ways to invoke the function 518*256a93a4Safresh1over others, then those ways should lead the list. 519*256a93a4Safresh1 520*256a93a4Safresh1The first item of the list should be immediately followed by one or 521*256a93a4Safresh1more C<XE<lt>...E<gt>> terms listing index-worthy topics; if nothing 522*256a93a4Safresh1else, then the name of the function, with no arguments. 523*256a93a4Safresh1 524*256a93a4Safresh1=item 2. 525*256a93a4Safresh1 526*256a93a4Safresh1A C<=for> line, directed at C<Pod::Functions>, containing a one-line 527*256a93a4Safresh1description of what the function does. This is written as a phrase, led 528*256a93a4Safresh1with an imperative verb, with neither leading capitalization nor ending 529*256a93a4Safresh1punctuation. Examples include "quote a list of words" and "change a 530*256a93a4Safresh1filename". 531*256a93a4Safresh1 532*256a93a4Safresh1=item 3. 533*256a93a4Safresh1 534*256a93a4Safresh1The function's definition and reference material, including all 535*256a93a4Safresh1explanatory text and code examples. 536*256a93a4Safresh1 537*256a93a4Safresh1=back 538*256a93a4Safresh1 539*256a93a4Safresh1Complex functions that need their text divided into subsections (under 540*256a93a4Safresh1the principles of L<"Apply section-breaks and examples 541*256a93a4Safresh1generously"|/Apply section-breaks and examples generously>) may do so by 542*256a93a4Safresh1using sublists, with C<=item> elements as header text. 543*256a93a4Safresh1 544*256a93a4Safresh1A fictional function "C<myfunc>", which takes a list as an optional 545*256a93a4Safresh1argument, might have an entry in perlfunc shaped like this: 546*256a93a4Safresh1 547*256a93a4Safresh1 =item myfunc LIST 548*256a93a4Safresh1 X<myfunc> 549*256a93a4Safresh1 550*256a93a4Safresh1 =item myfunc 551*256a93a4Safresh1 552*256a93a4Safresh1 =for Pod::Functions demonstrate a function's perlfunc section 553*256a93a4Safresh1 554*256a93a4Safresh1 [ Main part of function definition goes here, with examples ] 555*256a93a4Safresh1 556*256a93a4Safresh1 =over 557*256a93a4Safresh1 558*256a93a4Safresh1 =item Legacy uses 559*256a93a4Safresh1 560*256a93a4Safresh1 [ Examples of deprecated syntax still worth documenting ] 561*256a93a4Safresh1 562*256a93a4Safresh1 =item Security considerations 563*256a93a4Safresh1 564*256a93a4Safresh1 [ And so on... ] 565*256a93a4Safresh1 566*256a93a4Safresh1 =back 567*256a93a4Safresh1 568*256a93a4Safresh1=head1 TONE AND STYLE 569*256a93a4Safresh1 570*256a93a4Safresh1=head2 Apply one of the four documentation modes 571*256a93a4Safresh1 572*256a93a4Safresh1Aside from "meta" documentation such as C<perlhist> or C<perlartistic>, 573*256a93a4Safresh1each of Perl's man pages should conform to one of the four documentation 574*256a93a4Safresh1"modes" suggested by L<I<The Documentation System> by Daniele 575*256a93a4Safresh1Procida|https://documentation.divio.com>. These include tutorials, 576*256a93a4Safresh1cookbooks, explainers, and references--terms that we define in further 577*256a93a4Safresh1detail below. 578*256a93a4Safresh1 579*256a93a4Safresh1Each mode of documentation speaks to a different audience--not just 580*256a93a4Safresh1people of different backgrounds and skill levels, but individual readers 581*256a93a4Safresh1whose needs from language documentation can shift depending upon 582*256a93a4Safresh1context. For example, a programmer with plenty of time to learn a new 583*256a93a4Safresh1concept about Perl can ease into a tutorial about it, and later expand 584*256a93a4Safresh1their knowledge further by studying an explainer. Later, that same 585*256a93a4Safresh1programmer, wading knee-deep in live code and needing only to look up 586*256a93a4Safresh1some function's exact syntax, will want to reach for a reference page 587*256a93a4Safresh1instead. 588*256a93a4Safresh1 589*256a93a4Safresh1Perl's documentation must strive to meet these different situational 590*256a93a4Safresh1expectations by limiting each man page to a single mode. This helps 591*256a93a4Safresh1writers ensure they provide readers with the documentation needed or 592*256a93a4Safresh1expected, despite ever-evolving situations. 593*256a93a4Safresh1 594*256a93a4Safresh1=head3 Tutorial 595*256a93a4Safresh1 596*256a93a4Safresh1A tutorial man page focuses on B<learning>, ideally by I<doing>. It 597*256a93a4Safresh1presents the reader with small, interesting examples that allow them to 598*256a93a4Safresh1follow along themselves using their own Perl interpreter. The tutorial 599*256a93a4Safresh1inspires comprehension by letting its readers immediately experience 600*256a93a4Safresh1(and experiment on) the concept in question. Examples include 601*256a93a4Safresh1C<perlxstut>, C<perlpacktut>, and 602*256a93a4Safresh1C<perlretut>. 603*256a93a4Safresh1 604*256a93a4Safresh1Tutorial man pages must strive for a welcoming and reassuring tone from 605*256a93a4Safresh1their outset; they may very well be the first things that a newcomer to 606*256a93a4Safresh1Perl reads, playing a significant role in whether they choose 607*256a93a4Safresh1to stick around. Even an experienced programmer can benefit from the 608*256a93a4Safresh1sense of courage imparted by a strong tutorial about a more advanced 609*256a93a4Safresh1topic. After completing a tutorial, a reader should feel like they've 610*256a93a4Safresh1been led from zero knowledge of its topic to having an invigorating 611*256a93a4Safresh1spark of basic understanding, excited to learn more and experiment 612*256a93a4Safresh1further. 613*256a93a4Safresh1 614*256a93a4Safresh1Tutorials can certainly use real-world examples when that helps make for 615*256a93a4Safresh1clear, relatable demonstrations, so long as they keep the focus on 616*256a93a4Safresh1teaching--more practical problem-solving should be left to the realm 617*256a93a4Safresh1of cookbooks (as described below). Tutorials also needn't concern 618*256a93a4Safresh1themselves with explanations into why or how things work beneath the 619*256a93a4Safresh1surface, or explorations of alternate syntaxes and solutions; these are 620*256a93a4Safresh1better handled by explainers and reference pages. 621*256a93a4Safresh1 622*256a93a4Safresh1=head3 Cookbook 623*256a93a4Safresh1 624*256a93a4Safresh1A cookbook man page focuses on B<results>. Just like its name suggests, 625*256a93a4Safresh1it presents succinct, step-by-step solutions to a variety of real-world 626*256a93a4Safresh1problems around some topic. A cookbook's code examples serve less to 627*256a93a4Safresh1enlighten and more to provide quick, paste-ready solutions that the 628*256a93a4Safresh1reader can apply immediately to the situation facing them. 629*256a93a4Safresh1 630*256a93a4Safresh1A Perl cookbook demonstrates ways that all the tools and techniques 631*256a93a4Safresh1explained elsewhere can work together in order to achieve practical 632*256a93a4Safresh1results. Any explanation deeper than that belongs in explainers and 633*256a93a4Safresh1reference pages, instead. (Certainly, a cookbook can cross-reference 634*256a93a4Safresh1other man pages in order to satisfy the curiosity of readers who, with 635*256a93a4Safresh1their immediate problems solved, wish to learn more.) 636*256a93a4Safresh1 637*256a93a4Safresh1The most prominent cookbook pages that ship with Perl itself are its 638*256a93a4Safresh1many FAQ pages, in particular C<perlfaq4> and up, which provide short 639*256a93a4Safresh1solutions to practical questions in question-and-answer style. 640*256a93a4Safresh1C<perlunicook> shows another example, containing a bevy of practical code 641*256a93a4Safresh1snippets for a variety of internationally minded text manipulations. 642*256a93a4Safresh1 643*256a93a4Safresh1(An aside: I<The Documentation System> calls this mode "how-to", but 644*256a93a4Safresh1Perl's history of creative cuisine prefers the more kitchen-ready term 645*256a93a4Safresh1that we employ here.) 646*256a93a4Safresh1 647*256a93a4Safresh1=head3 Reference 648*256a93a4Safresh1 649*256a93a4Safresh1A reference page focuses on B<description>. Austere, uniform, and 650*256a93a4Safresh1succinct, reference pages--often arranged into a whole section of 651*256a93a4Safresh1mutually similar subpages--lend themselves well to "random access" by 652*256a93a4Safresh1a reader who knows precisely what knowledge they need, requiring only 653*256a93a4Safresh1the minimum amount of information before returning to the task at hand. 654*256a93a4Safresh1 655*256a93a4Safresh1Perl's own best example of a reference work is C<perlfunc>, the 656*256a93a4Safresh1sprawling man page that details the operation of every function built 657*256a93a4Safresh1into Perl, with each function's documentation presenting the same kinds 658*256a93a4Safresh1of information in the same order as every other. For an example of a 659*256a93a4Safresh1shorter reference on a single topic, look at C<perlreref>. 660*256a93a4Safresh1 661*256a93a4Safresh1Module documentation--including that of all the modules listed in 662*256a93a4Safresh1L<C<perlmodlib>|perlmodlib>--also counts as reference. They follow 663*256a93a4Safresh1precepts similar to those laid down by the C<perlpodstyle> man page, such 664*256a93a4Safresh1as opening with an example-laden "SYNOPSIS" section, or featuring a 665*256a93a4Safresh1"METHODS" section that succinctly lists and defines an object-oriented 666*256a93a4Safresh1module's public interface. 667*256a93a4Safresh1 668*256a93a4Safresh1=head3 Explainer 669*256a93a4Safresh1 670*256a93a4Safresh1Explainer pages focus on B<discussion>. Each explainer dives as deep as 671*256a93a4Safresh1needed into some Perl-relevant topic, taking all the time and space 672*256a93a4Safresh1needed to give the reader a thorough understanding of it. Explainers 673*256a93a4Safresh1mean to impart knowledge through study. They don't assume that the 674*256a93a4Safresh1student has a Perl interpreter fired up and hungry for immediate examples 675*256a93a4Safresh1(as with a tutorial), or specific Perl problems that they need quick 676*256a93a4Safresh1answers for (which cookbooks and reference pages can help with). 677*256a93a4Safresh1 678*256a93a4Safresh1Outside of its reference pages, most of Perl's manual belongs to this 679*256a93a4Safresh1mode. This includes the majority of the man pages whose names start with 680*256a93a4Safresh1"C<perl>". A fine example is C<perlsyn>, the Perl Syntax page, which 681*256a93a4Safresh1explores the whys and wherefores of Perl's unique syntax in a 682*256a93a4Safresh1wide-ranging discussion laden with many references to the language's 683*256a93a4Safresh1history, culture, and driving philosophies. 684*256a93a4Safresh1 685*256a93a4Safresh1Perl's explainer pages give authors a chance to explore Perl's penchant 686*256a93a4Safresh1for L<TMTOWTDI|perlglossary/TMTOWTDI>, illustrating alternate and even 687*256a93a4Safresh1obscure ways to use the language feature under discussion. However, as 688*256a93a4Safresh1the remainder of this guide discusses, the ideal Perl documentation 689*256a93a4Safresh1manages to deliver its message clearly and concisely, and not confuse 690*256a93a4Safresh1mere wordiness for completeness. 691*256a93a4Safresh1 692*256a93a4Safresh1=head3 Further notes on documentation modes 693*256a93a4Safresh1 694*256a93a4Safresh1Keep in mind that the purpose of this categorization is not to dictate 695*256a93a4Safresh1content--a very thorough explainer might contain short reference 696*256a93a4Safresh1sections of its own, for example, or a reference page about a very 697*256a93a4Safresh1complex function might resemble an explainer in places (e.g. 698*256a93a4Safresh1L<C<open>|perlfunc/open FILEHANDLE,MODE,EXPR>). Rather, it makes sure 699*256a93a4Safresh1that the authors and contributors of any given man page agree on what 700*256a93a4Safresh1sort of audience that page addresses. 701*256a93a4Safresh1 702*256a93a4Safresh1If a new or otherwise uncategorized man page presents itself as 703*256a93a4Safresh1resistant to fitting into only one of the four modes, consider breaking 704*256a93a4Safresh1it up into separate pages. That may mean creating a new "C<perl[...]>" 705*256a93a4Safresh1man page, or (in the case of module documentation) making new packages 706*256a93a4Safresh1underneath that module's namespace that serve only to hold additional 707*256a93a4Safresh1documentation. For instance, C<Example::Module>'s reference documentation 708*256a93a4Safresh1might include a see-also link to C<Example::Module::Cookbook>. 709*256a93a4Safresh1 710*256a93a4Safresh1Perl's several man pages about Unicode--comprising a short tutorial, a 711*256a93a4Safresh1thorough explainer, a cookbook, and a FAQ--provide a fine example of 712*256a93a4Safresh1spreading a complicated topic across several man pages with different 713*256a93a4Safresh1and clearly indicated purposes. 714*256a93a4Safresh1 715*256a93a4Safresh1=head2 Assume readers' intelligence, but not their knowledge 716*256a93a4Safresh1 717*256a93a4Safresh1Perl has grown a great deal from its humble beginnings as a tool for 718*256a93a4Safresh1people already well versed in C programming and various Unix utilities. 719*256a93a4Safresh1Today, a person learning Perl might come from any social or 720*256a93a4Safresh1technological background, with a range of possible motivations 721*256a93a4Safresh1stretching far beyond system administration. 722*256a93a4Safresh1 723*256a93a4Safresh1Perl's core documentation must recognize this by making as few 724*256a93a4Safresh1assumptions as possible about the reader's prior knowledge. While you 725*256a93a4Safresh1should assume that readers of Perl's documentation are smart, curious, 726*256a93a4Safresh1and eager to learn, you should not confuse this for pre-existing 727*256a93a4Safresh1knowledge about any other technology, or even programming in 728*256a93a4Safresh1general--especially in tutorial or introductory material. 729*256a93a4Safresh1 730*256a93a4Safresh1=head3 Keep Perl's documentation about Perl 731*256a93a4Safresh1 732*256a93a4Safresh1Outside of pages tasked specifically with exploring Perl's relationship 733*256a93a4Safresh1with other programming languages, the documentation should keep the 734*256a93a4Safresh1focus on Perl. Avoid drawing analogies to other technologies that the 735*256a93a4Safresh1reader may not have familiarity with. 736*256a93a4Safresh1 737*256a93a4Safresh1For example, when documenting one of Perl's built-in functions, write as 738*256a93a4Safresh1if the reader is now learning about that function for the first time, in 739*256a93a4Safresh1any programming language. 740*256a93a4Safresh1 741*256a93a4Safresh1Choosing to instead compare it to an equivalent or underlying C function 742*256a93a4Safresh1will probably not illuminate much understanding in a contemporary 743*256a93a4Safresh1reader. Worse, this can risk leaving readers unfamiliar with C feeling 744*256a93a4Safresh1locked out from fully understanding of the topic--to say nothing of 745*256a93a4Safresh1readers new to computer programming altogether. 746*256a93a4Safresh1 747*256a93a4Safresh1If, however, that function's ties to its C roots can lead to deeper 748*256a93a4Safresh1understanding with practical applications for a Perl programmer, you may 749*256a93a4Safresh1mention that link after its more immediately useful documentation. 750*256a93a4Safresh1Otherwise, omit this information entirely, leaving it for other 751*256a93a4Safresh1documentation or external articles more concerned with examining Perl's 752*256a93a4Safresh1underlying implementation details. 753*256a93a4Safresh1 754*256a93a4Safresh1=head3 Deploy jargon when needed, but define it as well 755*256a93a4Safresh1 756*256a93a4Safresh1Domain-specific jargon has its place, especially within documentation. 757*256a93a4Safresh1However, if a man page makes use of jargon that a typical reader might 758*256a93a4Safresh1not already know, then that page should make an effort to define the 759*256a93a4Safresh1term in question early-on--either explicitly, or via cross reference. 760*256a93a4Safresh1 761*256a93a4Safresh1For example, Perl loves working with filehandles, and as such that word 762*256a93a4Safresh1appears throughout its documentation. A new Perl programmer arriving at 763*256a93a4Safresh1a man page for the first time is quite likely to have no idea what a 764*256a93a4Safresh1"filehandle" is, though. Any Perl man page mentioning filehandles 765*256a93a4Safresh1should, at the very least, hyperlink that term to an explanation 766*256a93a4Safresh1elsewhere in Perl's documentation. If appropriate--for example, in the 767*256a93a4Safresh1lead-in to L<C<open> function's detailed reference|perlfunc/open 768*256a93a4Safresh1FILEHANDLE,MODE,EXPR>--it can also include a very short in-place 769*256a93a4Safresh1definition of the concept for the reader's convenience. 770*256a93a4Safresh1 771*256a93a4Safresh1=head2 Use meaningful variable and symbol names in examples 772*256a93a4Safresh1 773*256a93a4Safresh1When quickly sketching out examples, English-speaking programmers have a 774*256a93a4Safresh1long tradition of using short nonsense words as placeholders for 775*256a93a4Safresh1variables and other symbols--such as the venerable C<foo>, C<bar>, and 776*256a93a4Safresh1C<baz>. Example code found in a programming language's official, 777*256a93a4Safresh1permanent documentation, however, can and should make an effort to 778*256a93a4Safresh1provide a little more clarity through specificity. 779*256a93a4Safresh1 780*256a93a4Safresh1Whenever possible, code examples should give variables, classes, and 781*256a93a4Safresh1other programmer-defined symbols names that clearly demonstrate their 782*256a93a4Safresh1function and their relationship to one another. For example, if an 783*256a93a4Safresh1example requires that one class show an "is-a" relationship with 784*256a93a4Safresh1another, consider naming them something like C<Apple> and C<Fruit>, rather 785*256a93a4Safresh1than C<Foo> and C<Bar>. Similarly, sample code creating an instance of 786*256a93a4Safresh1that class would do better to name it C<$apple>, rather than C<$baz>. 787*256a93a4Safresh1 788*256a93a4Safresh1Even the simplest examples benefit from clear language using concrete 789*256a93a4Safresh1words. Prefer a construct like C<for my $item (@items) { ... }> over 790*256a93a4Safresh1C<for my $blah (@blah) { ... }>. 791*256a93a4Safresh1 792*256a93a4Safresh1=head2 Write in English, but not just for English-speakers 793*256a93a4Safresh1 794*256a93a4Safresh1While this style guide does specify American English as the 795*256a93a4Safresh1documentation's language for the sake of internal consistency, authors 796*256a93a4Safresh1should avoid cultural or idiomatic references available only to 797*256a93a4Safresh1English-speaking Americans (or any other specific culture or society). 798*256a93a4Safresh1As much as possible, the language employed by Perl's core documentation 799*256a93a4Safresh1should strive towards cultural universality, if not neutrality. Regional 800*256a93a4Safresh1turns of phrase, examples drawing on popular-culture knowledge, and 801*256a93a4Safresh1other rhetorical techniques of that nature should appear sparingly, if 802*256a93a4Safresh1at all. 803*256a93a4Safresh1 804*256a93a4Safresh1Authors should feel free to let more freewheeling language flourish in 805*256a93a4Safresh1"second-order" documentation about Perl, like books, blog entries, and 806*256a93a4Safresh1magazine articles, published elsewhere and with a narrower readership in 807*256a93a4Safresh1mind. But Perl's own docs should use language as accessible and 808*256a93a4Safresh1welcoming to as wide an audience as possible. 809*256a93a4Safresh1 810*256a93a4Safresh1=head2 Omit placeholder text or commentary 811*256a93a4Safresh1 812*256a93a4Safresh1Placeholder text does not belong in the documentation that ships with 813*256a93a4Safresh1Perl. No section header should be followed by text reading only "Watch 814*256a93a4Safresh1this space", "To be included later", or the like. While Perl's source 815*256a93a4Safresh1files may shift and alter as much as any other actively maintained 816*256a93a4Safresh1technology, each released iteration of its technology should feel 817*256a93a4Safresh1complete and self-contained, with no such future promises or other loose 818*256a93a4Safresh1ends visible. 819*256a93a4Safresh1 820*256a93a4Safresh1Take advantage of Perl's regular release cycle. Instead of cluttering 821*256a93a4Safresh1the docs with flags promising more information later--the presence of 822*256a93a4Safresh1which do not help readers at all today--the documentation's 823*256a93a4Safresh1maintenance team should treat any known documentation absences as an 824*256a93a4Safresh1issue to address like any other in the Perl project. Let Perl's 825*256a93a4Safresh1contributors, testers, and release engineers address that need, and 826*256a93a4Safresh1resist the temptation to insert apologies, which have all the utility in 827*256a93a4Safresh1documentation as undeleted debug messages do in production code. 828*256a93a4Safresh1 829*256a93a4Safresh1=head2 Apply section-breaks and examples generously 830*256a93a4Safresh1 831*256a93a4Safresh1No matter how accessible their tone, the sight of monolithic blocks of 832*256a93a4Safresh1text in technical documentation can present a will-weakening challenge 833*256a93a4Safresh1for the reader. Authors can improve this situation through breaking long 834*256a93a4Safresh1passages up into subsections with short, meaningful headers. 835*256a93a4Safresh1 836*256a93a4Safresh1Since every section-header in Pod also acts as a potential end-point for 837*256a93a4Safresh1a cross-reference (made via Pod's C<LE<lt>...E<gt>> syntax), putting 838*256a93a4Safresh1plenty of subsections in your documentation lets other man pages more 839*256a93a4Safresh1precisely link to a particular topic. This creates hyperlinks directly 840*256a93a4Safresh1to the most appropriate section rather than to the whole page in 841*256a93a4Safresh1general, and helps create a more cohesive sense of a rich, consistent, 842*256a93a4Safresh1and interrelated manual for readers. 843*256a93a4Safresh1 844*256a93a4Safresh1Among the four documentation modes, sections belong more naturally in 845*256a93a4Safresh1tutorials and explainers. The step-by-step instructions of cookbooks, or 846*256a93a4Safresh1the austere definitions of reference pages, usually have no room for 847*256a93a4Safresh1them. But authors can always make exceptions for unusually complex 848*256a93a4Safresh1concepts that require further breakdown for clarity's sake. 849*256a93a4Safresh1 850*256a93a4Safresh1Example code, on the other hand, can be a welcome addition to any mode 851*256a93a4Safresh1of documentation. Code blocks help break up a man page visually, 852*256a93a4Safresh1reassuring the reader that no matter how deep the textual explanation 853*256a93a4Safresh1gets, they are never far from another practical example showing how it 854*256a93a4Safresh1all comes together using a small, easy-to-read snippet of tested Perl 855*256a93a4Safresh1code. 856*256a93a4Safresh1 857*256a93a4Safresh1=head2 Lead with common cases and best practices 858*256a93a4Safresh1 859*256a93a4Safresh1Perl famously gives programmers more than one way to do things. Like any 860*256a93a4Safresh1other long-lived programming language, Perl has also built up a large, 861*256a93a4Safresh1community-held notion of best practices, blessing some ways to do things 862*256a93a4Safresh1as better than others, usually for the sake of more maintainable code. 863*256a93a4Safresh1 864*256a93a4Safresh1=head3 Show the better ways first 865*256a93a4Safresh1 866*256a93a4Safresh1Whenever it needs to show the rules for a technique which Perl provides 867*256a93a4Safresh1many avenues for, the documentation should always lead with best 868*256a93a4Safresh1practices. And when discussing some part of the Perl toolkit with many 869*256a93a4Safresh1applications, the docs should begin with a demonstration of its 870*256a93a4Safresh1application to the most common cases. 871*256a93a4Safresh1 872*256a93a4Safresh1The C<open> function, for example, has myriad potential uses within Perl 873*256a93a4Safresh1programs, but I<most of the time> programmers--and especially those new 874*256a93a4Safresh1to Perl--turn to this reference because they simply wish to open a 875*256a93a4Safresh1file for reading or writing. For this reason, C<open>'s documentation 876*256a93a4Safresh1begins there, and only descends into the function's more obscure uses 877*256a93a4Safresh1after thoroughly documenting and demonstrating how it works in the 878*256a93a4Safresh1common case. Furthermore, while engaging in this demonstration, the 879*256a93a4Safresh1C<open> documentation does not burden the reader right away with detailed 880*256a93a4Safresh1explanations about calling C<open> via any route other than the 881*256a93a4Safresh1best-practice, three-argument style. 882*256a93a4Safresh1 883*256a93a4Safresh1=head3 Show the lesser ways when needed 884*256a93a4Safresh1 885*256a93a4Safresh1Sometimes, thoroughness demands documentation of deprecated techniques. 886*256a93a4Safresh1For example, a certain Perl function might have an alternate syntax now 887*256a93a4Safresh1considered outmoded and no longer best-practice, but which a maintainer 888*256a93a4Safresh1of a legacy project might quite reasonably encounter when exploring old 889*256a93a4Safresh1code. In this case, these features deserve documentation, but couched in 890*256a93a4Safresh1clarity that modern Perl avoids such structures, and does not recommend 891*256a93a4Safresh1their use in new projects. 892*256a93a4Safresh1 893*256a93a4Safresh1Another way to look at this philosophy (and one L<borrowed from our 894*256a93a4Safresh1friends|https://devguide.python.org/documenting/#affirmative-tone> on 895*256a93a4Safresh1Python's documentation team) involves writing while sympathizing with a 896*256a93a4Safresh1programmer new to Perl, who may feel uncertain about learning a complex 897*256a93a4Safresh1concept. By leading that concept's main documentation with clear, 898*256a93a4Safresh1positive examples, we can immediately give these readers a simple and 899*256a93a4Safresh1true picture of how it works in Perl, and boost their own confidence to 900*256a93a4Safresh1start making use of this new knowledge. Certainly we should include 901*256a93a4Safresh1alternate routes and admonitions as reasonably required, but we needn't 902*256a93a4Safresh1emphasize them. Trust the reader to understand the basics quickly, and 903*256a93a4Safresh1to keep reading for a deeper understanding if they feel so driven. 904*256a93a4Safresh1 905*256a93a4Safresh1=head2 Document Perl's present 906*256a93a4Safresh1 907*256a93a4Safresh1Perl's documentation should stay focused on Perl's present behavior, 908*256a93a4Safresh1with a nod to future directions. 909*256a93a4Safresh1 910*256a93a4Safresh1=head3 Recount the past only when necessary 911*256a93a4Safresh1 912*256a93a4Safresh1=for comment 913*256a93a4Safresh1The principles of this section caused a lot of lively discussion and 914*256a93a4Safresh1debate among p5p when first proposed in October 2020. I am keeping the 915*256a93a4Safresh1recommendations nonspecific, and expect this section to receive a lot of 916*256a93a4Safresh1further refinement as we start to apply it to core docs. 917*256a93a4Safresh1 918*256a93a4Safresh1When some Perl feature changes its behavior, documentation about 919*256a93a4Safresh1that feature should change too, and just as definitively. The docs have 920*256a93a4Safresh1no obligation to keep descriptions of past behavior hanging around, even if 921*256a93a4Safresh1attaching clauses like "Prior to version 5.10, [...]". 922*256a93a4Safresh1 923*256a93a4Safresh1Since Perl's core documentation is part of Perl's source distribution, 924*256a93a4Safresh1it enjoys the same benefits of versioning and version-control as the 925*256a93a4Safresh1source code of Perl itself. Take advantage of this, and update the text 926*256a93a4Safresh1boldly when needed. Perl's history remains safe, even when you delete or 927*256a93a4Safresh1replace outdated information from the current version's docs. 928*256a93a4Safresh1 929*256a93a4Safresh1Perl's docs can acknowledge or discuss former behavior when warranted, 930*256a93a4Safresh1including notes that some feature appeared in the language as of some 931*256a93a4Safresh1specific version number. Authors should consider applying principles 932*256a93a4Safresh1similar to those for deprecated techniques, L<as described above|/Show 933*256a93a4Safresh1the lesser ways when needed>: make the information present, but not 934*256a93a4Safresh1prominent. 935*256a93a4Safresh1 936*256a93a4Safresh1Otherwise, keep the past in the past. A manual uncluttered with 937*256a93a4Safresh1outdated instruction stays more succinct and relevant. 938*256a93a4Safresh1 939*256a93a4Safresh1=head3 Describe the uncertain future with care 940*256a93a4Safresh1 941*256a93a4Safresh1Perl features marked as "experimental"--those that generate warnings 942*256a93a4Safresh1when used in code not invoking the L<C<experimental>|experimental> 943*256a93a4Safresh1pragma--deserve documentation, but only in certain contexts, and even 944*256a93a4Safresh1then with caveats. These features represent possible new directions for 945*256a93a4Safresh1Perl, but they have unstable interfaces and uncertain future presence. 946*256a93a4Safresh1 947*256a93a4Safresh1The documentation should take both implications of "experimental" 948*256a93a4Safresh1literally. It should not discourage these features' use by programmers 949*256a93a4Safresh1who wish to try out new features in projects that can risk their 950*256a93a4Safresh1inherent instability; this experimentation can help Perl grow and 951*256a93a4Safresh1improve. By the same token, the docs should downplay these features' use 952*256a93a4Safresh1in just about every other context. 953*256a93a4Safresh1 954*256a93a4Safresh1Introductory or overview material should omit coverage of experimental 955*256a93a4Safresh1features altogether. 956*256a93a4Safresh1 957*256a93a4Safresh1More thorough reference materials or explanatory articles can include 958*256a93a4Safresh1experimental features, but needs to clearly mark them as such, and not 959*256a93a4Safresh1treat them with the same prominence as Perl's stable features. Using 960*256a93a4Safresh1unstable features seldom coincides with best practices, and 961*256a93a4Safresh1documentation that L<puts best practices first|/Lead with common cases 962*256a93a4Safresh1and best practices> should reflect this. 963*256a93a4Safresh1 964*256a93a4Safresh1=head2 The documentation speaks with one voice 965*256a93a4Safresh1 966*256a93a4Safresh1Even though it comes from many hands and minds, criss-crossing through 967*256a93a4Safresh1the many years of Perl's lifetime, the language's documentation should 968*256a93a4Safresh1speak with a single, consistent voice. With few exceptions, the docs 969*256a93a4Safresh1should avoid explicit first-person-singular statements, or similar 970*256a93a4Safresh1self-reference to any individual's contributor's philosophies or 971*256a93a4Safresh1experiences. 972*256a93a4Safresh1 973*256a93a4Safresh1Perl did begin life as a deeply personal expression by a single 974*256a93a4Safresh1individual, and this famously carried through the first revisions of its 975*256a93a4Safresh1documentation as well. Today, Perl's community understands that the 976*256a93a4Safresh1language's continued development and support comes from many people 977*256a93a4Safresh1working in concert, rather than any one person's vision or effort. Its 978*256a93a4Safresh1documentation should not pretend otherwise. 979*256a93a4Safresh1 980*256a93a4Safresh1The documentation should, however, carry forward the best tradition that 981*256a93a4Safresh1Larry Wall set forth in the language's earliest days: Write both 982*256a93a4Safresh1economically and with a humble, subtle wit, resulting in a technical 983*256a93a4Safresh1manual that mixes concision with a friendly approachability. It avoids 984*256a93a4Safresh1the dryness that one might expect from technical documentation, while 985*256a93a4Safresh1not leaning so hard into overt comedy as to distract and confuse from 986*256a93a4Safresh1the nonetheless-technical topics at hand. 987*256a93a4Safresh1 988*256a93a4Safresh1Like the best written works, Perl's documentation has a soul. Get 989*256a93a4Safresh1familiar with it as a reader to internalize its voice, and then find 990*256a93a4Safresh1your own way to express it in your own contributions. Writing clearly, 991*256a93a4Safresh1succinctly, and with knowledge of your audience's expectations will get 992*256a93a4Safresh1you most of the way there, in the meantime. 993*256a93a4Safresh1 994*256a93a4Safresh1Every line in the docs--whether English sentence or Perl 995*256a93a4Safresh1statement--should serve the purpose of bringing understanding to the 996*256a93a4Safresh1reader. Should a sentence exist mainly to make a wry joke that doesn't 997*256a93a4Safresh1further the reader's knowledge of Perl, set it aside, and consider 998*256a93a4Safresh1recasting it into a personal blog post or other article instead. 999*256a93a4Safresh1 1000*256a93a4Safresh1Write with a light heart, and a miserly hand. 1001*256a93a4Safresh1 1002*256a93a4Safresh1=head1 INDEX OF PREFERRED TERMS 1003*256a93a4Safresh1 1004*256a93a4Safresh1L<As noted above|/Choice of underlying style guide: CMOS>, this guide 1005*256a93a4Safresh1"inherits" all the preferred terms listed in the Chicago Manual of 1006*256a93a4Safresh1Style, 17th edition, and adds the following terms of particular interest 1007*256a93a4Safresh1to Perl documentation. 1008*256a93a4Safresh1 1009*256a93a4Safresh1=over 1010*256a93a4Safresh1 1011*256a93a4Safresh1=item built-in function 1012*256a93a4Safresh1 1013*256a93a4Safresh1Not "builtin". 1014*256a93a4Safresh1 1015*256a93a4Safresh1=item Darwin 1016*256a93a4Safresh1 1017*256a93a4Safresh1See L<macOS|/macOS>. 1018*256a93a4Safresh1 1019*256a93a4Safresh1=item macOS 1020*256a93a4Safresh1 1021*256a93a4Safresh1Use this term for Apple's operating system instead of "Mac OS X" or 1022*256a93a4Safresh1variants thereof. 1023*256a93a4Safresh1 1024*256a93a4Safresh1This term is also preferable to "Darwin", unless one needs to refer 1025*256a93a4Safresh1to macOS's Unix layer specifically. 1026*256a93a4Safresh1 1027*256a93a4Safresh1=item man page 1028*256a93a4Safresh1 1029*256a93a4Safresh1One unit of Unix-style documentation. Not "manpage". Preferable to "manual page". 1030*256a93a4Safresh1 1031*256a93a4Safresh1=item Perl; perl 1032*256a93a4Safresh1 1033*256a93a4Safresh1The name of the programming language is Perl, with a leading capital 1034*256a93a4Safresh1"P", and the remainder in lowercase. (Never "PERL".) 1035*256a93a4Safresh1 1036*256a93a4Safresh1The interpreter program that reads and executes Perl code is named 1037*256a93a4Safresh1"C<perl>", in lowercase and in monospace (as with any other command 1038*256a93a4Safresh1name). 1039*256a93a4Safresh1 1040*256a93a4Safresh1Generally, unless you are specifically writing about the 1041*256a93a4Safresh1command-line C<perl> program (as, for example, L<C<perlrun>|perlrun> 1042*256a93a4Safresh1does), use "Perl" instead. 1043*256a93a4Safresh1 1044*256a93a4Safresh1=item Perl 5 1045*256a93a4Safresh1 1046*256a93a4Safresh1Documentation need not follow Perl's name with a "5", or any other 1047*256a93a4Safresh1number, except during discussions of Perl's history, future plans, 1048*256a93a4Safresh1or explicit comparisons between major Perl versions. 1049*256a93a4Safresh1 1050*256a93a4Safresh1Before 2019, specifying "Perl 5" was sometimes needed to distinguish 1051*256a93a4Safresh1the language from Perl 6. With the latter's renaming to "Raku", this 1052*256a93a4Safresh1practice became unnecessary. 1053*256a93a4Safresh1 1054*256a93a4Safresh1=item Perl 6 1055*256a93a4Safresh1 1056*256a93a4Safresh1See L<Raku|/Raku>. 1057*256a93a4Safresh1 1058*256a93a4Safresh1=item Perl 5 Porters, the; porters, the; p5p 1059*256a93a4Safresh1 1060*256a93a4Safresh1The full name of the team responsible for Perl's ongoing maintenance 1061*256a93a4Safresh1and development is "the Perl 5 Porters", and this sobriquet should 1062*256a93a4Safresh1be spelled out in the first mention within any one document. It may 1063*256a93a4Safresh1thereafter call the team "the porters" or "p5p". 1064*256a93a4Safresh1 1065*256a93a4Safresh1Not "Perl5 Porters". 1066*256a93a4Safresh1 1067*256a93a4Safresh1=item program 1068*256a93a4Safresh1 1069*256a93a4Safresh1The most general descriptor for a stand-alone work made out of 1070*256a93a4Safresh1executable Perl code. Synonymous with, and preferable to, "script". 1071*256a93a4Safresh1 1072*256a93a4Safresh1=item Raku 1073*256a93a4Safresh1 1074*256a93a4Safresh1Perl's "sister language", whose homepage is L<https://raku.org>. 1075*256a93a4Safresh1 1076*256a93a4Safresh1Previously known as "Perl 6". In 2019, its design team renamed the 1077*256a93a4Safresh1language to better reflect its identity as a project independent from 1078*256a93a4Safresh1Perl. As such, Perl's documentation should always refer to this language 1079*256a93a4Safresh1as "Raku" and not "Perl 6". 1080*256a93a4Safresh1 1081*256a93a4Safresh1=item script 1082*256a93a4Safresh1 1083*256a93a4Safresh1See L<program|/program>. 1084*256a93a4Safresh1 1085*256a93a4Safresh1=item semicolon 1086*256a93a4Safresh1 1087*256a93a4Safresh1Perl code's frequently overlooked punctuation mark. Not "semi-colon". 1088*256a93a4Safresh1 1089*256a93a4Safresh1=item Unix 1090*256a93a4Safresh1 1091*256a93a4Safresh1Not "UNIX", "*nix", or "Un*x". Applicable to both the original operating 1092*256a93a4Safresh1system from the 1970s as well as all its conceptual descendants. You may 1093*256a93a4Safresh1simply write "Unix" and not "a Unix-like operating system" when 1094*256a93a4Safresh1referring to a Unix-like operating system. 1095*256a93a4Safresh1 1096*256a93a4Safresh1=back 1097*256a93a4Safresh1 1098*256a93a4Safresh1=head1 SEE ALSO 1099*256a93a4Safresh1 1100*256a93a4Safresh1=over 1101*256a93a4Safresh1 1102*256a93a4Safresh1=item * 1103*256a93a4Safresh1 1104*256a93a4Safresh1L<perlpod|perlpod> 1105*256a93a4Safresh1 1106*256a93a4Safresh1=item * 1107*256a93a4Safresh1 1108*256a93a4Safresh1L<perlpodstyle|perlpodstyle> 1109*256a93a4Safresh1 1110*256a93a4Safresh1=back 1111*256a93a4Safresh1 1112*256a93a4Safresh1=head1 AUTHOR 1113*256a93a4Safresh1 1114*256a93a4Safresh1This guide was initially drafted by Jason McIntosh 1115*256a93a4Safresh1(jmac@jmac.org), under a grant from The Perl Foundation. 1116*256a93a4Safresh1 1117*256a93a4Safresh1=for comment Additional contributors can get listed here (and this 1118*256a93a4Safresh1comment deleted), when there are some. 1119