Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1118 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perldocstyle.1 b/upstream/mageia-cauldron/man1/perldocstyle.1
new file mode 100644
index 00000000..b4f19c95
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perldocstyle.1
@@ -0,0 +1,1118 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDOCSTYLE 1"
+.TH PERLDOCSTYLE 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perldocstyle \- A style guide for writing Perl's documentation
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document is a guide for the authorship and maintenance of the
+documentation that ships with Perl. This includes the following:
+.IP \(bu 4
+The several dozen manual sections whose filenames begin with "\f(CW\*(C`perl\*(C'\fR",
+such as \f(CW\*(C`perlobj\*(C'\fR, \f(CW\*(C`perlre\*(C'\fR, and \f(CW\*(C`perlintro\*(C'\fR. (And, yes, \f(CW\*(C`perl\*(C'\fR.)
+.IP \(bu 4
+The documentation for all the modules included with Perl (as listed by
+\&\f(CW\*(C`perlmodlib\*(C'\fR).
+.IP \(bu 4
+The hundreds of individually presented reference sections derived from
+the \f(CW\*(C`perlfunc\*(C'\fR file.
+.PP
+This guide will hereafter refer to user-manual section files as \fIman
+pages\fR, per Unix convention.
+.SS "Purpose of this guide"
+.IX Subsection "Purpose of this guide"
+This style guide aims to establish standards, procedures, and philosophies
+applicable to Perl's core documentation.
+.PP
+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.
+.PP
+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.
+.SS "Intended audience"
+.IX Subsection "Intended audience"
+Anyone interested in contributing to Perl's core documentation should
+familiarize themselves with the standards outlined by this guide.
+.PP
+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.
+.SS "Status of this document"
+.IX Subsection "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.
+.PP
+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.
+.SH FUNDAMENTALS
+.IX Header "FUNDAMENTALS"
+.SS "Choice of markup: Pod"
+.IX Subsection "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.
+.PP
+For a comprehensive reference to Pod syntax, see \f(CW\*(C`perlpod\*(C'\fR.
+For the sake of reading this guide, familiarity with the Pod syntax for
+section headers (\f(CW\*(C`=head2\*(C'\fR, et cetera) and for inline text formatting
+(\f(CW\*(C`C<like this>\*(C'\fR) should suffice.
+.PP
+Perl programmers also use Pod to document their own scripts, libraries,
+and modules. This use of Pod has its own style guide, outlined by
+\&\f(CW\*(C`perlpodstyle\*(C'\fR.
+.SS "Choice of language: American English"
+.IX Subsection "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.
+.PP
+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.
+.PP
+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.
+.PP
+\fIOther languages and translations\fR
+.IX Subsection "Other languages and translations"
+.PP
+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.
+.PP
+That said, keeping Perl's documentation clear, simple, and short has a
+welcome side effect of aiding any such translation project.
+.PP
+(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.)
+.SS "Choice of encoding: UTF\-8"
+.IX Subsection "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.
+.PP
+As such, every core doc file (or the Pod section of every core module)
+should commence with an \f(CW\*(C`=encoding utf8\*(C'\fR declaration.
+.SS "Choice of underlying style guide: CMOS"
+.IX Subsection "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.
+.PP
+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.)
+.SS "Contributing to Perl's documentation"
+.IX Subsection "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.
+.PP
+Perl accepts documentation contributions through the same open-source
+project pipeline as code contributions. See \f(CW\*(C`perlhack\*(C'\fR for
+more information.
+.SH "FORMATTING AND STRUCTURE"
+.IX Header "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.
+.SS "Document structure"
+.IX Subsection "Document structure"
+Each individual work of core Perl documentation, whether contained
+within a \f(CW\*(C`.pod\*(C'\fR 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.)
+.PP
+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
+\&\f(CW\*(C`perlpodstyle\*(C'\fR, which derives its recommendations in
+turn from these well-established practices.
+.PP
+\fIName\fR
+.IX Subsection "Name"
+.PP
+After its \f(CW\*(C`=encoding utf8\*(C'\fR declaration, a
+Perl man page \fImust\fR present a level-one header named "NAME" (literally),
+followed by a paragraph containing the page's name and a very brief
+description.
+.PP
+The first few lines of a notional page named \f(CW\*(C`perlpodexample\*(C'\fR:
+.PP
+.Vb 1
+\&    =encoding utf8
+\&
+\&    =head1 NAME
+\&
+\&    perlpodexample \- An example of formatting a manual page\*(Aqs title line
+.Ve
+.PP
+\fIDescription and synopsis\fR
+.IX Subsection "Description and synopsis"
+.PP
+Most Perl man pages also contain a DESCRIPTION section featuring a
+summary of, or introduction to, the document's content and purpose.
+.PP
+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.
+.PP
+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.
+.PP
+\fIOther sections and subsections\fR
+.IX Subsection "Other sections and subsections"
+.PP
+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
+\&\f(CW\*(C`L<...>\*(C'\fR.
+.PP
+What other sections to include depends entirely upon the topic at hand.
+Authors should feel free to include further \f(CW\*(C`=head1\*(C'\fR\-level sections,
+whether other standard ones listed by \f(CW\*(C`perlpodstyle\*(C'\fR, or ones specific
+to the page's topic; in either case, render these top-level headings in
+all-capital letters.
+.PP
+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.
+.PP
+\fIAuthor and copyright\fR
+.IX Subsection "Author and copyright"
+.PP
+In most circumstances, Perl's stand-alone man pages\-\-those contained
+within \f(CW\*(C`.pod\*(C'\fR 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.
+.PP
+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.
+.PP
+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 \f(CW\*(C`perlpodstyle\*(C'\fR.
+.SS "Formatting rules"
+.IX Subsection "Formatting rules"
+\fILine length and line wrap\fR
+.IX Subsection "Line length and line wrap"
+.PP
+Each line within a Perl man page's Pod source file should measure 72
+characters or fewer in length.
+.PP
+Please break paragraphs up into blocks of short lines, rather than
+"soft wrapping" paragraphs across hundreds of characters with no line
+breaks.
+.PP
+\fICode blocks\fR
+.IX Subsection "Code blocks"
+.PP
+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.
+.PP
+For the sake of consistency within and across Perl's man pages, all
+examples must adhere to the code-layout principles set out by
+\&\f(CW\*(C`perlstyle\*(C'\fR.
+.PP
+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.
+.PP
+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:
+.PP
+.Vb 5
+\&    while (my $line = <$fh>) {
+\&        #
+\&        # (Do something interesting with $line here.)
+\&        #
+\&    }
+.Ve
+.PP
+Even the simplest code blocks often require the use of example
+variables and subroutines, whose names you should choose with
+care.
+.PP
+\fIInline code and literals\fR
+.IX Subsection "Inline code and literals"
+.PP
+Within a paragraph of text, use \f(CW\*(C`C<...>\*(C'\fR when quoting or
+referring to any bit of Perl code\-\-even if it is only one character
+long.
+.PP
+For instance, when referring within an explanatory paragraph to Perl's
+operator for adding two numbers together, you'd write "\f(CW\*(C`C<+>\*(C'\fR".
+.PP
+\fIFunction names\fR
+.IX Subsection "Function names"
+.PP
+Use \f(CW\*(C`C<...>\*(C'\fR to render all Perl function names in monospace,
+whenever they appear in text.
+.PP
+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 \f(CW\*(C`print\*(C'\fR
+function, write it as "\f(CW\*(C`print\*(C'\fR", not "\f(CWprint()\fR".
+.PP
+\fIFunction arguments\fR
+.IX Subsection "Function arguments"
+.PP
+Represent functions' expected arguments in all-caps, with no sigils, and
+using \f(CW\*(C`C<...>\*(C'\fR 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:
+.IP \(bu 4
+EXPR
+.Sp
+The "generic" argument: any scalar value, or a Perl expression that
+evaluates to one.
+.IP \(bu 4
+ARRAY
+.Sp
+An array, stored in a named variable.
+.IP \(bu 4
+HASH
+.Sp
+A hash, stored in a named variable.
+.IP \(bu 4
+BLOCK
+.Sp
+A curly-braced code block, or a subroutine reference.
+.IP \(bu 4
+LIST
+.Sp
+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 \fIlast\fR argument, when present.)
+.PP
+When possible, give scalar arguments names that suggest their purpose
+among the arguments. See, for example, \f(CW\*(C`substr\*(C'\fR's
+documentation, whose
+listed arguments include \f(CW\*(C`EXPR\*(C'\fR, \f(CW\*(C`OFFSET\*(C'\fR, \f(CW\*(C`LENGTH\*(C'\fR, and \f(CW\*(C`REPLACEMENT\*(C'\fR.
+.PP
+\fIApostrophes, quotes, and dashes\fR
+.IX Subsection "Apostrophes, quotes, and dashes"
+.PP
+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.
+.PP
+Render em dashes as two hyphens\-\-like this:
+.PP
+.Vb 1
+\&    Render em dashes as two hyphens\-\-like this.
+.Ve
+.PP
+Leave it up to formatters to reformat and reshape these punctuation
+marks as best fits their respective target media.
+.PP
+\fIUnix programs and C functions\fR
+.IX Subsection "Unix programs and C functions"
+.PP
+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: \f(CWmalloc(3)\fR, or \f(CWmkdir(1)\fR.
+.PP
+If mentioning this program for the first time within a man page or
+section, make it a cross reference, e.g. \f(CW\*(C`L<malloc(3)>\*(C'\fR.
+.PP
+Do not otherwise style this text.
+.PP
+\fICross-references and hyperlinks\fR
+.IX Subsection "Cross-references and hyperlinks"
+.PP
+Make generous use of Pod's \f(CW\*(C`L<...>\*(C'\fR 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.
+.PP
+Use \f(CW\*(C`L<...>\*(C'\fR 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.
+.PP
+Hyperlinks do not supersede other formatting required by this guide; Pod
+allows nested text formats, and you should use this feature as needed.
+.PP
+Here is an example sentence that mentions Perl's \f(CW\*(C`say\*(C'\fR function, with a
+link to its documentation section within the \f(CW\*(C`perlfunc\*(C'\fR man page:
+.PP
+.Vb 2
+\&    In version 5.10, Perl added support for the 
+\&    L<C<say>|perlfunc/say FILEHANDLE LIST> function.
+.Ve
+.PP
+Note the use of the vertical pipe ("\f(CW\*(C`|\*(C'\fR") to separate how the link will
+appear to readers ("\f(CW\*(C`C<say>\*(C'\fR") from the full page-and-section specifier
+that the formatter links to.
+.PP
+\fITables and diagrams\fR
+.IX Subsection "Tables and diagrams"
+.PP
+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 \f(CW\*(C`=begin\*(C'\fR / \f(CW\*(C`=end\*(C'\fR directives to
+target these tables at \f(CW\*(C`html\*(C'\fR and \f(CW\*(C`text\*(C'\fR Pod formatters, respectively.
+For example:
+.PP
+.Vb 1
+\&    =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
+.Ve
+.PP
+The same holds true for figures and graphical illustrations. Pod does
+not natively support inline graphics, but you can mix HTML \f(CW\*(C`<img>\*(C'\fR tags
+with monospaced text-art representations of those images' content.
+.PP
+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.
+.SS "Adding comments"
+.IX Subsection "Adding comments"
+Like any other kind of source code, Pod lets you insert comments visible
+only to other people reading the source directly, and ignored by the
+formatting programs that transform Pod into various human-friendly
+output formats (such as HTML or PDF).
+.PP
+To comment Pod text, use the \f(CW\*(C`=for\*(C'\fR and \f(CW\*(C`=begin\*(C'\fR / \f(CW\*(C`=end\*(C'\fR Pod
+directives, aiming them at a (notional) formatter called "\f(CW\*(C`comment\*(C'\fR". A
+couple of examples:
+.PP
+.Vb 2
+\&    =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\*(Aqs
+\&    great for leaving notes, explanations, or suggestions for your
+\&    fellow documentation writers.
+\&
+\&    =end comment
+.Ve
+.PP
+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).
+.SS "Perlfunc has special rules"
+.IX Subsection "Perlfunc has special rules"
+The \f(CW\*(C`perlfunc\*(C'\fR man page, an exhaustive reference of every
+Perl built-in function, has a handful of formatting rules not seen
+elsewhere in Perl's documentation.
+.PP
+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.
+.PP
+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:
+.IP 1. 4
+A list of \f(CW\*(C`=item\*(C'\fR 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).
+.Sp
+If modern best practices prefer certain ways to invoke the function
+over others, then those ways should lead the list.
+.Sp
+The first item of the list should be immediately followed by one or
+more \f(CW\*(C`X<...>\*(C'\fR terms listing index-worthy topics; if nothing
+else, then the name of the function, with no arguments.
+.IP 2. 4
+A \f(CW\*(C`=for\*(C'\fR line, directed at \f(CW\*(C`Pod::Functions\*(C'\fR, 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".
+.IP 3. 4
+The function's definition and reference material, including all
+explanatory text and code examples.
+.PP
+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 \f(CW\*(C`=item\*(C'\fR elements as header text.
+.PP
+A fictional function "\f(CW\*(C`myfunc\*(C'\fR", which takes a list as an optional
+argument, might have an entry in perlfunc shaped like this:
+.PP
+.Vb 2
+\&    =item myfunc LIST
+\&    X<myfunc>
+\&
+\&    =item myfunc
+\&
+\&    =for Pod::Functions demonstrate a function\*(Aqs 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
+.Ve
+.SH "TONE AND STYLE"
+.IX Header "TONE AND STYLE"
+.SS "Apply one of the four documentation modes"
+.IX Subsection "Apply one of the four documentation modes"
+Aside from "meta" documentation such as \f(CW\*(C`perlhist\*(C'\fR or \f(CW\*(C`perlartistic\*(C'\fR,
+each of Perl's man pages should conform to one of the four documentation
+"modes" suggested by \fIThe Documentation System\fR by Daniele
+Procida <https://documentation.divio.com>. These include tutorials,
+cookbooks, explainers, and references\-\-terms that we define in further
+detail below.
+.PP
+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.
+.PP
+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.
+.PP
+\fITutorial\fR
+.IX Subsection "Tutorial"
+.PP
+A tutorial man page focuses on \fBlearning\fR, ideally by \fIdoing\fR. 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
+\&\f(CW\*(C`perlxstut\*(C'\fR, \f(CW\*(C`perlpacktut\*(C'\fR, and
+\&\f(CW\*(C`perlretut\*(C'\fR.
+.PP
+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.
+.PP
+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.
+.PP
+\fICookbook\fR
+.IX Subsection "Cookbook"
+.PP
+A cookbook man page focuses on \fBresults\fR. 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.
+.PP
+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.)
+.PP
+The most prominent cookbook pages that ship with Perl itself are its
+many FAQ pages, in particular \f(CW\*(C`perlfaq4\*(C'\fR and up, which provide short
+solutions to practical questions in question-and-answer style.
+\&\f(CW\*(C`perlunicook\*(C'\fR shows another example, containing a bevy of practical code
+snippets for a variety of internationally minded text manipulations.
+.PP
+(An aside: \fIThe Documentation System\fR calls this mode "how-to", but
+Perl's history of creative cuisine prefers the more kitchen-ready term
+that we employ here.)
+.PP
+\fIReference\fR
+.IX Subsection "Reference"
+.PP
+A reference page focuses on \fBdescription\fR. 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.
+.PP
+Perl's own best example of a reference work is \f(CW\*(C`perlfunc\*(C'\fR, 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 \f(CW\*(C`perlreref\*(C'\fR.
+.PP
+Module documentation\-\-including that of all the modules listed in
+\&\f(CW\*(C`perlmodlib\*(C'\fR\-\-also counts as reference. They follow
+precepts similar to those laid down by the \f(CW\*(C`perlpodstyle\*(C'\fR 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.
+.PP
+\fIExplainer\fR
+.IX Subsection "Explainer"
+.PP
+Explainer pages focus on \fBdiscussion\fR. 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).
+.PP
+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
+"\f(CW\*(C`perl\*(C'\fR". A fine example is \f(CW\*(C`perlsyn\*(C'\fR, 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.
+.PP
+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.
+.PP
+\fIFurther notes on documentation modes\fR
+.IX Subsection "Further notes on documentation modes"
+.PP
+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.
+\&\f(CW\*(C`open\*(C'\fR). Rather, it makes sure
+that the authors and contributors of any given man page agree on what
+sort of audience that page addresses.
+.PP
+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 "\f(CW\*(C`perl[...]\*(C'\fR"
+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, \f(CW\*(C`Example::Module\*(C'\fR's reference documentation
+might include a see-also link to \f(CW\*(C`Example::Module::Cookbook\*(C'\fR.
+.PP
+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.
+.SS "Assume readers' intelligence, but not their knowledge"
+.IX Subsection "Assume readers' intelligence, but not their knowledge"
+Perl has grown a great deal from its humble beginnings as a tool for
+people already well versed in C programming and various Unix utilities.
+Today, a person learning Perl might come from any social or
+technological background, with a range of possible motivations
+stretching far beyond system administration.
+.PP
+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.
+.PP
+\fIKeep Perl's documentation about Perl\fR
+.IX Subsection "Keep Perl's documentation about Perl"
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+\fIDeploy jargon when needed, but define it as well\fR
+.IX Subsection "Deploy jargon when needed, but define it as well"
+.PP
+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.
+.PP
+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 \f(CW\*(C`open\*(C'\fR function's detailed reference\-\-it can also include a very short in-place
+definition of the concept for the reader's convenience.
+.SS "Use meaningful variable and symbol names in examples"
+.IX Subsection "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 \f(CW\*(C`foo\*(C'\fR, \f(CW\*(C`bar\*(C'\fR, and
+\&\f(CW\*(C`baz\*(C'\fR. 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.
+.PP
+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 \f(CW\*(C`Apple\*(C'\fR and \f(CW\*(C`Fruit\*(C'\fR, rather
+than \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR. Similarly, sample code creating an instance of
+that class would do better to name it \f(CW$apple\fR, rather than \f(CW$baz\fR.
+.PP
+Even the simplest examples benefit from clear language using concrete
+words. Prefer a construct like \f(CW\*(C`for my $item (@items) { ... }\*(C'\fR over
+\&\f(CW\*(C`for my $blah (@blah) { ... }\*(C'\fR.
+.SS "Write in English, but not just for English-speakers"
+.IX Subsection "Write in English, but not just for English-speakers"
+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.
+.PP
+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.
+.SS "Omit placeholder text or commentary"
+.IX Subsection "Omit placeholder text or commentary"
+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.
+.PP
+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.
+.SS "Apply section-breaks and examples generously"
+.IX Subsection "Apply section-breaks and examples generously"
+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.
+.PP
+Since every section-header in Pod also acts as a potential end-point for
+a cross-reference (made via Pod's \f(CW\*(C`L<...>\*(C'\fR 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.
+.PP
+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.
+.PP
+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.
+.SS "Lead with common cases and best practices"
+.IX Subsection "Lead with common cases and best practices"
+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.
+.PP
+\fIShow the better ways first\fR
+.IX Subsection "Show the better ways first"
+.PP
+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.
+.PP
+The \f(CW\*(C`open\*(C'\fR function, for example, has myriad potential uses within Perl
+programs, but \fImost of the time\fR 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, \f(CW\*(C`open\*(C'\fR'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
+\&\f(CW\*(C`open\*(C'\fR documentation does not burden the reader right away with detailed
+explanations about calling \f(CW\*(C`open\*(C'\fR via any route other than the
+best-practice, three-argument style.
+.PP
+\fIShow the lesser ways when needed\fR
+.IX Subsection "Show the lesser ways when needed"
+.PP
+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.
+.PP
+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.
+.SS "Document Perl's present"
+.IX Subsection "Document Perl's present"
+Perl's documentation should stay focused on Perl's present behavior,
+with a nod to future directions.
+.PP
+\fIRecount the past only when necessary\fR
+.IX Subsection "Recount the past only when necessary"
+.PP
+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, [...]".
+.PP
+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.
+.PP
+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.
+.PP
+Otherwise, keep the past in the past. A manual uncluttered with
+outdated instruction stays more succinct and relevant.
+.PP
+\fIDescribe the uncertain future with care\fR
+.IX Subsection "Describe the uncertain future with care"
+.PP
+Perl features marked as "experimental"\-\-those that generate warnings
+when used in code not invoking the \f(CW\*(C`experimental\*(C'\fR
+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.
+.PP
+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.
+.PP
+Introductory or overview material should omit coverage of experimental
+features altogether.
+.PP
+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.
+.SS "The documentation speaks with one voice"
+.IX Subsection "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's contributor's philosophies or
+experiences.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+Write with a light heart, and a miserly hand.
+.SH "INDEX OF PREFERRED TERMS"
+.IX Header "INDEX OF PREFERRED TERMS"
+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.
+.IP "built-in function" 4
+.IX Item "built-in function"
+Not "builtin".
+.IP Darwin 4
+.IX Item "Darwin"
+See macOS.
+.IP macOS 4
+.IX Item "macOS"
+Use this term for Apple's operating system instead of "Mac OS X" or
+variants thereof.
+.Sp
+This term is also preferable to "Darwin", unless one needs to refer
+to macOS's Unix layer specifically.
+.IP "man page" 4
+.IX Item "man page"
+One unit of Unix-style documentation. Not "manpage". Preferable to "manual page".
+.IP "Perl; perl" 4
+.IX Item "Perl; perl"
+The name of the programming language is Perl, with a leading capital
+"P", and the remainder in lowercase. (Never "PERL".)
+.Sp
+The interpreter program that reads and executes Perl code is named
+"\f(CW\*(C`perl\*(C'\fR", in lowercase and in monospace (as with any other command
+name).
+.Sp
+Generally, unless you are specifically writing about the
+command-line \f(CW\*(C`perl\*(C'\fR program (as, for example, \f(CW\*(C`perlrun\*(C'\fR
+does), use "Perl" instead.
+.IP "Perl 5" 4
+.IX Item "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.
+.Sp
+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.
+.IP "Perl 6" 4
+.IX Item "Perl 6"
+See Raku.
+.IP "Perl 5 Porters, the; porters, the; p5p" 4
+.IX Item "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".
+.Sp
+Not "Perl5 Porters".
+.IP program 4
+.IX Item "program"
+The most general descriptor for a stand-alone work made out of
+executable Perl code. Synonymous with, and preferable to, "script".
+.IP Raku 4
+.IX Item "Raku"
+Perl's "sister language", whose homepage is <https://raku.org>.
+.Sp
+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".
+.IP script 4
+.IX Item "script"
+See program.
+.IP semicolon 4
+.IX Item "semicolon"
+Perl code's frequently overlooked punctuation mark. Not "semi-colon".
+.IP Unix 4
+.IX Item "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.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP \(bu 4
+perlpod
+.IP \(bu 4
+perlpodstyle
+.SH AUTHOR
+.IX Header "AUTHOR"
+This guide was initially drafted by Jason McIntosh
+(jmac@jmac.org), under a grant from The Perl Foundation.