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