perldocstyle

PERLDOCSTYLE(1)        Perl Programmers Reference Guide        PERLDOCSTYLE(1)

NAME
       perldocstyle - A style guide for writing Perl's documentation

DESCRIPTION
       This document is a guide for the authorship and maintenance of the
       documentation that ships with Perl. This includes the following:

       o   The several dozen manual sections whose filenames begin with
           ""perl"", such as "perlobj", "perlre", and "perlintro". (And, yes,
           "perl".)

       o   The documentation for all the modules included with Perl (as listed
           by "perlmodlib").

       o   The hundreds of individually presented reference sections derived
           from the "perlfunc" file.

       This guide will hereafter refer to user-manual section files as man
       pages, per Unix convention.

   Purpose of this guide
       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.

   Intended audience
       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.

   Status of this document
       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.

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, 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".

   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 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.

       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.

       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.)

   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.

       As such, every core doc file (or the Pod section of every core module)
       should commence with an "=encoding utf8" declaration.

   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 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.)

   Contributing to Perl's documentation
       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.

FORMATTING AND STRUCTURE
       This section details specific Pod syntax and style that all core Perl
       documentation should adhere to, in the interest of consistency and
       readability.

   Document structure
       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.

       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 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.

       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.

       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. 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".

   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.

       Code blocks

       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.

       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<+>"".

       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()"".

       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:

       o   EXPR

           The "generic" argument: any scalar value, or a Perl expression that
           evaluates to one.

       o   ARRAY

           An array, stored in a named variable.

       o   HASH

           A hash, stored in a named variable.

       o   BLOCK

           A curly-braced code block, or a subroutine reference.

       o   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.)

       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".

       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.

       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.

       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.

       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<CPERLDOCSTYLE(1)