PERLDOCSTYLE(1perl)

✨ perldocstyle ✨

okay bestie, gather round, because we're about to talk about perldocstyle — aka A style guide for writing Perl's documentation 💅 and no, this is not the boring part, this is the part where the whole Perl manual gets its glow-up and stays consistent, fr fr.

---

🎀 NAME 🎀

perldocstyle — it's literally a whole style guide for writing Perl's documentation. that's it, that's the vibe. 👑

---

📖 DESCRIPTION 📖

okay so, real talk: this document is the guide for writing and maintaining all the documentation that ships with Perl 🫶. and when we say "all", we mean ALL of it, including:

• the several dozen manual sections whose filenames begin with perl, like perlobj, perlre, and perlintro (and yes, perl itself, the icon, the main character 👑).
• the documentation for every module included with Perl (as listed by perlmodlib).
• the hundreds of individually presented reference sections derived from the perlfunc file. hundreds. of them. 😭

and just so we're clear on terminology: this guide is gonna call user-manual section files man pages, per Unix convention. that's the word we're using, periodt.

💭 Purpose of this guide 💭

this style guide's whole goal is to establish standards, procedures, and philosophies that apply to Perl's core documentation.

why tho? because sticking to these standards makes sure that any one part of Perl's manual has a tone and style that matches all the other parts ✨. and like — same as the rest of the Perl project — the docs are an open-source thing authored over a long period of time by a lot of people. keeping consistency across that much work? lowkey a challenge. so this guide exists to give everyone a foundation and help make that difficulty less of an issue.

and the payoff is real: it helps readers — especially people who are brand new to Perl — feel more welcome and more engaged with the docs, and that in turn helps the Perl project itself grow stronger by having a bigger, more diverse, more confident crowd of knowledgeable users. ate. 💖

🫶 Intended audience 🫶

anyone who wants to contribute to Perl's core documentation should get familiar with the standards this guide lays out.

and also — programmers documenting their own work, totally separate from the Perl project, might find this guide worthwhile too, especially if they want their work to carry the same tone and style as Perl's own manual. sharing is caring 🦋.

📌 Status of this document 📌

this guide was initially drafted in late 2020, pulling from the documentation style guides of several open-source technologies contemporary with Perl. that list includes Python, Raku, Rust, and the Linux kernel. no cap.

the author intends this guide to be used as a starting place — a launchpad, a jumping-off point — for reviewing the reams and reams of existing Perl documentation. and the expectation is that whoever does that review should grow and modify this guide as needed to account for the requirements and quirks particular to Perl's programming manual. it's a living document, bestie 💫.

---

🌱 FUNDAMENTALS 🌱

🌸 Choice of markup: Pod 🌸

all of Perl's core documentation uses Pod (Plain Old Documentation), a simple markup language, to format its source text. Pod is similar in spirit to other contemporary lightweight markup technologies like Markdown and reStructuredText, and it's got a decades-long shared history with Perl itself. iconic behavior.

for a comprehensive reference to Pod syntax, go see perlpod 📚. and for the sake of reading this guide, you just need to be familiar with the Pod syntax for section headers (=head2, et cetera) and for inline text formatting (C<like this>). that's it, you're good.

Perl programmers also use Pod to document their own scripts, libraries, and modules — and that use of Pod has its own style guide, outlined by perlpodstyle. so if that's you, go check that one out too 🎀.

💬 Choice of language: American English 💬

Perl's core documentation is written in English, with a preference for American spelling of words and expression of phrases. that means color over colour, math versus maths, the team has decided and not the team have decided, and so on. 🇺🇸

we pick one style of English for the sake of consistency across Perl's documentation — much like how a software project might declare a four-space indentation standard, even when that doesn't affect how well the code compiles. both moves result in an easier read by avoiding jarring, mid-document changes in format or style. it's giving "we agreed on a vibe and we're sticking to it" 💅.

contributors to Perl's documentation should note that this rule describes the ultimate, published output of the project, and does not prescribe the dialect used within community contributions. the documentation team enthusiastically welcomes any English-language contributions, and will actively assist in Americanizing spelling and style when warranted. so don't stress, just write 🫶

🌍 Other languages and translations 🌍

community-authored translations of Perl's documentation do exist, covering a variety of languages. while the Perl project appreciates these translation efforts and promotes them when applicable, it does not officially support or maintain any of them. just being honest about the vibes.

that said, keeping Perl's documentation clear, simple, and short has a welcome side effect of aiding any such translation project. efficiency queen ✨.

note: the Chinese, Japanese, and Korean-language README files included with Perl's source distributions provide an exception to this choice of language — but these documents fall outside the scope of this guide.

🔤 Choice of encoding: UTF-8 🔤

Perl's core documentation files are encoded in UTF-8, and can make use of the full range of characters this encoding allows. the whole alphabet? the emoji potential? unmatched 🌈.

as such, every core doc file (or the Pod section of every core module) should commence with an =encoding utf8 declaration. don't forget it, it's the first step of the routine 🧖.

📚 Choice of underlying style guide: CMOS 📚

Perl's documentation uses the Chicago Manual of Style (CMOS), 17th Edition, as its baseline guide for style and grammar. the link they cite is https://www.chicagomanualofstyle.org, so that's your reference 🎀.

and while the document you're currently reading aims to serve as an adequate stand-alone style guide for documenting Perl, authors should consider CMOS the fallback authority for any pertinent topics not covered here.

now — because CMOS is not a free resource, access to it is not a prerequisite for contributing to Perl's documentation, okay? the doc team will help contributors learn about and apply its guidelines as needed. however, we do encourage anyone interested in significant doc contributions to obtain it or at least read through it. (copies are likely available through most public libraries, and CMOS-derived fundamentals can be found online as well.) so like, if you can, slay, but it's not a gate 🚪✨.

🤝 Contributing to Perl's documentation 🤝

Perl, like any programming language, is only as good as its documentation. Perl depends on clear, friendly, and thorough docs in order to:

• welcome brand-new users 👋
• teach and explain the language's various concepts and components 🧠
• serve as a lifelong reference for experienced Perl programmers 📖

so as you can imagine, the Perl project welcomes and values all community efforts to improve the language's documentation. we love to see it 💖.

Perl accepts documentation contributions through the same open-source project pipeline as code contributions. see perlhack for more information. go off 🚀.

---

🛠️ FORMATTING AND STRUCTURE 🛠️

this section details the specific Pod syntax and style that all core Perl documentation should adhere to, in the interest of consistency and readability. buckle up, this is the "getting ready" montage 💄.

🏗️ Document structure 🏗️

each individual work of core Perl documentation — whether it lives inside a .pod file or in the Pod section of a standard code module — patterns its structure after a number of long-time Unix man page conventions. (and that's exactly why this guide uses "man page" to refer to any one self-contained part of Perl's documentation. mystery solved 🔍.)

adhering to these conventions helps Pod formatters present a Perl man page's content in all sorts of different contexts — whether that's a terminal, the web, or even print. 📠✨ and a lot of the following requirements originate with perlpodstyle, which in turn derives its recommendations from these well-established practices. it's a whole lineage.

👑 Name 👑

after its =encoding utf8 declaration, a Perl man page must present a level-one header named NAME (literally, that exact word), followed by a paragraph containing the page's name and a very brief description.

the first few lines of a notional page named perlpodexample look like this:

=encoding utf8

=head1 NAME

perlpodexample - An example of formatting a manual page's title line

📝 Description and synopsis 📝

most Perl man pages also contain a DESCRIPTION section featuring a summary of, or introduction to, the document's content and purpose.

this section should also, one way or another, clearly identify the audience the page addresses — especially if it has expectations about the reader's prior knowledge 👀. for example, a man page that dives deep into the inner workings of Perl's regular expression engine should state its assumptions up front — and quickly redirect readers who were instead looking for a more basic reference or tutorial. no gatekeeping, just signposting 🪧.

reference pages, when appropriate, can precede the DESCRIPTION with a SYNOPSIS section that lists, within one or more code blocks, some very brief examples of the referenced feature's use. this section should show a handful of common-case and best-practice examples — not an exhaustive list of every obscure method or alternate syntax available. keep it snackable 🍓.

🧭 Other sections and subsections 🧭

pages should conclude, when appropriate, with a SEE ALSO section containing hyperlinks to relevant sections of Perl's manual, other Unix man pages, or appropriate web pages. hyperlink each such cross-reference via L<...> 🔗.

what other sections to include depends entirely upon the topic at hand. authors should feel free to include further =head1-level sections — whether other standard ones listed by perlpodstyle, or ones specific to the page's topic. in either case, render these top-level headings in all-capital letters. 📣

you may then include as many subsections beneath them as needed to meet the standards of clarity, accessibility, and cross-reference affinity suggested elsewhere in this guide. go wild, but on purpose 💅.

✍️ Author and copyright ✍️

in most circumstances, Perl's stand-alone man pages — those contained within .pod files — do not need to include any copyright or license information about themselves. their source Pod files are part of Perl's own core software repository, and that already covers them under the same copyright and license terms as Perl itself. so you do not need to include additional LICENSE or COPYRIGHT sections of your own. one less thing 💆.

these man pages may optionally credit their primary author, or include a list of significant contributors, under AUTHOR or CONTRIBUTORS headings. and note: the presence of authors' names does not preclude a given page from writing in a voice consistent with the rest of Perl's documentation. credit your faves AND keep the vibe consistent 🫶.

important: these guidelines do not apply to the core software modules that ship with Perl. those have their own standards for authorship and copyright statements, as found in perlpodstyle.

🎨 Formatting rules 🎨

📏 Line length and line wrap 📏

each line within a Perl man page's Pod source file should measure 72 characters or fewer in length.

please break paragraphs up into blocks of short lines, rather than "soft wrapping" paragraphs across hundreds of characters with no line breaks. we're not writing one long ribbon, bestie 🎀.

💻 Code blocks 💻

Just like the text around them, all code examples should be as short and readable as possible — displaying no more complexity than is absolutely necessary to illustrate the concept at hand. Like, keep it simple bestie, it's giving clarity 💅

For the sake of consistency within and across Perl's man pages, all examples must adhere to the code-layout principles set out by perlstyle.

Sample code should deviate from these standards only when necessary: during a demonstration of how Perl disregards whitespace, for example, or to temporarily switch to two-column indentation for an unavoidably verbose illustration.

You may include comments within example code to further clarify or label the code's behavior in-line. You may also use comments as placeholder for code normally present but not relevant to the current topic, like so:

while (my $line = <$fh>) {
    #
    # (Do something interesting with $line here.)
    #
}

Even the simplest code blocks often require the use of example variables and subroutines, whose names you should choose with care. Naming is an art, fr fr. ✨

🌸 Inline code and literals 🌸

Within a paragraph of text, use C<...> when quoting or referring to any bit of Perl code--even if it is only one character long.

For instance, when referring within an explanatory paragraph to Perl's operator for adding two numbers together, you'd write "C<+>". One character. Iconic. 👑

🌸 Function names 🌸

Use C<...> to render all Perl function names in monospace, whenever they appear in text.

Unless you need to specifically quote a function call with a list of arguments, do not follow a function's name in text with a pair of empty parentheses. That is, when referring in general to Perl's print function, write it as print, not print(). No little ghost parens hanging around, okay? 🫶

🌸 Function arguments 🌸

Represent functions' expected arguments in all-caps, with no sigils, and using C<...> to render them in monospace. These arguments should have short names making their nature and purpose clear. Convention specifies a few ones commonly seen throughout Perl's documentation:

• EXPR — The "generic" argument: any scalar value, or a Perl expression that evaluates to one.
• ARRAY — An array, stored in a named variable.
• HASH — A hash, stored in a named variable.
• BLOCK — A curly-braced code block, or a subroutine reference.
• LIST — Any number of values, stored across any number of variables or expressions, which the function will "flatten" and treat as a single list. (And because it can contain any number of variables, it must be the last argument, when present. 👈 no exceptions)

When possible, give scalar arguments names that suggest their purpose among the arguments. See, for example, substr's documentation, whose listed arguments include EXPR, OFFSET, LENGTH, and REPLACEMENT. So descriptive, so organized. 🎀

🌸 Apostrophes, quotes, and dashes 🌸

In Pod source, use straight quotes, and not "curly quotes": "Like this", not "like this". The same goes for apostrophes: Here's a positive example, and here's a negative one. 😭 (like literally, don't use the curly ones bestie)

Render em dashes as two hyphens--like this:

Render em dashes as two hyphens--like this.

Leave it up to formatters to reformat and reshape these punctuation marks as best fits their respective target media. Not your job, let them cook. 💅

🌸 Unix programs and C functions 🌸

When referring to a Unix program or C function with its own man page (outside of Perl's documentation), include its manual section number in parentheses. For example: malloc(3), or mkdir(1).

If mentioning this program for the first time within a man page or section, make it a cross reference, e.g. L<malloc(3)>.

Do not otherwise style this text.

🌸 Cross-references and hyperlinks 🌸

Make generous use of Pod's L<...> syntax to create hyperlinks to other parts of the current man page, or to other documents entirely--whether elsewhere on the reader's computer, or somewhere on the internet, via URL. Link everything, it's the moment. 🔗✨

Use L<...> to link to another section of the current man page when mentioning it, and make use of its page-and-section syntax to link to the most specific section of a separate page within Perl's documentation. Generally, the first time you refer to a specific function, program, or concept within a certain page or section, consider linking to its full documentation.

Hyperlinks do not supersede other formatting required by this guide; Pod allows nested text formats, and you should use this feature as needed. Stack those formats, queen. 💜

Here is an example sentence that mentions Perl's say function, with a link to its documentation section within the perlfunc man page:

In version 5.10, Perl added support for the
L<C<say>|perlfunc/say FILEHANDLE LIST> function.

Note the use of the vertical pipe ("|") to separate how the link will appear to readers ("C<say>") from the full page-and-section specifier that the formatter links to.

🌸 Tables and diagrams 🌸

Pod does not officially support tables. To best present tabular data, include the table as both HTML and plain-text representations--the latter as an indented code block. Use =begin / =end directives to target these tables at html and text Pod formatters, respectively. For example:

=head2 Table of fruits

=begin text

 Name           Shape           Color
 =====================================
 Apple          Round           Red
 Banana         Long            Yellow
 Pear           Pear-shaped     Green

=end text

=begin html

<table>
<tr><th>Name</th><th>Shape</th><th>Color</th></tr>
<tr><td>Apple</td><td>Round</td><td>Red</td></tr>
<tr><td>Banana</td><td>Long</td><td>Yellow</td></tr>
<tr><td>Pear</td><td>Pear-shaped</td><td>Green</td></tr>
</table>

=end html

The same holds true for figures and graphical illustrations. Pod does not natively support inline graphics, but you can mix HTML <img> tags with monospaced text-art representations of those images' content.

Due in part to these limitations, most Perl man pages use neither tables nor diagrams. Like any other tool in your documentation toolkit, however, you may consider their inclusion when they would improve an explanation's clarity without adding to its complexity.

🌈 Adding comments 🌈

Like any other kind of source code, Pod lets you insert comments visible only to other people reading the source directly, and ignored by the formatting programs that transform Pod into various human-friendly output formats (such as HTML or PDF).

To comment Pod text, use the =for and =begin / =end Pod directives, aiming them at a (notional) formatter called "comment". A couple of examples:

=for comment Using "=for comment" like this is good for short,
single-paragraph comments.

=begin comment

If you need to comment out more than one paragraph, use a
=begin/=end block, like this.

None of the text or markup in this whole example would be visible to
someone reading the documentation through normal means, so it's
great for leaving notes, explanations, or suggestions for your
fellow documentation writers.

=end comment

In the tradition of any good open-source project, you should make free but judicious use of comments to leave in-line "meta-documentation" as needed for other Perl documentation writers (including your future self). Hi future you, hope you're slaying 💖

🌈 Perlfunc has special rules 🌈

The perlfunc man page, an exhaustive reference of every Perl built-in function, has a handful of formatting rules not seen elsewhere in Perl's documentation.

Software used during Perl's build process (Pod::Functions) parses this page according to certain rules, in order to build separate man pages for each of Perl's functions, as well as achieve other indexing effects. As such, contributors to perlfunc must know about and adhere to its particular rules.

Most of the perfunc man page comprises a single list, found under the header "Alphabetical Listing of Perl Functions". Each function reference is an entry on that list, made of three parts, in order:

1. A list of =item lines which each demonstrate, in template format, a way to call this function. One line should exist for every combination of arguments that the function accepts (including no arguments at all, if applicable).

If modern best practices prefer certain ways to invoke the function over others, then those ways should lead the list.

The first item of the list should be immediately followed by one or more X<...> terms listing index-worthy topics; if nothing else, then the name of the function, with no arguments.

2. A =for line, directed at Pod::Functions, containing a one-line description of what the function does. This is written as a phrase, led with an imperative verb, with neither leading capitalization nor ending punctuation. Examples include "quote a list of words" and "change a filename". Short. Snappy. Done. ✨
3. The function's definition and reference material, including all explanatory text and code examples.

Complex functions that need their text divided into subsections (under the principles of "Apply section-breaks and examples generously") may do so by using sublists, with =item elements as header text.

A fictional function "myfunc", which takes a list as an optional argument, might have an entry in perlfunc shaped like this:

=item myfunc LIST
X<myfunc>

=item myfunc

=for Pod::Functions demonstrate a function's perlfunc section

[ Main part of function definition goes here, with examples ]

=over

=item Legacy uses

[ Examples of deprecated syntax still worth documenting ]

=item Security considerations

[ And so on... ]

=back

---

🌈 TONE AND STYLE 🌈

💖 Apply one of the four documentation modes 💖

Aside from "meta" documentation such as perlhist or perlartistic, each of Perl's man pages should conform to one of the four documentation "modes" suggested by The Documentation System by Daniele Procida <https://documentation.divio.com>. These include tutorials, cookbooks, explainers, and references--terms that we define in further detail below.

Each mode of documentation speaks to a different audience--not just people of different backgrounds and skill levels, but individual readers whose needs from language documentation can shift depending upon context. For example, a programmer with plenty of time to learn a new concept about Perl can ease into a tutorial about it, and later expand their knowledge further by studying an explainer. Later, that same programmer, wading knee-deep in live code and needing only to look up some function's exact syntax, will want to reach for a reference page instead. Same person, different moods, different pages. It's giving range. 🦋

okay so Perl's documentation has to ~vibe check~ itself against all these different situations, and the move is to lock each man page into ONE single mode. that way writers can actually make sure readers get what they came for, even when situations keep evolving on us like a group chat with 47 unread messages 💀.

🎀 Tutorial 🎀

a tutorial man page is all about learning, ideally by doing. it hands the reader small, interesting examples so they can follow along on their own Perl interpreter. the whole point is inspiring comprehension by letting readers immediately experience the concept — and poke at it — themselves. iconic examples: perlxstut, perlpacktut, and perlretut ✨.

tutorials have to bring a welcoming and reassuring tone from the jump, fr fr — because they might genuinely be the very first thing a Perl newcomer ever reads, and they play a significant role in whether that person decides to stick around 🥺. even a seasoned programmer can benefit from the little courage boost a strong tutorial about an advanced topic gives them. by the end, a reader should feel like they got walked from zero knowledge to having an invigorating spark of basic understanding, hyped to learn more and experiment further 🔥.

tutorials can absolutely use real-world examples when that makes a demo clearer and more relatable — as long as the focus stays on teaching. more practical, get-it-done problem-solving? that's cookbook territory (more below 👇). tutorials also don't need to bother with explaining why or how things work beneath the surface, or exploring alternate syntaxes and solutions — those live with the explainers and reference pages bestie 💅.

🍓 Cookbook 🍓

a cookbook man page is all about results. just like the name says, it drops succinct, step-by-step solutions to a whole buffet of real-world problems around some topic 🧁. the code examples aren't really there to enlighten — they're there to be quick, paste-ready solutions the reader can slap directly onto the problem in front of them.

a Perl cookbook shows off how all the tools and techniques explained elsewhere can work together to achieve practical results. any explanation deeper than that? belongs in explainers and reference pages instead. (to be clear though — a cookbook can cross-reference other man pages, so readers whose immediate problem is solved can go satisfy their curiosity 🫶.)

the most prominent cookbook pages shipping with Perl itself are its many FAQ pages — in particular perlfaq4 and up, which serve up short solutions to practical questions in good ol' question-and-answer style. perlunicook is another example, packing a bevy of practical code snippets for internationally minded text manipulations 🌈.

ok small aside, bestie: The Documentation System calls this mode "how-to", but Perl's history of creative cuisine prefers the more kitchen-ready term we use here 🍳✨.

📚 Reference 📚

a reference page is all about description. austere, uniform, and succinct — reference pages (usually living as a whole section of mutually similar subpages) are made for "random access" by a reader who already knows exactly what they need, so they only have to grab the minimum amount of info before getting back to the task at hand 🎯.

Perl's own best example of a reference work is perlfunc, the sprawling man page detailing the operation of every function built into Perl, where each function's documentation presents the same kinds of info in the same order as every other. for a shorter single-topic reference, peek at perlreref 👀.

Module documentation — including all the modules listed in perlmodlib — also counts as reference ✅. they follow precepts similar to those laid down by the perlpodstyle man page, like opening with an example-laden SYNOPSIS section, or featuring a METHODS section that succinctly lists and defines an object-oriented module's public interface.

🦋 Explainer 🦋

an explainer page is all about discussion. each one dives as deep as needed into some Perl-relevant topic, taking all the time and space necessary to give the reader a thorough understanding 💜. explainers mean to impart knowledge through study. they do NOT assume the student has a Perl interpreter fired up and hungry for immediate examples (that's a tutorial), or a specific Perl problem they need quick answers for (cookbooks and reference pages can help there).

outside of its reference pages, most of Perl's manual belongs to this mode — including the majority of man pages whose names start with "perl". a fine example is perlsyn, the Perl Syntax page, which explores the whys and wherefores of Perl's unique syntax in a wide-ranging discussion loaded with references to the language's history, culture, and driving philosophies 🌸.

Perl's explainer pages give authors a chance to explore Perl's penchant for TMTOWTDI, showing off alternate and even obscure ways to use the language feature in question. BUT — and the rest of this guide gets into it — the ideal Perl documentation still manages to deliver its message clearly and concisely, and does not confuse mere wordiness for completeness 💅.

✨ Further notes on documentation modes ✨

keep in mind that the point of this categorization is not to dictate content — a very thorough explainer might contain short reference sections of its own, and a reference page about a super complex function might resemble an explainer in places (e.g. open). what it's really doing is making sure the authors and contributors of any given man page agree on what sort of audience that page addresses 🫶.

if a new (or otherwise uncategorized) man page is being all stubborn and refusing to fit into just one of the four modes, consider breaking it up into separate pages 🔪✨. that might mean creating a new perl[...] man page, or (for module documentation) making new packages underneath that module's namespace that exist only to hold additional documentation. for instance, Example::Module's reference documentation might include a see-also link to Example::Module::Cookbook 👑

Perl's several man pages about Unicode — a short tutorial, a thorough explainer, a cookbook, and a FAQ 🎀 — are a fine example of spreading a complicated topic across several man pages with different and clearly indicated purposes. obsessed tbh.

🧠 Assume readers' intelligence, but not their knowledge 🧠

Perl has grown a great deal from its humble beginnings as a tool for people already well versed in C programming and various Unix utilities 🌱. today, a person learning Perl might come from any social or technological background, with a range of possible motivations stretching far beyond system administration.

Perl's core documentation has to recognize this by making as few assumptions as possible about the reader's prior knowledge. you should assume readers of Perl's docs are smart, curious, and eager to learn — but do NOT confuse that for pre-existing knowledge about any other technology, or even programming in general. ESPECIALLY not in tutorial or introductory material okay 🔥.

💖 Keep Perl's documentation about Perl 💖

outside of pages specifically tasked with exploring Perl's relationship with other programming languages, the documentation should keep the focus on Perl, periodt ✋. avoid drawing analogies to other technologies the reader might not be familiar with.

for example: when documenting one of Perl's built-in functions, write as if the reader is learning about that function for the first time ever, in any programming language. choosing instead to compare it to an equivalent or underlying C function probably won't illuminate much understanding in a contemporary reader. worse — it can risk leaving readers who don't know C feeling locked out of fully understanding the topic, to say nothing of readers brand new to computer programming altogether 😭.

if, however, that function's ties to its C roots can lead to deeper understanding with practical applications for a Perl programmer, you may mention that link after its more immediately useful documentation. otherwise? omit this info entirely and leave it for other documentation or external articles that are more concerned with examining Perl's underlying implementation details 💅.

💜 Deploy jargon when needed, but define it as well 💜

domain-specific jargon has its place, especially in documentation. BUT — if a man page uses jargon a typical reader might not already know, then that page should make an effort to define the term early on, either explicitly or via cross reference 👑.

for example, Perl loves working with filehandles, so that word shows up all over its documentation. but a new Perl programmer arriving at a man page for the very first time is quite likely to have zero idea what a "filehandle" even is 🥺. any Perl man page mentioning filehandles should, at the very least, hyperlink that term to an explanation elsewhere in Perl's documentation. and if appropriate — for example, in the lead-in to open function's detailed reference — it can also include a very short in-place definition of the concept for the reader's convenience ✨.

🌟 Use meaningful variable and symbol names in examples 🌟

when quickly sketching out examples, English-speaking programmers have a long tradition of using short nonsense words as placeholders for variables and other symbols — like the venerable foo, bar, and baz 💀. but example code found in a programming language's official, permanent documentation can and should make an effort to provide a little more clarity through specificity.

whenever possible, code examples should give variables, classes, and other programmer-defined symbols names that clearly demonstrate their function and their relationship to one another. like, if an example needs one class to show an "is-a" relationship with another, consider naming them something like Apple and Fruit, rather than Foo and Bar 🍎🍇. similarly, sample code creating an instance of that class would do better to name it $apple rather than $baz.

even the simplest examples benefit from clear language using concrete words. prefer a construct like:

for my $item (@items) { ... }

over:

for my $blah (@blah) { ... }

no cap, your future readers will thank you 🫶💖.

🌍 Write in English, but not just for English-speakers

okay so this style guide says American English is the language for the docs, for internal consistency reasons, bestie — but that does not mean authors get to sprinkle in cultural or idiomatic references that only land if you're a US English speaker. Or any other specific culture or society, for that matter. As much as humanly possible, the language in Perl's core docs should be aiming at cultural universality, if not full neutrality. Regional turns of phrase? Examples that lean on pop-culture knowledge? Other rhetorical tricks in that same family? They should show up sparingly. If at all. 👀

But like — authors should absolutely feel free to be more freewheeling and chaotic-good in "second-order" docs about Perl: books, blog entries, magazine articles, stuff published elsewhere with a narrower readership in mind. Go off, honestly. 💅 But Perl's own docs? Those need language that's as accessible and welcoming to as wide an audience as possible. No gatekeeping. Periodt.

🕳️ Omit placeholder text or commentary

Placeholder text has no business in the docs that ship with Perl. Hard no. No section header should be followed by text that just says "Watch this space", "To be included later", or anything like that. Listen — Perl's source files may shift and change as much as any other actively maintained technology, sure, but every released iteration should feel complete and self-contained. No future promises. No loose ends just hangin' out. ✨

So use Perl's regular release cycle, bestie. Instead of cluttering the docs with little flags promising more info later — which helps literally zero readers today — the documentation maintenance team should treat any known documentation gap as an issue to address like any other issue in the Perl project. Let the contributors, testers, and release engineers handle it. And resist that temptation to insert apologies, because apologies have exactly as much utility in documentation as undeleted debug messages do in production code. 😭 which is to say: none.

🎀 Apply section-breaks and examples generously

No matter how cute the tone is, a monolithic wall of text in technical documentation is a will-weakening challenge for the reader. Like, watching your soul leave your body. 💀 So authors can fix this by breaking long passages up into subsections with short, meaningful headers.

Also! Every single section-header in Pod doubles as a potential cross-reference end-point (you make those with Pod's L<...> syntax). So putting plenty of subsections in your documentation lets other man pages link to a specific topic super precisely. That means hyperlinks go straight to the most appropriate section instead of dumping the reader on the whole page in general. Which helps build a more cohesive vibe — a rich, consistent, interrelated manual. 🫶

Out of the four documentation modes, sections fit most naturally in tutorials and explainers. The step-by-step instructions of cookbooks, or the austere definitions of reference pages, usually don't have room for them. But authors can always make exceptions for unusually complex concepts that genuinely need further breakdown for clarity's sake.

Example code though? That's welcome in any mode of documentation. Code blocks break up a man page visually, and they reassure the reader that no matter how deep the text goes, they're never far from another practical example showing how it all comes together — using a small, easy-to-read snippet of tested Perl code. 🍓

👑 Lead with common cases and best practices

Perl famously gives programmers more than one way to do things. And like any other long-lived programming language, Perl has built up a big community-held notion of best practices — blessing some ways as better than others, usually for the sake of more maintainable code.

✨ Show the better ways first

Whenever the docs need to lay out the rules for a technique that Perl gives you a million avenues into, they should always lead with best practices. And when talking about some part of the Perl toolkit that has many applications, the docs should start with a demonstration of it applied to the most common cases.

Take open, for example. It has myriad potential uses in Perl programs, but most of the time programmers — especially folks new to Perl — reach for this reference because they simply want to open a file for reading or writing. So that's where open's documentation begins, and only after thoroughly documenting and demonstrating how it works in the common case does it descend into the function's more obscure uses. And while doing all that demonstrating? It doesn't burden the reader right away with detailed explanations about calling open via any route other than the best-practice, three-argument style. Nope. Common case first. 😌

🌈 Show the lesser ways when needed

Sometimes thoroughness demands documenting deprecated techniques. Like, a certain Perl function might have an alternate syntax that's now considered outmoded and no longer best-practice — but a maintainer of a legacy project might quite reasonably run into it while exploring old code. In that case those features deserve documentation, but it has to be couched in clarity that modern Perl avoids such structures, and does not recommend using them in new projects. ⚠️

Another way to look at this whole philosophy — and this one's borrowed from our friends over at <https://devguide.python.org/documenting/#affirmative-tone> on Python's documentation team — is to write while sympathizing with a programmer new to Perl, who may feel uncertain about learning a complex concept. By leading that concept's main documentation with clear, positive examples, we immediately give those readers a simple and true picture of how it works in Perl, and boost their confidence to start using this new knowledge. Obviously we should include alternate routes and admonitions when reasonably required, but we don't need to emphasize them. Trust the reader to get the basics quickly, and to keep reading for deeper understanding if they feel so driven. 🤝

⏳ Document Perl's present

Perl's documentation should stay focused on Perl's present behavior, with just a nod to future directions.

📜 Recount the past only when necessary

When some Perl feature changes its behavior, the documentation about that feature should change too — and just as definitively. The docs have no obligation to keep descriptions of past behavior hanging around, even if you're attaching clauses like "Prior to version 5.10, [...]".

Perl's core documentation is part of Perl's source distribution, so it enjoys the same versioning and version-control benefits as Perl's source code itself. Take advantage of that and update the text boldly when needed. Perl's history stays safe, bestie — even when you delete or replace outdated info from the current version's docs. 💾✨

Perl's docs can acknowledge or discuss former behavior when it's warranted — including notes that some feature appeared in the language as of some specific version number. Authors should consider applying principles similar to the ones for deprecated techniques, described above: make the information present, but not prominent.

Otherwise? Keep the past in the past. A manual uncluttered with outdated instruction stays more succinct and relevant.

🔮 Describe the uncertain future with care

Perl features marked as "experimental" — the ones that generate warnings when used in code that isn't invoking the experimental pragma — deserve documentation, but only in certain contexts, and even then with caveats. These features represent possible new directions for Perl, but they have unstable interfaces and an uncertain future presence.

The documentation should take both implications of "experimental" literally:

• It should not discourage programmers who want to try these features out in projects that can risk their inherent instability — that experimentation helps Perl grow and improve.
• By the same token, the docs should downplay these features' use in just about every other context.

Introductory or overview material should omit coverage of experimental features altogether. 🚫

More thorough reference materials or explanatory articles can include experimental features, but need to clearly mark them as such — and not treat them with the same prominence as Perl's stable features. Using unstable features seldom coincides with best practices, and documentation that puts best practices first should reflect that.

🫂 The documentation speaks with one voice

Even though it comes from many hands and minds, criss-crossing through all the many years of Perl's lifetime, the language's documentation should speak with a single, consistent voice. With few exceptions, the docs should avoid explicit first-person-singular statements, or any similar self-reference to an individual contributor's philosophies or experiences.

Perl did begin life as a deeply personal expression by a single individual, and that famously carried through the first revisions of its documentation too. But today, Perl's community understands that the language's continued development and support comes from many people working in concert — not from any one person's vision or effort. The documentation shouldn't pretend otherwise. 💖

The documentation should, however, carry forward the best tradition that Larry Wall set forth in the language's earliest days: write both economically and with a humble, subtle wit. The result is a technical manual that mixes concision with a friendly approachability. It dodges the dryness you might expect from technical documentation, while not leaning so hard into overt comedy that it distracts and confuses readers from the nonetheless-technical topics at hand.

Like the best written works, Perl's documentation has a soul. Get familiar with it as a reader to internalize its voice, and then find your own way to express it in your own contributions. Writing clearly, succinctly, and with knowledge of your audience's expectations will get you most of the way there in the meantime. 🧚

Every line in the docs — whether English sentence or Perl statement — should serve the purpose of bringing understanding to the reader. Should a sentence exist mainly to make a wry joke that doesn't further the reader's knowledge of Perl, set it aside, and consider recasting it into a personal blog post or other article instead. 🙈

Write with a light heart, and a miserly hand. 💜

---

✨ INDEX OF PREFERRED TERMS ✨

okay so, as noted above, this guide lowkey "inherits" every single preferred term listed in the Chicago Manual of Style, 17th edition 💅 and then adds its own little stash of terms that are of particular interest to Perl documentation. Here they all are, bestie — no skips, no cap 👑

---

built-in function 🧩

Not "builtin".

Darwin 🍎

See macOS.

macOS 💻

Use this term for Apple's operating system instead of "Mac OS X" or any variants thereof.

This term is also preferable to "Darwin", unless you actually need to refer specifically to macOS's Unix layer.

man page 📖

One unit of Unix-style documentation. Not "manpage". Preferable to "manual page".

Perl; perl 🐪

The name of the programming language is Perl — leading capital "P", everything else lowercase. (Never "PERL", that's giving shouty, not giving language name 😭)

The interpreter program that reads and executes Perl code is named perl, in lowercase and in monospace, just like any other command name.

Generally, unless you're specifically writing about the command-line perl program (like, for example, perlrun does), use "Perl".

Perl 5 5️⃣

Documentation does not need to follow Perl's name with a "5", or any other number, except during discussions of Perl's history, future plans, or explicit comparisons between major Perl versions.

Before 2019, specifying "Perl 5" was sometimes needed to keep the language separate from Perl 6. With the latter's renaming to "Raku", this practice became unnecessary. periodt.

Perl 6

See Raku.

Perl 5 Porters, the; porters, the; p5p 👑

The full name of the team responsible for Perl's ongoing maintenance and development is "the Perl 5 Porters", and this sobriquet should be spelled out on the first mention within any one document. After that, it may call the team "the porters" or "p5p".

Not "Perl5 Porters".

program 🛠️

The most general descriptor for a stand-alone work made out of executable Perl code. Synonymous with, and preferable to, "script".

Raku 🦋

Perl's "sister language", whose homepage is at https://raku.org.

Previously known as "Perl 6". In 2019, its design team renamed the language to better reflect its identity as a project independent from Perl. So Perl's documentation should always refer to this language as "Raku" and never as "Perl 6". 💅

script 📜

See program.

semicolon ;

Perl code's frequently overlooked punctuation mark. Not "semi-colon". (she's small, she's mighty, she's required 🫶)

Unix 🖥️

Not "UNIX", not "*nix", not "Un*x". This applies to both the original operating system from the 1970s and all of its conceptual descendants. You may simply write "Unix" and not "a Unix-like operating system" when you're referring to a Unix-like operating system. slay.

---

👀 SEE ALSO

• perlpod
• perlpodstyle

---

🌸 AUTHOR

This guide was initially drafted by Jason McIntosh (jmac@jmac.org), under a grant from The Perl Foundation.

---

and that's the whole page, bestie 🎀 one (1) last thing: this whole thing is version perl v5.44.0, dated 2026-10-17, and it lives at PERLDOCSTYLE(1perl). read it, love it, cite it, go write docs that ate 🔥💜