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