PERLDOCSTYLE(1)

📦
version 5.42.3 · 21 versions
, in fedora 43, fedora 44

💖 PERLDOCSTYLE 💖

okay so welcome to perldocstyle, bestie — it lives in the Perl Programmers Reference Guide and it's literally the glow-up guide for how we write Perl's own docs. grab a snack, this one's long but it's so worth it 🫶

🌸 NAME 🌸

perldocstyle — a style guide for writing Perl's documentation. that's it, that's the name, slay 💅

✨ DESCRIPTION ✨

okay so this doc is the guide for authoring and maintaining all the documentation that ships with Perl. and "all the documentation" means a LOT, including:

  • The several dozen manual sections whose filenames begin with "perl", such as perlobj, perlre, and perlintro. (and yes — perl itself, the icon, the main character 👑)
  • The documentation for all the modules included with Perl (as listed by perlmodlib).
  • The hundreds of individually presented reference sections derived from the perlfunc file. hundreds. no cap.

from here on out, this guide calls user-manual section files man pages, per Unix convention. that's the vibe, we're keeping it 🎀

🧚 Purpose of this guide

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

sticking to these standards helps make sure any one part of Perl's manual has a tone and style that matches every other part. and like, same as the rest of the Perl project, the docs collection is an open-source project written over a long time by many people. keeping consistency across that much work is genuinely hard — this guide gives everyone a foundation so it's less of a struggle. it's giving teamwork, it's giving structure ✨

this helps readers — especially people who are brand new to Perl — feel more welcome and more engaged with Perl's documentation. and that helps the Perl project itself grow stronger, because you end up with a bigger, more diverse, more confident population of knowledgeable users. literally everyone wins 💖

🦋 Intended audience

anyone interested in contributing to Perl's core documentation should get familiar with the standards this guide lays out. periodt.

programmers who are documenting their own work, totally separate from the Perl project itself, might find this guide worthwhile too — especially if they want their work to extend the tone and style of Perl's own manual. we love a crossover episode 🌈

🌟 Status of this document

this guide was first drafted in late 2020, pulling from the documentation style guides of several open-source technologies contemporary with Perl. that included Python, Raku, Rust, and the Linux kernel. icons only.

the author intends to see this guide used as a starting place from which to launch a review of Perl's reams of extant documentation — and the expectation is that the people doing 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, it's evolving 🧬

🔥 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. they're basically childhood friends 💜

for a comprehensive reference to Pod syntax, go see "perlpod". but for the sake of reading this guide, it's enough to know the Pod syntax for section headers (=head2, et cetera) and for inline text formatting (C<like this>). that's all you need, fr fr.

Perl programmers also use Pod to document their own scripts, libraries, and modules. that particular use of Pod has its own style guide, outlined by "perlpodstyle". go check it out when you need it 📚

🌸 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. so that means "color" over "colour", "math" versus "maths", "the team has decided" and not "the team have decided", and so on. and so on. and so on 😌

we pick one style of English purely for consistency across Perl's documentation — kinda like how a software project might declare a four-space indentation standard, even when that doesn't actually affect how well the code compiles. both moves make things easier to read, because nobody's getting jump-scared by a mid-document format or style change. consistency ate 💅

contributors to Perl's documentation should note: this rule describes the ultimate, published output of the project. it 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 contribute in your own voice, we got you 🫶

💫 Other languages and translations

community-authored translations of Perl's documentation do exist, covering a variety of languages. the Perl project appreciates these translation efforts and promotes them when applicable — but it does not officially support or maintain any of them. just so we're clear on that 💀

that said, keeping Perl's documentation clear, simple, and short has a welcome side effect: it aids any such translation project. lowkey a freebie 🌍

(note that 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 they can make use of the full range of characters this encoding allows. the whole buffet, no restrictions ✨

as such, every core doc file (or the Pod section of every core module) should commence with an =encoding utf8 declaration. put it at the top, bestie, it's the opening line 🎬

👑 Choice of underlying style guide: CMOS

Perl's documentation uses the Chicago Manual of Style (https://www.chicagomanualofstyle.org) — CMOS, 17th Edition — as its baseline guide for style and grammar. while the document you're reading right now tries its best to be an adequate stand-alone style guide for documenting Perl, authors should consider CMOS the fallback authority for any pertinent topics not covered here. it's the parent document, the final boss of grammar 🏛️

because CMOS is not a free resource, access to it is not a prerequisite for contributing to Perl's documentation. 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.) no gatekeeping here 💖

🌈 Contributing to Perl's documentation

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

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

so yeah, the Perl project welcomes and values all community efforts to improve the language's documentation. every bit counts 🫶

Perl accepts documentation contributions through the same open-source project pipeline as code contributions. see "perlhack" for more info. same door, same vibe, come on in 🚪

💅 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. rules are cute when they're for a good reason ✨

🦋 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. (hence this guide using "man page" to refer to any one self-contained part of Perl's documentation.)

adhering to these conventions helps Pod formatters present a Perl man page's content in different contexts — whether that's a terminal, the web, or even print. many of the following requirements originate with "perlpodstyle", which derives its recommendations in turn from these well-established practices. traditions, but make it functional 🎀

⭐ Name

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

the first few lines of a notional page named perlpodexample:

=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 the page 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 are instead looking for a more basic reference or tutorial. be honest about who you're talking to, bestie 🗣️

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. highlights, not the whole photo album 📸

🌟 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<...>. link it or it didn't happen 🔗

what other sections to include depends entirely on 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. LOUD AND PROUD 📣

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. nest away, go wild 🪆

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. you do not need to include additional LICENSE or COPYRIGHT sections of your own. skip it, it's handled 💅

these man pages may optionally credit their primary author, or include a list of significant contributors, under AUTHOR or CONTRIBUTORS headings. note that the presence of authors' names does not preclude a given page from writing in a voice consistent with the rest of Perl's documentation. shout-out your people and stay on brand 🫶

note that 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. different rules, different playground.

🧚 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. seventy-two. count 'em 📏

please break paragraphs up into blocks of short lines, rather than "soft wrapping" paragraphs across hundreds of characters with no line breaks. nobody wants to scroll sideways through a wall of text, bestie 😭

🎀 Code blocks

(we're picking this one right up in the next part, stay with me 💖)

Just like the words around them, every code example needs to be as short and readable as humanly possible — no more complexity than it absolutely takes to show off the concept you're explaining. ✨

For consistency's sake, both inside one man page and across all of Perl's man pages, all examples must follow the code-layout principles laid out by perlstyle. 💅

Sample code should only stray from those standards when it has to: like when you're demonstrating how Perl disregards whitespace, or when you temporarily switch to two-column indentation for an unavoidably verbose illustration.

You can drop comments inside example code to clarify or label what the code does, in-line. You can also use comments as a placeholder for code that would normally be there but isn't relevant to the topic at hand, like so:

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

Even the simplest code blocks usually need example variables and subroutines, so choose those names with care, bestie. 💖

✨ Inline code and literals ✨

When you're inside a paragraph of text and you're quoting or referring to any bit of Perl code, wrap it in C<...> — yes, even if it's only one single character long. 🦋

So if you're writing an explanatory paragraph about Perl's operator for adding two numbers together, you'd write it as "C<+>". 🎀

💖 Function names 💖

Use C<...> to render all Perl function names in monospace, every single time they show up in text.

Unless you specifically need to quote a function call with a list of arguments, do not follow a function's name in text with a pair of empty parentheses. Like, when you're referring to Perl's print function in general, write it as print, not print(). periodt. 💅

🌸 Function arguments 🌸

Show functions' expected arguments in ALL-CAPS, with no sigils, and use C<...> to render them in monospace. Those argument names should be short and should make their nature and purpose obvious. Convention says a few of them show up over and over across 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 hold any number of variables, it must be the last argument, when present.) 👑

When you can, give scalar arguments names that hint at their purpose among the arguments. Peep substr's documentation, for example — its listed arguments include EXPR, OFFSET, LENGTH, and REPLACEMENT. ✨

🎀 Apostrophes, quotes, and dashes 🎀

In Pod source, use straight quotes, not "curly quotes": "Like this", not “like this”. Same energy for apostrophes: Here's a positive example, and here’s a negative one. 🙈

Render em dashes as two hyphens--like this:

Render em dashes as two hyphens--like this.

Then leave it up to formatters to reformat and reshape those punctuation marks however fits their own target media best. 💅

🦋 Unix programs and C functions 🦋

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

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

Do not style this text in any other way.

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 they're somewhere else on the reader's computer, or out on the internet via URL. 🌈

Use L<...> to link to another section of the current man page whenever you mention it, and use 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 override any other formatting this guide requires; Pod allows nested text formats, and you should use that feature whenever you need it. 💅

Here's 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.

Notice the vertical pipe (|) doing the separating — it splits how the link will appear to readers (C<say>) from the full page-and-section specifier that the formatter actually links to. 👑

🫶 Tables and diagrams 🫶

Pod does not officially support tables. To present tabular data as best you can, include the table as both an HTML representation and a plain-text representation — the latter as an indented code block. Use =begin / =end directives to target these tables at the 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

Same deal for figures and graphical illustrations. Pod doesn't natively support inline graphics, but you can mix HTML <img> tags with monospaced text-art versions of what those images contain. 🎨

Partly because of these limitations, most Perl man pages use neither tables nor diagrams. But like any other tool in your documentation toolkit, you may consider including them when they'd make an explanation clearer without making it more complicated. 💖

🌸 Adding comments 🌸

Like literally any other kind of source code, Pod lets you insert comments that are visible only to other people reading the source directly, and that get ignored by the formatting programs that turn Pod into all the various human-friendly output formats (HTML, PDF, that whole vibe).

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" for other Perl documentation writers (including your own future self, bestie — she will thank you). 🫶

💀 Perlfunc has special rules 💀

The perlfunc man page — the exhaustive reference of every single Perl built-in function — has a handful of formatting rules you won't see anywhere else in Perl's documentation.

Software used during Perl's build process (Pod::Functions) parses this page according to certain rules, so it can build separate man pages for each of Perl's functions, plus pull off some other indexing effects. Because of that, contributors to perlfunc must know about its particular rules and stick to them. no cap.

Most of the perfunc man page is one 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. Write it 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".
  3. The function's definition and reference material, including all the explanatory text and code examples. 💖

Complex functions that need their text split into subsections (per the principles of "Apply section-breaks and examples generously") can do that by using sublists, with =item elements as the 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 like perlhist or perlartistic, every one 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>. Those four are tutorials, cookbooks, explainers, and references — terms we define in more detail below. ✨

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

Perl's docs gotta meet all these different situational expectations, and the move is to limit each man page to a single mode. That way writers can make sure readers actually get the documentation they need (or expect), no matter how the situation keeps evolving. 💫

🎀 Tutorial 🎀

A tutorial man page is all about learning — ideally by doing. It hands the reader small, cute, interesting examples so they can follow along on their own Perl interpreter. The tutorial sparks comprehension by letting readers immediately experience (and experiment on) the concept in question. Examples: perlxstut, perlpacktut, and perlretut. ✨

Tutorial man pages have to come in warm and reassuring from the very first line — lowkey they might be the very first thing a Perl newcomer ever reads, and they play a huge role in whether that person decides to stick around. And even a seasoned programmer can catch a courage boost from a strong tutorial on a more advanced topic. After finishing a tutorial, the reader should feel like they got led from zero knowledge to an invigorating spark of basic understanding, hyped to learn more and experiment further. 🦋

Tutorials can totally use real-world examples when that makes for clearer, more relatable demos — as long as they keep the focus on teaching. The more practical problem-solving stuff gets left to cookbooks (next up below). And tutorials don't need to bother with explaining why or how things work under the surface, or exploring alternate syntaxes and solutions — that's explainer and reference territory.

🍓 Cookbook 🍓

A cookbook man page is all about results. Just like the name says, it serves up succinct, step-by-step solutions to a whole variety of real-world problems around some topic. The code examples aren't there so much to enlighten as to give you quick, paste-ready fixes you can apply immediately to the situation in front of you. 🥘

A Perl cookbook shows how all the tools and techniques explained elsewhere can work together to hit practical results. Anything deeper than that belongs in explainers and reference pages. (That said, a cookbook can absolutely cross-reference other man pages for readers whose immediate problem is solved and who wanna learn more.)

The most iconic cookbook pages shipping with Perl itself are its many FAQ pages, especially perlfaq4 and up, which give short solutions to practical questions in question-and-answer style. perlunicook is another one, packing a bevy of practical code snippets for a variety of internationally minded text manipulations. 🌈

(An aside: 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, succinct — reference pages (often arranged into a whole section of mutually similar subpages) lend themselves perfectly to "random access" by a reader who knows precisely what they need, only wanting the minimum amount of info before getting back to the task at hand. 👑

Perl's best example of a reference work is perlfunc, the sprawling man page detailing every function built into Perl, where each function's docs present the same kinds of information in the same order as every other. For a shorter single-topic reference, peep perlreref.

Module documentation — including all the modules listed in perlmodlib — counts as reference too. They follow precepts similar to the ones 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 🧠

Explainer pages are all about discussion. Each explainer dives as deep as needed into some Perl-relevant topic, taking all the time and space it needs to give the reader a thorough understanding of it. Explainers mean to impart knowledge through study. They don't assume the student has a Perl interpreter fired up and hungry for immediate examples (like a tutorial), or specific Perl problems they need quick answers for (which cookbooks and reference pages can help with). 💜

Outside of its reference pages, most of Perl's manual belongs to this mode — including the majority of the 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 laden with tons of 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, illustrating alternate and even obscure ways to use the language feature under discussion. But — as the rest of this guide discusses — the ideal Perl documentation manages to deliver its message clearly and concisely, and doesn't confuse mere wordiness for completeness.

🔍 Further notes on documentation modes 🔍

Keep in mind: the purpose of this categorization is not to dictate content. A very thorough explainer might contain short reference sections of its own, for example, or a reference page about a very complex function might resemble an explainer in places (e.g. open). What it actually does is make 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 just refuses to fit into only one of the four modes, consider breaking it up into separate pages. That might mean creating a new perl[...] man page, or (in the case of module documentation) making new packages underneath that module's namespace that serve 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 — comprising 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. 🦋

💖 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, someone 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. Assume readers of Perl's docs are smart, curious, and eager to learn — but don't confuse that for pre-existing knowledge about any other technology, or even programming in general. Especially in tutorial or introductory material. 🌸

🌱 Keep Perl's documentation about Perl 🌱

Outside of pages tasked specifically with exploring Perl's relationship with other programming languages, the documentation should keep the focus on Perl. Avoid drawing analogies to other technologies the reader may not be familiar with.

For example, when documenting one of Perl's built-in functions, write as if the reader is now learning about that function for the first time, in any programming language.

Choosing to compare it to an equivalent or underlying C function will probably not illuminate much understanding in a contemporary reader. Worse, it can risk leaving readers unfamiliar with C feeling locked out from fully understanding the topic — to say nothing of readers 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 information entirely, leaving it for other documentation or external articles 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 within documentation. However, if a man page makes use of jargon that a typical reader might not already know, then that page should make an effort to define the term in question early on — either explicitly, or via cross reference.

For example, Perl loves working with filehandles, and as such that word appears throughout its documentation. A new Perl programmer arriving at a man page for the first time is quite likely to have no idea what a "filehandle" is, though. Any Perl man page mentioning filehandles should, at the very least, hyperlink that term to an explanation elsewhere in Perl's documentation. If appropriate — for example, in the lead-in to the 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 — such as the venerable foo, bar, and baz. Example code found in a programming language's official, permanent documentation, however, 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. For example, if an example requires that one class 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) { ... }. 🫶

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

okay so first thing: this style guide says we're doing American English for the docs, periodt, because internal consistency is the vibe. BUT — and this is the important part, bestie — authors should avoid cultural or idiomatic references that only make sense to English-speaking Americans (or any other specific culture or society). Like, we want Perl's core documentation to strive towards cultural universality, if not outright neutrality. Regional turns of phrase, examples that lean on pop-culture knowledge, and other rhetorical techniques of that nature? Should appear sparingly, if at all. 💅

Authors can totally let their hair down with more freewheeling language in "second-order" documentation about Perl — think books, blog entries, magazine articles — stuff published elsewhere with a narrower readership in mind. But Perl's own docs? They need to use language that's as accessible and welcoming to as wide an audience as possible. 🫶

✨ Omit placeholder text or commentary ✨

Placeholder text? Not in the docs that ship with Perl. No section header should be followed by text that just says "Watch this space", "To be included later", or anything like that. Sure, Perl's source files may shift and alter like any other actively maintained technology, but every released iteration should feel complete and self-contained — no future promises, no loose ends visible. 💀

Take advantage of Perl's regular release cycle, okay? Instead of cluttering the docs with flags promising more info later (which helps literally no one today), the documentation's maintenance team should treat any known documentation absences as an issue to address like any other in the Perl project. Let Perl's contributors, testers, and release engineers handle that. And resist the temptation to insert apologies, which have all the utility in documentation as undeleted debug messages do in production code. 😭

✨ Apply section-breaks and examples generously ✨

No matter how accessible the tone is, monolithic blocks of text in technical documentation can be a will-weakening challenge for the reader. Authors can fix this by breaking long passages up into subsections with short, meaningful headers. 🎀

And here's a lowkey genius thing: every section-header in Pod also acts as a potential end-point for a cross-reference (made via Pod's L<...> syntax). So putting plenty of subsections in your docs lets other man pages link more precisely to a particular topic. That means hyperlinks go directly to the most appropriate section instead of the whole page in general — which helps create a more cohesive sense of a rich, consistent, and interrelated manual for readers. 👑

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

Example code, on the other hand? Welcome in any mode of documentation. Code blocks help break up a man page visually and reassure the reader that no matter how deep the textual explanation gets, 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 show the rules for a technique that Perl provides many avenues for, they should always lead with best practices. And when discussing some part of the Perl toolkit with many applications, the docs should begin with a demonstration of its application to the most common cases. 🌟

Take the open function, for example. It has myriad potential uses within Perl programs, but most of the time programmers — especially those new to Perl — turn to this reference because they simply wish to open a file for reading or writing. That's why open's documentation begins there, and only descends into the function's more obscure uses after thoroughly documenting and demonstrating how it works in the common case. Furthermore, while engaging in this demonstration, the open documentation does not burden the reader right away with detailed explanations about calling open via any route other than the best-practice, three-argument style. 💅

Show the lesser ways when needed

Sometimes, thoroughness demands documentation of deprecated techniques. For example, a certain Perl function might have an alternate syntax now considered outmoded and no longer best-practice, but which a maintainer of a legacy project might quite reasonably encounter when exploring old code. In this case, these features deserve documentation, but couched in clarity that modern Perl avoids such structures, and does not recommend their use in new projects. 🙈

Another way to look at this philosophy (and one borrowed from our friends over on Python's documentation team at https://devguide.python.org/documenting/#affirmative-tone) involves writing 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 can immediately give these readers a simple and true picture of how it works in Perl, and boost their own confidence to start making use of this new knowledge. Certainly we should include alternate routes and admonitions as reasonably required, but we needn't emphasize them. Trust the reader to understand the basics quickly, and to keep reading for a deeper understanding if they feel so driven. 🦋

✨ Document Perl's present ✨

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

Recount the past only when necessary

When some Perl feature changes its behavior, 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 attaching clauses like "Prior to version 5.10, [...]". 🗑️

Since Perl's core documentation is part of Perl's source distribution, it enjoys the same benefits of versioning and version-control as the source code of Perl itself. So take advantage of this, and update the text boldly when needed. Perl's history remains safe, even when you delete or replace outdated information from the current version's docs. 💾

Perl's docs can acknowledge or discuss former behavior when warranted, including notes that some feature appeared in the language as of some specific version number. Authors should consider applying principles similar to those for deprecated techniques, as 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" — those that generate warnings when used in code not 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 uncertain future presence. 😬

The documentation should take both implications of "experimental" literally. It should not discourage these features' use by programmers who wish to try out new features in projects that can risk their inherent instability; this experimentation can help 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 needs 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 this. 💅

✨ The documentation speaks with one voice ✨

Even though it comes from many hands and minds, criss-crossing through 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 similar self-reference to any individual contributor's philosophies or experiences. 👑

Perl did begin life as a deeply personal expression by a single individual, and this famously carried through the first revisions of its documentation as well. Today, Perl's community understands that the language's continued development and support comes from many people working in concert, rather than any one person's vision or effort. Its documentation should not 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, resulting in a technical manual that mixes concision with a friendly approachability. It avoids the dryness that one might expect from technical documentation, while not leaning so hard into overt comedy as to distract and confuse 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 bestie, so like, this guide "inherits" all the preferred terms listed in the Chicago Manual of Style, 17th edition, and then it adds these extra ones that are, like, super specific to Perl documentation. Periodt. 💅

built-in function

Not "builtin". 🚫

Darwin

See macOS. 👀

macOS

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

This term is also preferable to "Darwin", unless one needs to refer to macOS's Unix layer specifically. 💻

man page

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

Perl; perl

The name of the programming language is Perl, with a leading capital "P", and the remainder in lowercase. (Never "PERL".) 🐪

The interpreter program that reads and executes Perl code is named perl, in lowercase and in monospace (as with any other command name). ⌨️

Generally, unless you are specifically writing about the command-line perl program (as, for example, perlrun does), use "Perl" instead. ✨

Perl 5

Documentation need not 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 distinguish the language from Perl 6. With the latter's renaming to "Raku", this practice became unnecessary. 🕰️

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 in the first mention within any one document. It may thereafter 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 <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. As such, Perl's documentation should always refer to this language as "Raku" and not "Perl 6". 💫

script

See program. 📜

semicolon

Perl code's frequently overlooked punctuation mark. Not "semi-colon". ;) 😉

Unix

Not "UNIX", "*nix", or "Un*x". Applicable to both the original operating system from the 1970s as well as all its conceptual descendants. You may simply write "Unix" and not "a Unix-like operating system" when referring to a Unix-like operating system. 🐧

👀 SEE ALSO 👀

  • perlpod
  • perlpodstyle

💖 AUTHOR 💖

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

This page is from perl v5.42.3, dated 2026-08-03, and it's PERLDOCSTYLE(1). Stay slay, bestie! 💅✨

📦 where this page comes from