PERLDOCSTYLE(1) Perl Programmers Reference Guide PERLDOCSTYLE(1) #
PERLDOCSTYLE(1) Perl Programmers Reference Guide PERLDOCSTYLE(1)
NNAAMMEE #
perldocstyle - A style guide for writing Perl's documentation
DDEESSCCRRIIPPTTIIOONN #
This document is a guide for the authorship and maintenance of the
documentation that ships with Perl. This includes the following:
• The several dozen manual sections whose filenames begin with
""perl"", such as "perlobj", "perlre", and "perlintro". (And, yes,
"perl".)
• 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.
This guide will hereafter refer to user-manual section files as _m_a_n
_p_a_g_e_s, per Unix convention.
PPuurrppoossee ooff tthhiiss gguuiiddee This style guide aims to establish standards, procedures, and philosophies applicable to Perl’s core documentation.
Adherence to these standards will help ensure that any one part of Perl's
manual has a tone and style consistent with that of any other. As with
the rest of the Perl project, the language's documentation collection is
an open-source project authored over a long period of time by many
people. Maintaining consistency across such a wide swath of work presents
a challenge; this guide provides a foundation to help mitigate this
difficulty.
This will help its readers--especially those new to Perl--to feel more
welcome and engaged with Perl's documentation, and this in turn will help
the Perl project itself grow stronger through having a larger, more
diverse, and more confident population of knowledgeable users.
IInntteennddeedd aauuddiieennccee Anyone interested in contributing to Perl’s core documentation should familiarize themselves with the standards outlined by this guide.
Programmers documenting their own work apart from the Perl project itself
may also find this guide worthwhile, especially if they wish their work
to extend the tone and style of Perl's own manual.
SSttaattuuss ooff tthhiiss ddooccuummeenntt This guide was initially drafted in late 2020, drawing from the documentation style guides of several open-source technologies contemporary with Perl. This has included Python, Raku, Rust, and the Linux kernel.
The author intends to see this guide used as starting place from which to
launch a review of Perl's reams of extant documentation, with the
expectation that those conducting this review should grow and modify this
guide as needed to account for the requirements and quirks particular to
Perl's programming manual.
FFUUNNDDAAMMEENNTTAALLSS #
CChhooiiccee ooff mmaarrkkuupp:: PPoodd 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, such as Markdown and reStructuredText, and has a decades-long shared history with Perl itself.
For a comprehensive reference to Pod syntax, see "perlpod". For the sake
of reading this guide, familiarity with the Pod syntax for section
headers ("=head2", et cetera) and for inline text formatting ("C<like
this>") should suffice.
Perl programmers also use Pod to document their own scripts, libraries,
and modules. This use of Pod has its own style guide, outlined by
"perlpodstyle".
CChhooiiccee ooff llaanngguuaaggee:: AAmmeerriiccaann EEnngglliisshh 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 name one style of English for the sake of consistency across Perl's
documentation, much as a software project might declare a four-space
indentation standard--even when that doesn't affect how well the code
compiles. Both efforts result in an easier read by avoiding jarring, mid-
document changes in format or style.
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.
_O_t_h_e_r _l_a_n_g_u_a_g_e_s _a_n_d _t_r_a_n_s_l_a_t_i_o_n_s
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.
That said, keeping Perl's documentation clear, simple, and short has a
welcome side effect of aiding any such translation project.
(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.)
CChhooiiccee ooff eennccooddiinngg:: UUTTFF--88 Perl’s core documentation files are encoded in UTF-8, and can make use of the full range of characters this encoding allows.
As such, every core doc file (or the Pod section of every core module)
should commence with an "=encoding utf8" declaration.
CChhooiiccee ooff uunnddeerrllyyiinngg ssttyyllee gguuiiddee:: CCMMOOSS 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 are currently reading endeavors to serve as an adequate stand-alone style guide for the purposes of documenting Perl, authors should consider CMOS the fallback authority for any pertinent topics not covered here.
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
or at least read through CMOS. (Copies are likely available through most
public libraries, and CMOS-derived fundamentals can be found online as
well.)
CCoonnttrriibbuuttiinngg ttoo PPeerrll’’ss ddooccuummeennttaattiioonn Perl, like any programming language, is only as good as its documentation. Perl depends upon clear, friendly, and thorough documentation in order 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. As such, the Perl project welcomes and values all community efforts to improve the language’s documentation.
Perl accepts documentation contributions through the same open-source
project pipeline as code contributions. See "perlhack" for more
information.
FFOORRMMAATTTTIINNGG AANNDD SSTTRRUUCCTTUURREE #
This section details specific Pod syntax and style that all core Perl
documentation should adhere to, in the interest of consistency and
readability.
DDooccuummeenntt ssttrruuccttuurree Each individual work of core Perl documentation, whether contained within 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’s use of “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 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.
_N_a_m_e
After its "=encoding utf8" declaration, a Perl man page _m_u_s_t 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
_D_e_s_c_r_i_p_t_i_o_n _a_n_d _s_y_n_o_p_s_i_s
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 that 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 are instead
looking for a more basic reference or tutorial.
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, rather than an
exhaustive list of every obscure method or alternate syntax available.
_O_t_h_e_r _s_e_c_t_i_o_n_s _a_n_d _s_u_b_s_e_c_t_i_o_n_s
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.
_A_u_t_h_o_r _a_n_d _c_o_p_y_r_i_g_h_t
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.
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.
Note that these guidelines do not apply to the core software modules that
ship with Perl. These have their own standards for authorship and
copyright statements, as found in "perlpodstyle".
FFoorrmmaattttiinngg rruulleess _L_i_n_e _l_e_n_g_t_h _a_n_d _l_i_n_e _w_r_a_p
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.
_C_o_d_e _b_l_o_c_k_s
Just like the text around them, all code examples should be as short and
readable as possible, displaying no more complexity than absolutely
necessary to illustrate the concept at hand.
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.
_I_n_l_i_n_e _c_o_d_e _a_n_d _l_i_t_e_r_a_l_s
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<+>"".
_F_u_n_c_t_i_o_n _n_a_m_e_s
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()"".
_F_u_n_c_t_i_o_n _a_r_g_u_m_e_n_t_s
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 _l_a_s_t argument, when present.)
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".
_A_p_o_s_t_r_o_p_h_e_s_, _q_u_o_t_e_s_, _a_n_d _d_a_s_h_e_s
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.
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.
_U_n_i_x _p_r_o_g_r_a_m_s _a_n_d _C _f_u_n_c_t_i_o_n_s
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.
_C_r_o_s_s_-_r_e_f_e_r_e_n_c_e_s _a_n_d _h_y_p_e_r_l_i_n_k_s
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. #
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.
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.
_T_a_b_l_e_s _a_n_d _d_i_a_g_r_a_m_s
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.
AAddddiinngg ccoommmmeennttss 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).
PPeerrllffuunncc hhaass ssppeecciiaall rruulleess 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".
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
TTOONNEE AANNDD SSTTYYLLEE #
AAppppllyy oonnee ooff tthhee ffoouurr ddooccuummeennttaattiioonn mmooddeess 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 _T_h_e _D_o_c_u_m_e_n_t_a_t_i_o_n _S_y_s_t_e_m 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.
Perl's documentation must strive to meet these different situational
expectations by limiting each man page to a single mode. This helps
writers ensure they provide readers with the documentation needed or
expected, despite ever-evolving situations.
_T_u_t_o_r_i_a_l
A tutorial man page focuses on lleeaarrnniinngg, ideally by _d_o_i_n_g. It presents
the reader with small, interesting examples that allow them to follow
along themselves using their own Perl interpreter. The tutorial inspires
comprehension by letting its readers immediately experience (and
experiment on) the concept in question. Examples include "perlxstut",
"perlpacktut", and "perlretut".
Tutorial man pages must strive for a welcoming and reassuring tone from
their outset; they may very well be the first things that a newcomer to
Perl reads, playing a significant role in whether they choose to stick
around. Even an experienced programmer can benefit from the sense of
courage imparted by a strong tutorial about a more advanced topic. After
completing a tutorial, a reader should feel like they've been led from
zero knowledge of its topic to having an invigorating spark of basic
understanding, excited to learn more and experiment further.
Tutorials can certainly use real-world examples when that helps make for
clear, relatable demonstrations, so long as they keep the focus on
teaching--more practical problem-solving should be left to the realm of
cookbooks (as described below). Tutorials also needn't concern themselves
with explanations into why or how things work beneath the surface, or
explorations of alternate syntaxes and solutions; these are better
handled by explainers and reference pages.
_C_o_o_k_b_o_o_k
A cookbook man page focuses on rreessuullttss. Just like its name suggests, it
presents succinct, step-by-step solutions to a variety of real-world
problems around some topic. A cookbook's code examples serve less to
enlighten and more to provide quick, paste-ready solutions that the
reader can apply immediately to the situation facing them.
A Perl cookbook demonstrates ways that all the tools and techniques
explained elsewhere can work together in order to achieve practical
results. Any explanation deeper than that belongs in explainers and
reference pages, instead. (Certainly, a cookbook can cross-reference
other man pages in order to satisfy the curiosity of readers who, with
their immediate problems solved, wish to learn more.)
The most prominent cookbook pages that ship with Perl itself are its many
FAQ pages, in particular "perlfaq4" and up, which provide short solutions
to practical questions in question-and-answer style. "perlunicook" shows
another example, containing a bevy of practical code snippets for a
variety of internationally minded text manipulations.
(An aside: _T_h_e _D_o_c_u_m_e_n_t_a_t_i_o_n _S_y_s_t_e_m calls this mode "how-to", but Perl's
history of creative cuisine prefers the more kitchen-ready term that we
employ here.)
_R_e_f_e_r_e_n_c_e
A reference page focuses on ddeessccrriippttiioonn. Austere, uniform, and succinct,
reference pages--often arranged into a whole section of mutually similar
subpages--lend themselves well to "random access" by a reader who knows
precisely what knowledge they need, requiring only the minimum amount of
information before returning to the task at hand.
Perl's own best example of a reference work is "perlfunc", the sprawling
man page that details the operation of every function built into Perl,
with each function's documentation presenting the same kinds of
information in the same order as every other. For an example of a shorter
reference on a single topic, look at "perlreref".
Module documentation--including that of all the modules listed in
"perlmodlib"--also counts as reference. They follow precepts similar to
those laid down by the "perlpodstyle" man page, such as opening with an
example-laden "SYNOPSIS" section, or featuring a "METHODS" section that
succinctly lists and defines an object-oriented module's public
interface.
_E_x_p_l_a_i_n_e_r
Explainer pages focus on ddiissccuussssiioonn. Each explainer dives as deep as
needed into some Perl-relevant topic, taking all the time and space
needed to give the reader a thorough understanding of it. Explainers mean
to impart knowledge through study. They don't assume that the student has
a Perl interpreter fired up and hungry for immediate examples (as with a
tutorial), or specific Perl problems that 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. This includes 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 many 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. However, as the remainder of this
guide discusses, the ideal Perl documentation manages to deliver its
message clearly and concisely, and not confuse mere wordiness for
completeness.
_F_u_r_t_h_e_r _n_o_t_e_s _o_n _d_o_c_u_m_e_n_t_a_t_i_o_n _m_o_d_e_s
Keep in mind that 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"). Rather, it
makes sure that 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 presents itself as resistant
to fitting into only one of the four modes, consider breaking it up into
separate pages. That may 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--provide a fine example of
spreading a complicated topic across several man pages with different and
clearly indicated purposes.
AAssssuummee rreeaaddeerrss’’ iinntteelllliiggeennccee,, bbuutt nnoott tthheeiirr kknnoowwlleeddggee 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 must recognize this by making as few
assumptions as possible about the reader's prior knowledge. While you
should assume that readers of Perl's documentation are smart, curious,
and eager to learn, you should not confuse this for pre-existing
knowledge about any other technology, or even programming in
general--especially in tutorial or introductory material.
_K_e_e_p _P_e_r_l_'_s _d_o_c_u_m_e_n_t_a_t_i_o_n _a_b_o_u_t _P_e_r_l
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 that the reader
may not have familiarity 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 instead compare it to an equivalent or underlying C function
will probably not illuminate much understanding in a contemporary reader.
Worse, this can risk leaving readers unfamiliar with C feeling locked out
from fully understanding of 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.
_D_e_p_l_o_y _j_a_r_g_o_n _w_h_e_n _n_e_e_d_e_d_, _b_u_t _d_e_f_i_n_e _i_t _a_s _w_e_l_l
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
"open" function's detailed reference--it can also include a very short
in-place definition of the concept for the reader's convenience.
UUssee mmeeaanniinnggffuull vvaarriiaabbllee aanndd ssyymmbbooll nnaammeess iinn eexxaammpplleess 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) { ... }".
WWrriittee iinn EEnngglliisshh,, bbuutt nnoott jjuusstt ffoorr EEnngglliisshh--ssppeeaakkeerrss While this style guide does specify American English as the documentation’s language for the sake of internal consistency, authors should avoid cultural or idiomatic references available only to English- speaking Americans (or any other specific culture or society). As much as possible, the language employed by Perl’s core documentation should strive towards cultural universality, if not neutrality. Regional turns of phrase, examples drawing on popular-culture knowledge, and other rhetorical techniques of that nature should appear sparingly, if at all.
Authors should feel free to let more freewheeling language flourish in
"second-order" documentation about Perl, like books, blog entries, and
magazine articles, published elsewhere and with a narrower readership in
mind. But Perl's own docs should use language as accessible and welcoming
to as wide an audience as possible.
OOmmiitt ppllaacceehhoollddeerr tteexxtt oorr ccoommmmeennttaarryy Placeholder text does not belong in the documentation that ships with Perl. No section header should be followed by text reading only “Watch this space”, “To be included later”, or the like. While Perl’s source files may shift and alter as much as any other actively maintained technology, each released iteration of its technology should feel complete and self-contained, with no such future promises or other loose ends visible.
Take advantage of Perl's regular release cycle. Instead of cluttering the
docs with flags promising more information later--the presence of which
do not help readers at all 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 address that need, and resist the temptation to insert
apologies, which have all the utility in documentation as undeleted debug
messages do in production code.
AAppppllyy sseeccttiioonn--bbrreeaakkss aanndd eexxaammpplleess ggeenneerroouussllyy No matter how accessible their tone, the sight of monolithic blocks of text in technical documentation can present a will-weakening challenge for the reader. Authors can improve this situation through breaking long passages up into subsections with short, meaningful headers.
Since every section-header in Pod also acts as a potential end-point for
a cross-reference (made via Pod's "L<...>" syntax), putting plenty of
subsections in your documentation lets other man pages more precisely
link to a particular topic. This creates hyperlinks directly to the most
appropriate section rather than to the whole page in general, and 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 require further breakdown for clarity's sake.
Example code, on the other hand, can be a welcome addition to any mode of
documentation. Code blocks help break up a man page visually, reassuring
the reader that no matter how deep the textual explanation gets, they are
never far from another practical example showing how it all comes
together using a small, easy-to-read snippet of tested Perl code.
LLeeaadd wwiitthh ccoommmmoonn ccaasseess aanndd bbeesstt pprraaccttiicceess Perl famously gives programmers more than one way to do things. Like any other long-lived programming language, Perl has also built up a large, community-held notion of best practices, blessing some ways to do things as better than others, usually for the sake of more maintainable code.
_S_h_o_w _t_h_e _b_e_t_t_e_r _w_a_y_s _f_i_r_s_t
Whenever it needs to show the rules for a technique which Perl provides
many avenues for, the documentation 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.
The "open" function, for example, has myriad potential uses within Perl
programs, but _m_o_s_t _o_f _t_h_e _t_i_m_e programmers--and especially those new to
Perl--turn to this reference because they simply wish to open a file for
reading or writing. For this reason, "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.
_S_h_o_w _t_h_e _l_e_s_s_e_r _w_a_y_s _w_h_e_n _n_e_e_d_e_d
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
<https://devguide.python.org/documenting/#affirmative-tone> on Python's
documentation team) 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.
DDooccuummeenntt PPeerrll’’ss pprreesseenntt Perl’s documentation should stay focused on Perl’s present behavior, with a nod to future directions.
_R_e_c_o_u_n_t _t_h_e _p_a_s_t _o_n_l_y _w_h_e_n _n_e_c_e_s_s_a_r_y
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. 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.
_D_e_s_c_r_i_b_e _t_h_e _u_n_c_e_r_t_a_i_n _f_u_t_u_r_e _w_i_t_h _c_a_r_e
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.
TThhee ddooccuummeennttaattiioonn ssppeeaakkss wwiitthh oonnee vvooiiccee 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’s 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.
IINNDDEEXX OOFF PPRREEFFEERRRREEDD TTEERRMMSS #
As noted above, this guide "inherits" all the preferred terms listed in
the Chicago Manual of Style, 17th edition, and adds the following terms
of particular interest to Perl documentation.
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.
SSEEEE AALLSSOO #
• perlpod
• perlpodstyle
AAUUTTHHOORR #
This guide was initially drafted by Jason McIntosh (jmac@jmac.org), under
a grant from The Perl Foundation.
perl v5.36.3 2023-02-15 PERLDOCSTYLE(1)