perldocstyle - Perl 文档编写风格指南
本文档是编写随 Perl 一起发布的文档的指南。这包括以下内容
数十个手册部分，其文件名以“perl”开头，例如 perlobj、perlre 和 perlintro。（是的，perl。）
所有包含在 Perl 中的模块的文档（如 perlmodlib 所列）。
从 perlfunc 文件派生的数百个单独呈现的参考部分。
本指南将根据 Unix 惯例，将用户手册部分文件称为手册页。
本风格指南旨在建立适用于 Perl 核心文档的标准、程序和理念。
遵守这些标准将有助于确保 Perl 手册的任何一部分都具有与其他任何部分一致的语气和风格。与 Perl 项目的其他部分一样，该语言的文档集合是一个开源项目，由许多人在很长一段时间内编写。在如此广泛的工作中保持一致性是一个挑战；本指南提供了一个基础来帮助减轻这种困难。
这将有助于读者，尤其是那些刚接触 Perl 的人，更轻松地融入 Perl 文档，并积极参与其中。反过来，这将有助于 Perl 项目本身通过拥有更多、更多样化、更自信的知识用户群体而变得更加强大。
任何有兴趣为 Perl 核心文档做出贡献的人员都应该熟悉本指南中概述的标准。
除了 Perl 项目本身之外，为自己的工作编写文档的程序员也可能发现本指南很有用，尤其是当他们希望自己的工作扩展 Perl 手册的语气和风格时。
本指南最初是在 2020 年底起草的，借鉴了当时与 Perl 同期的几种开源技术的文档风格指南。其中包括 Python、Raku、Rust 和 Linux 内核。
作者希望将本指南用作起点，从该起点开始对 Perl 大量的现有文档进行审查，并期望进行审查的人员根据需要扩展和修改本指南，以满足 Perl 编程手册的特定要求和怪癖。
Perl 的所有核心文档都使用 Pod（“Plain Old Documentation”）这种简单的标记语言来格式化其源文本。Pod 在精神上类似于其他当代轻量级标记技术，例如 Markdown 和 reStructuredText，并且与 Perl 本身有着数十年的共同历史。
有关 Pod 语法的全面参考，请参见 perlpod。为了阅读本指南，熟悉 Pod 语法中的节标题（=head2 等）和内联文本格式（C<like this>）就足够了。
Perl 程序员还使用 Pod 来记录他们自己的脚本、库和模块。这种 Pod 的使用有其自己的风格指南，由 perlpodstyle 概述。
Perl 的核心文档是用英语编写的，优先使用美式英语的单词拼写和短语表达。这意味着使用 “color” 而不是 “colour”，使用 “math” 而不是 “maths”，使用 “the team has decided” 而不是 “the team have decided”，等等。
为了确保 Perl 文档的一致性，我们指定了一种英语风格，就像软件项目可能会声明一个四空格缩进标准一样，即使这不会影响代码的编译方式。这两种努力都通过避免格式或风格的突然变化，使阅读变得更加容易。
Perl 文档的贡献者应注意，此规则描述了项目的最终发布输出，并不规定社区贡献中使用的方言。文档团队热烈欢迎任何英语贡献，并在需要时积极协助将拼写和风格美国化。
社区编写的 Perl 文档翻译确实存在，涵盖多种语言。虽然 Perl 项目感谢这些翻译工作并在适用时推广它们，但它并不正式支持或维护任何翻译。
也就是说，保持 Perl 文档清晰、简洁和简短，这对任何此类翻译项目都有助益。
(请注意，Perl 源代码分发中包含的中文、日语和韩语 README 文件是对此语言选择的例外——但这些文档不在本指南的范围内。)
Perl 的核心文档文件使用 UTF-8 编码，可以利用此编码允许的全部字符范围。
因此，每个核心文档文件（或每个核心模块的 Pod 部分）都应以 =encoding utf8 声明开头。
Perl 的文档使用第 17 版的 芝加哥格式手册 (CMOS) 作为其风格和语法的基准指南。虽然您当前正在阅读的文档旨在作为 Perl 文档的独立风格指南，但作者应将 CMOS 视为未在此处涵盖的任何相关主题的最终权威。
由于 CMOS 不是免费资源，因此访问它不是为 Perl 文档做出贡献的先决条件；文档团队将帮助贡献者学习和应用其指南，根据需要。但是，我们鼓励任何对重大文档贡献感兴趣的人获取或至少通读 CMOS。（大多数公共图书馆可能提供副本，并且也可以在线找到 CMOS 衍生的基础知识。）
Perl，就像任何编程语言一样，只有其文档一样好。Perl 依赖于清晰、友好和全面的文档，以欢迎全新的用户，教授和解释该语言的各种概念和组件，并作为经验丰富的 Perl 程序员的终身参考。因此，Perl 项目欢迎并重视所有社区为改进该语言的文档所做的努力。
Perl 接受通过与代码贡献相同的开源项目管道进行的文档贡献。有关更多信息，请参阅 perlhack。
本节详细介绍所有核心 Perl 文档应遵循的特定 Pod 语法和样式，以确保一致性和可读性。
每个独立的核心 Perl 文档作品，无论是在 .pod 文件中还是在标准代码模块的 Pod 部分中，都以许多长期 Unix 手册页约定为其结构模式。（因此，本指南使用“手册页”来指代 Perl 文档的任何一个自包含部分。）
遵循这些约定有助于 Pod 格式化程序在不同的上下文中呈现 Perl 手册页的内容——无论是终端、网络，甚至打印。以下许多要求源于 perlpodstyle，它反过来从这些成熟的实践中汲取其建议。
在 =encoding utf8 声明 之后，Perl 手册页必须呈现一个名为“NAME”（字面意思）的一级标题，后面跟着一个包含页面名称和非常简短描述的段落。
名为 perlpodexample 的一个假想页面的前几行
=encoding utf8
=head1 NAME
perlpodexample - An example of formatting a manual page's title line大多数 Perl 手册页还包含一个 DESCRIPTION 部分，其中包含对文档内容和目的的摘要或介绍。
本节还应以某种方式明确标识页面所针对的受众，尤其是在对读者事先的知识有期望的情况下。例如，深入探讨 Perl 正则表达式引擎内部工作原理的手册页应在开头说明其假设——并迅速将那些正在寻找更基本参考或教程的读者重定向。
参考页，在适当的情况下，可以在 DESCRIPTION 之前添加一个 SYNOPSIS 部分，该部分在一个或多个代码块中列出所引用功能使用的几个非常简短的示例。本节应显示一些常见情况和最佳实践示例，而不是对所有晦涩方法或可用备用语法的详尽列表。
在适当的情况下，页面应以 SEE ALSO 部分结束，该部分包含指向 Perl 手册的相关部分、其他 Unix 手册页或适当网页的超链接。通过 L<...> 超链接每个这样的交叉引用。
要包含哪些其他部分完全取决于主题。作者可以随意添加更多 =head1 级别的部分，无论是 perlpodstyle 列出的其他标准部分，还是特定于页面主题的部分；无论哪种情况，都应将这些顶级标题呈现为全大写字母。
然后，您可以在它们下面包含任意数量的子部分，以满足清晰度、可访问性和交叉引用亲和力的标准 如本指南其他地方所述。
在大多数情况下，Perl 的独立手册页——那些包含在 .pod 文件中的手册页——不需要包含任何关于它们自己的版权或许可信息。它们的源 Pod 文件是 Perl 自己的核心软件存储库的一部分，并且已经涵盖了它们，与 Perl 本身具有相同的版权和许可条款。您无需包含您自己的其他“LICENSE”或“COPYRIGHT”部分。
这些手册页可以选择在“AUTHOR”或“CONTRIBUTORS”标题下注明其主要作者，或包含重要贡献者的列表。请注意，作者姓名的存在并不排除特定页面 以与 Perl 文档其余部分一致的声音写作。
请注意，这些指南不适用于与 Perl 一起提供的核心软件模块。这些模块有自己的作者身份和版权声明标准，如 perlpodstyle 中所述。
Perl 手册页的 Pod 源文件中的每一行长度应为 72 个字符或更少。
请将段落分成短行块，而不是在数百个字符中“软换行”段落，而没有换行符。
与周围的文本一样，所有代码示例都应尽可能短小易读，显示的复杂性不超过说明手头概念所绝对必要的复杂性。
为了在 Perl 的手册页之间保持一致性，所有示例都必须遵守 perlstyle 制定的代码布局原则。
示例代码仅在必要时才应偏离这些标准：例如，在演示 Perl 如何忽略空格时，或者为了暂时切换到两列缩进以进行不可避免的冗长说明。
您可以在示例代码中包含注释，以进一步阐明或标记代码的行为。您还可以使用注释作为占位符，用于通常存在但与当前主题无关的代码，如下所示
while (my $line = <$fh>) {
#
# (Do something interesting with $line here.)
#
}即使是最简单的代码块也经常需要使用示例变量和子例程，您应该谨慎选择它们的名称。
在一段文字中，使用 C<...> 来引用或提及任何 Perl 代码片段，即使它只有一字符长。
例如，在解释性段落中提到 Perl 用于将两个数字相加的运算符时，您应该写成 "C<+>"。
使用 C<...> 将所有 Perl 函数名称以等宽字体呈现，无论它们出现在文本中的哪个位置。
除非您需要专门引用带有参数列表的函数调用，否则不要在文本中函数名称后面加一对空括号。也就是说，在一般情况下提到 Perl 的 print 函数时，写成 "print"，而不是 "print()"。
用全大写字母表示函数的预期参数，不使用符号，并使用 C<...> 将它们以等宽字体呈现。这些参数应该有简短的名称，使它们的性质和目的清晰。惯例指定了在 Perl 文档中常见的几个参数。
EXPR
"通用"参数：任何标量值，或计算结果为一个标量值的 Perl 表达式。
ARRAY
一个数组，存储在命名变量中。
HASH
一个哈希表，存储在命名变量中。
BLOCK
一个用大括号括起来的代码块，或一个子程序引用。
LIST
任意数量的值，存储在任意数量的变量或表达式中，函数将“扁平化”并将其视为一个列表。（由于它可以包含任意数量的变量，因此它必须是最后一个参数，如果存在的话。）
如果可能，请为标量参数命名，以暗示它们在参数中的作用。例如，请参见 substr 的文档，其列出的参数包括 EXPR、OFFSET、LENGTH 和 REPLACEMENT。
在 Pod 源代码中，使用直引号，而不是“弯引号”：“像这样”，而不是“像这样”。撇号也是如此：这是一个正面的例子，而这是一个负面的例子。
将 em 破折号渲染为两个连字符--像这样
Render em dashes as two hyphens--like this.将这些标点符号的重新格式化和重塑工作留给格式化程序，以便它们最适合各自的目标媒体。
在提到具有自身手册页的 Unix 程序或 C 函数（在 Perl 文档之外）时，请在括号中包含其手册部分号。例如：malloc(3) 或 mkdir(1)。
如果在手册页或部分中首次提及此程序，请将其作为交叉引用，例如 L<malloc(3)>。
不要以其他方式设置此文本的样式。
充分利用 Pod 的 L<...> 语法来创建指向当前手册页其他部分或完全不同文档的超链接——无论是在读者计算机上的其他位置，还是通过 URL 在互联网上的某个位置。
在提及当前手册页的另一个部分时，使用 L<...> 进行链接，并使用其页面和部分语法链接到 Perl 文档中单独页面的最具体部分。通常，在特定页面或部分中首次引用特定函数、程序或概念时，请考虑链接到其完整文档。
超链接不会取代本指南要求的其他格式；Pod 允许嵌套文本格式，您应根据需要使用此功能。
以下是一个示例句子，其中提到了 Perl 的 say 函数，并链接到 perlfunc 手册页中的文档部分
In version 5.10, Perl added support for the
L<C<say>|perlfunc/say FILEHANDLE LIST> function.请注意使用竖线（“|”）来分隔链接在读者面前的显示方式（“C<say>”）和格式化程序链接到的完整页面和部分规范。
Pod 不正式支持表格。为了最佳地呈现表格数据，请将表格作为 HTML 和纯文本表示形式包含在内——后者作为缩进的代码块。使用 =begin / =end 指令分别将这些表格定位到 html 和 text Pod 格式化程序。例如
=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对于图形和图形插图也是如此。Pod 本身不支持内联图形，但您可以将 HTML <img> 标签与这些图像内容的等宽文本艺术表示形式混合使用。
由于这些限制，大多数 Perl 手册页都不使用表格或图表。但是，就像您文档工具包中的任何其他工具一样，您可以在提高解释清晰度而不增加复杂性的情况下考虑将其包含在内。
与任何其他类型的源代码一样，Pod 允许您插入仅对直接阅读源代码的其他人可见的注释，并且被将 Pod 转换为各种对人类友好的输出格式（如 HTML 或 PDF）的格式化程序忽略。
要注释 Pod 文本，请使用 =for 和 =begin / =end Pod 指令，将其指向名为“comment”的（假想）格式化程序。以下是一些示例
=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按照任何优秀的开源项目的传统，您应该自由但谨慎地使用注释，根据需要留下内联“元文档”，以供其他 Perl 文档编写者（包括您未来的自己）使用。
perlfunc 手册页 是对所有 Perl 内置函数的详尽参考，它有一些在 Perl 文档中其他地方看不到的格式化规则。
在 Perl 构建过程中使用的软件（Pod::Functions）根据某些规则解析此页面，以便为每个 Perl 函数构建单独的手册页，以及实现其他索引效果。因此，perlfunc 的贡献者必须了解并遵守其特定规则。
大多数 perfunc 手册页包含一个单一列表，位于标题 "Perl 函数的字母顺序列表" 下。每个函数引用都是该列表中的一个条目，由三个部分组成，按顺序排列
一系列 =item 行，每行都以模板格式演示了调用此函数的一种方法。对于函数接受的每个参数组合（包括适用时不带任何参数），都应该存在一行。
如果现代最佳实践更喜欢某些调用函数的方式而不是其他方式，那么这些方式应该排在列表的最前面。
列表的第一个项目应紧随其后的是一个或多个 X<...> 术语，列出值得索引的主题；如果没有其他主题，则为函数名称，不带任何参数。
一条指向 Pod::Functions 的 =for 行，包含对函数作用的单行描述。这写成一个短语，以一个祈使动词开头，既没有开头的大写字母，也没有结尾的标点符号。例如，“引用一个单词列表”和“更改一个文件名”。
函数的定义和参考材料，包括所有解释性文本和代码示例。
需要将文本分成多个小节的复杂函数（遵循"慷慨地应用分节符和示例"原则）可以使用子列表，其中=item元素作为标题文本。
一个虚构的函数“myfunc”，它接受一个列表作为可选参数，可能在perlfunc中有一个类似这样的条目
=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除了“元”文档（如perlhist或perlartistic）之外，Perl 的每个手册页都应符合 Daniele Procida 编写的文档系统中建议的四种文档“模式”之一。这些模式包括教程、菜谱、解释器和参考——我们在下面将详细定义这些术语。
每种文档模式都面向不同的受众——不仅仅是不同背景和技能水平的人，还包括个人读者，他们的语言文档需求会根据上下文而变化。例如，一个有足够时间学习 Perl 新概念的程序员可以轻松地学习一个关于它的教程，然后通过学习一个解释器来进一步扩展他们的知识。后来，同一个程序员，在深入代码中，只需要查找某个函数的确切语法，就会想要使用参考页面。
Perl 的文档必须努力满足这些不同的情境期望，将每个手册页限制为单一模式。这有助于作者确保他们为读者提供所需或预期的文档，无论情况如何变化。
教程手册页侧重于学习，理想情况下是通过实践。它向读者展示一些有趣的小例子，让他们可以使用自己的 Perl 解释器进行操作。教程通过让读者立即体验（并实验）所讨论的概念来激发理解。例如perlxstut、perlpacktut和perlretut。
教程手册页必须从一开始就努力营造一种友好和令人放心的语气；它们很可能是 Perl 新手阅读的第一件事，在他们是否选择继续使用 Perl 中起着重要作用。即使是经验丰富的程序员也可以从关于更高级主题的强大教程中获得的勇气感中受益。完成教程后，读者应该感觉自己已经从对主题一无所知到对基本理解有了令人振奋的火花，并渴望进一步学习和实验。
教程当然可以使用现实世界的例子，只要这些例子有助于提供清晰、相关的演示，只要它们将重点放在教学上——更实用的问题解决应该留给菜谱（如下所述）。教程也不必关注对事物在表面之下如何工作或为什么工作的解释，或对备选语法和解决方案的探索；这些内容最好由解释器和参考页面处理。
食谱手册侧重于结果。顾名思义，它针对某个主题提供了一系列针对现实世界问题的简洁、分步解决方案。食谱中的代码示例并非为了阐明，而是为了提供快速、可直接粘贴的解决方案，读者可以立即将其应用于他们所面临的情况。
Perl 食谱展示了所有在其他地方解释的工具和技术如何协同工作以实现实际结果。任何比这更深入的解释都应该放在解释器和参考页面中。（当然，食谱可以交叉引用其他手册页，以满足那些已经解决了眼前问题，并希望了解更多信息的读者的好奇心。）
Perl 自身附带的最突出的食谱页面是其众多 FAQ 页面，特别是perlfaq4 及其后续页面，它们以问答的形式为实际问题提供简短的解决方案。perlunicook 是另一个例子，它包含大量针对各种国际化文本操作的实用代码片段。
（旁注：文档系统将这种模式称为“操作指南”，但 Perl 的创意烹饪历史更喜欢我们在这里使用的更贴近厨房的术语。）
参考页面侧重于描述。参考页面简洁、统一、简洁，通常排列成一个包含相互类似子页面的完整部分，非常适合“随机访问”，读者可以准确地知道他们需要什么知识，只需要最少的信息量，然后就可以返回到手头的任务。
Perl 自己最好的参考作品是perlfunc，这是一个庞大的手册页，详细介绍了 Perl 中每个内置函数的操作，每个函数的文档都以相同的顺序呈现相同类型的信息。要查看有关单个主题的较短参考，请查看perlreref。
模块文档（包括 perlmodlib 中列出的所有模块的文档）也属于参考。它们遵循perlpodstyle 手册页中规定的原则，例如以包含示例的“概要”部分开头，或者包含一个“方法”部分，该部分简洁地列出并定义面向对象的模块的公共接口。
解释器页面侧重于讨论。每个解释器都会深入探讨某个与 Perl 相关的主题，并花费所有必要的时间和空间，让读者对其有透彻的理解。解释器的目的是通过学习来传授知识。它们不假设学生已经启动了 Perl 解释器，并渴望立即获得示例（如教程），或者需要快速解答的特定 Perl 问题（食谱和参考页面可以帮助解决这些问题）。
除了参考页面之外，Perl 手册的大部分内容都属于这种模式。这包括大多数名称以“perl”开头的 手册页。一个很好的例子是perlsyn，即 Perl 语法页面，它在广泛的讨论中探讨了 Perl 独特语法的来龙去脉，其中包含许多关于该语言历史、文化和驱动理念的参考。
Perl 的解释器页面让作者有机会探索 Perl 对 TMTOWTDI 的偏好，说明了使用所讨论的语言功能的替代方法，甚至是不常用的方法。但是，正如本指南的其余部分所讨论的那样，理想的 Perl 文档能够清晰简洁地传递其信息，而不是将冗长混淆为完整性。
请记住，这种分类的目的不是规定内容——例如，一篇非常详细的解释器可能会包含它自己的简短参考部分，或者关于一个非常复杂函数的参考页面可能在某些地方类似于解释器（例如，open）。相反，它确保任何给定手册页面的作者和贡献者就该页面针对的受众达成一致。
如果一个新的或其他未分类的手册页面表现出难以只适合四种模式中的一种，请考虑将其拆分为单独的页面。这可能意味着创建一个新的“perl[...]”手册页，或者（在模块文档的情况下）在该模块命名空间下创建新的包，这些包仅用于保存额外的文档。例如，Example::Module 的参考文档可能包含指向 Example::Module::Cookbook 的参见链接。
Perl 关于 Unicode 的几个手册页——包括一个简短的教程、一个详细的解释器、一个食谱和一个常见问题解答——提供了一个很好的例子，说明如何将一个复杂主题分散到几个具有不同且明确指示目的的手册页中。
Perl 从它作为一种工具的简陋起源发展至今，该工具面向已经精通 C 编程和各种 Unix 实用程序的人。如今，学习 Perl 的人可能来自任何社会或技术背景，其动机范围远远超出了系统管理。
Perl 的核心文档必须通过对读者先前知识的假设尽可能少来认识到这一点。虽然你应该假设 Perl 文档的读者很聪明、好奇并且渴望学习，但你不应该将此与关于任何其他技术，甚至一般编程的预先存在的知识混淆——尤其是在教程或入门材料中。
除了专门用于探索 Perl 与其他编程语言关系的页面之外，文档应该将重点放在 Perl 上。避免与读者可能不熟悉的其他技术进行类比。
例如，在记录 Perl 的内置函数之一时，请像读者现在第一次学习该函数一样编写，无论是在哪种编程语言中。
选择将其与等效的或底层的 C 函数进行比较可能不会在当代读者中阐明太多理解。更糟糕的是，这可能会冒着让不熟悉 C 的读者无法完全理解主题的风险——更不用说完全不熟悉计算机编程的读者了。
然而，如果该函数与其 C 根源的联系可以帮助 Perl 程序员更深入地理解并将其应用于实际应用中，您可以在提供更直接有用的文档之后再提及该链接。否则，完全省略此信息，将其留给其他文档或更关注 Perl 底层实现细节的外部文章。
特定领域的术语有其用武之地，尤其是在文档中。但是，如果手册页使用了普通读者可能不了解的术语，那么该页面应该尽力尽早定义该术语——无论是明确定义还是通过交叉引用。
例如，Perl 喜欢使用文件句柄，因此该词在其文档中随处可见。第一次接触手册页的新手 Perl 程序员很可能不知道什么是“文件句柄”。任何提及文件句柄的 Perl 手册页都应该至少将该术语链接到 Perl 文档中的其他解释。如果合适——例如，在open 函数的详细参考的引言中——它也可以包含一个非常简短的现场概念定义，以方便读者理解。
在快速草拟示例时，英语程序员长期以来一直使用简短的无意义词作为变量和其他符号的占位符——例如著名的foo、bar 和 baz。然而，编程语言官方永久文档中的示例代码应该努力通过具体性提供更多清晰度。
只要有可能，代码示例应该为变量、类和其他程序员定义的符号提供明确表明其功能及其相互关系的名称。例如，如果示例要求一个类显示与另一个类的“is-a”关系，请考虑将其命名为Apple 和 Fruit，而不是 Foo 和 Bar。类似地，创建该类实例的示例代码最好将其命名为$apple，而不是 $baz。
即使是最简单的示例也受益于使用具体词语的清晰语言。优先使用for my $item (@items) { ... } 这样的结构，而不是 for my $blah (@blah) { ... }。
虽然本风格指南为了内部一致性将文档语言指定为美式英语，但作者应避免仅对英语母语人士（或任何其他特定文化或社会）可用的文化或习语参考。 尽可能地，Perl 核心文档使用的语言应力求文化上的普遍性，即使不是中立。 地区性的表达方式、基于流行文化知识的例子以及其他此类修辞技巧应该谨慎使用，如果有的话。
作者可以自由地在关于 Perl 的“二阶”文档中使用更自由的语言，例如书籍、博客文章和杂志文章，这些文档在其他地方出版，并针对更窄的读者群。 但 Perl 自身的文档应该使用尽可能广泛的受众都能理解和接受的语言。
占位符文本不属于 Perl 附带的文档。 任何节标题后面都不应该出现仅包含“敬请关注”、“待定”或类似内容的文本。 虽然 Perl 的源文件可能像任何其他积极维护的技术一样发生变化和改变，但其技术的每次发布迭代都应该感觉完整且自包含，没有任何此类未来承诺或其他松散的结尾可见。
利用 Perl 的定期发布周期。 与其用承诺将来提供更多信息的标记来使文档混乱——这些标记对今天的读者没有任何帮助——文档维护团队应该将任何已知的文档缺失视为 Perl 项目中需要解决的问题。 让 Perl 的贡献者、测试人员和发布工程师解决这个问题，并抵制插入道歉的诱惑，这些道歉在文档中的作用就像未删除的调试信息在生产代码中的作用一样。
无论语气多么平易近人，在技术文档中看到大块的文本都会对读者构成意志消沉的挑战。 作者可以通过将长段落分解成带有简短、有意义的标题的子节来改善这种情况。
由于 Pod 中的每个节标题也充当交叉引用（通过 Pod 的 L<...> 语法创建）的潜在终点，因此在文档中添加大量子节可以让其他手册页更精确地链接到特定主题。 这将创建直接指向最合适部分的超链接，而不是指向整个页面，并有助于为读者创造一种更连贯的丰富、一致和相互关联的手册的感觉。
在四种文档模式中，章节更自然地属于教程和解释器。烹饪书的逐步说明，或参考页面的简明定义，通常没有空间容纳它们。但作者总是可以为异常复杂的概念做出例外，这些概念需要进一步分解以确保清晰度。
另一方面，示例代码可以成为任何文档模式的欢迎补充。代码块有助于在视觉上分解手册页，让读者放心，无论文本解释有多深，他们永远不会远离另一个实际示例，该示例展示了如何使用一小段易于阅读的经过测试的 Perl 代码将所有内容整合在一起。
众所周知，Perl 为程序员提供了不止一种方法来完成任务。与任何其他长期存在的编程语言一样，Perl 也积累了大量由社区持有的最佳实践概念，将某些做事方式视为优于其他方式，通常是为了使代码更易于维护。
无论何时需要展示 Perl 提供多种途径的技巧规则，文档都应始终以最佳实践开头。在讨论 Perl 工具包中具有多种应用的部分时，文档应从演示其在最常见情况下的应用开始。
例如，open 函数在 Perl 程序中具有无数潜在用途，但大多数情况下程序员（尤其是 Perl 新手）会转向此参考，因为他们只是希望打开一个文件以进行读写。因此，open 的文档从这里开始，只有在彻底记录和演示了它在常见情况下的工作方式后，才会深入到该函数的更模糊的用途。此外，在进行此演示时，open 文档不会立即让读者负担过重，详细解释通过除最佳实践的三参数样式以外的任何方式调用 open。
有时，彻底性要求记录过时的技术。例如，某个 Perl 函数可能具有现在被认为过时且不再是最佳实践的备用语法，但遗留项目维护者在探索旧代码时可能会合理地遇到这种情况。在这种情况下，这些功能值得记录，但要以清晰的方式表达，即现代 Perl 避免了这种结构，并且不建议在新的项目中使用它们。
另一种看待这种理念的方式（也是从我们Python 文档团队的朋友那里借鉴来的）是，在编写文档时要设身处地地为刚接触 Perl 的程序员着想，他们可能对学习复杂的概念感到不确定。通过在每个概念的主要文档中提供清晰、积极的示例，我们可以立即让这些读者了解它在 Perl 中的工作原理，并增强他们使用这些新知识的信心。当然，我们应该在合理的情况下包含备选方案和注意事项，但我们不必强调它们。相信读者能够快速理解基本知识，并在需要时继续阅读以获得更深入的理解。
Perl 的文档应该集中在 Perl 的当前行为上，并对未来的方向有所提及。
当某个 Perl 特性改变其行为时，关于该特性的文档也应该随之改变，并且同样明确。文档没有义务保留对过去行为的描述，即使添加诸如“在 5.10 版本之前，[...]”之类的条款。
由于 Perl 的核心文档是 Perl 源代码分发的一部分，因此它与 Perl 本身的源代码一样，享有版本控制和版本控制的优势。利用这一点，并在需要时大胆更新文本。即使您从当前版本的文档中删除或替换过时的信息，Perl 的历史仍然是安全的。
Perl 的文档可以在有必要时承认或讨论以前的行为，包括一些特性从某个特定版本号开始出现在语言中的说明。作者应该考虑应用类似于弃用技术的原则，如上所述：提供信息，但不要突出显示。
否则，让过去成为过去。一本没有过时指令的手册会更加简洁和相关。
标记为“实验性”的 Perl 特性（在未调用 experimental pragma 的代码中使用时会生成警告）应该有文档，但只在某些情况下，即使有文档，也要加上警告。这些特性代表了 Perl 可能的未来发展方向，但它们具有不稳定的接口和不确定的未来存在。
对于“实验性”的含义，文档应该从字面上理解。它不应该阻止那些希望在可能存在风险的项目中尝试新功能的程序员使用这些功能；这种实验可以帮助 Perl 发展和改进。同样，文档应该淡化这些功能在几乎所有其他情况下的使用。
介绍性或概述材料应该完全省略对实验性功能的介绍。
更全面的参考材料或解释性文章可以包含实验性功能，但需要明确地将它们标记为实验性功能，并且不要像对待 Perl 的稳定功能那样突出它们。使用不稳定功能很少与最佳实践相符，而 将最佳实践放在首位 的文档应该反映这一点。
即使文档来自许多人，经过多年 Perl 的发展，它也应该保持一致的风格。除了少数例外，文档应该避免使用显式的第一人称单数陈述，或类似的自我引用，以反映任何个人贡献者的哲学或经验。
Perl 的诞生最初是个人表达，这在早期文档修订中也得到了体现。如今，Perl 社区认识到，语言的持续发展和支持来自许多人的共同努力，而不是任何一个人的愿景或努力。文档不应该假装相反。
然而，文档应该延续 Larry Wall 在语言早期奠定的最佳传统：既经济又谦逊，并带有微妙的幽默，从而形成一本既简洁又友好易懂的技术手册。它避免了技术文档中常见的枯燥乏味，同时也不过度依赖明显的幽默，以免分散读者对技术主题的注意力。
像最好的作品一样，Perl 的文档也有灵魂。作为读者，熟悉它并内化它的声音，然后找到自己的方式在自己的贡献中表达它。清晰、简洁地写作，并了解读者期望，将帮助你走上正确的道路。
文档中的每一行，无论是英文句子还是 Perl 语句，都应该服务于让读者理解的目的。如果一个句子只是为了讲一个与读者对 Perl 的理解无关的俏皮笑话，就应该把它放在一边，并考虑把它改写成个人博客文章或其他文章。
轻松地写作，并节俭地使用文字。
如上所述，本指南“继承”了《芝加哥格式手册》第 17 版中列出的所有首选术语，并添加了以下与 Perl 文档特别相关的术语。
不要使用“builtin”。
参见 macOS。
使用此术语来指代 Apple 的操作系统，而不是“Mac OS X”或其变体。
除非需要专门指代 macOS 的 Unix 层，否则此术语也优于“Darwin”。
Unix 风格文档的一个单元。不要使用“manpage”。优于“manual page”。
编程语言的名称是 Perl，首字母大写“P”，其余字母小写。（不要使用“PERL”。）
读取和执行 Perl 代码的解释器程序名为“perl”，小写，并使用等宽字体（与其他任何命令名称一样）。
通常，除非您专门编写有关命令行 perl 程序的内容（例如，perlrun），否则请使用“Perl”。
文档不需要在 Perl 的名称后面加“5”或任何其他数字，除非在讨论 Perl 的历史、未来计划或主要 Perl 版本之间的明确比较时。
在 2019 年之前，有时需要指定“Perl 5”来区分该语言和 Perl 6。随着后者更名为“Raku”，这种做法变得不再必要。
参见 Raku。
负责 Perl 持续维护和开发的团队的全称是“the Perl 5 Porters”，在任何一篇文档中第一次提及时应完整拼写。之后可以将该团队称为“the porters”或“p5p”。
不要使用“Perl5 Porters”。
对由可执行 Perl 代码组成的独立作品的最通用描述。与“脚本”同义，优于“脚本”。
Perl 的“姊妹语言”，其主页是 https://raku.perl5.cn。
以前称为“Perl 6”。2019 年，其设计团队将该语言更名为“Raku”，以更好地反映其作为独立于 Perl 的项目的身份。因此，Perl 的文档应始终将该语言称为“Raku”，而不是“Perl 6”。
参见 program。
Perl 代码中经常被忽视的标点符号。不是“semi-colon”。
不是“UNIX”、“*nix”或“Un*x”。适用于 1970 年代的原始操作系统及其所有概念上的后代。在提及类 Unix 操作系统时，您可以简单地写“Unix”，而不是“类 Unix 操作系统”。
本指南最初由 Jason McIntosh ([email protected]) 在 Perl 基金会的资助下起草。