perlpodstyle

(源代码, CPAN)

#名称

perlpodstyle - Perl POD 样式指南

#说明

这些是基于编写良好 UNIX 手册页的通用指南，用于编写 Perl 脚本和模块的 POD 文档的通用指南。当然，所有这些指南都是可选的，但遵循它们会使你的文档与系统上的其他文档更加一致。

根据惯例，无论何时出现，都要以粗体（使用 B<>）编写正在记录的程序的名称，所有程序选项也是如此。参数应以斜体（I<>）编写。函数名称传统上以斜体编写；如果你将函数写为 function()，Pod::Man 将为你处理此问题。文字代码或命令应使用 C<>。对其他手册页的引用应采用 manpage(section) 或 L<manpage(section)> 形式，Pod::Man 将自动以适当的方式设置它们的格式。第二种形式（使用 L<>）用于请求 POD 格式化程序在可能的情况下链接到手册页。作为例外，引用模块文档时通常省略部分，因为不清楚模块文档将在哪个部分中；改为对模块引用使用 L<Module::Name>。

对其他程序或函数的引用通常采用手册页引用的形式，以便交叉引用工具能够为用户提供链接等。不过，这样做可能会适得其反，因此请注意不要用太多标记来弄乱文档。对未作为手册页引用给出的其他程序的引用应括在 B<> 中。

主要标题应使用 =head1 指令设置，并且历来以相当惊人的全大写格式编写；这不是强制性的，但强烈建议这样做，以便不同软件包中的部分具有统一的命名。可以使用 =head2 包含次要标题，并且通常采用混合大小写。

手册页的标准部分是

#NAME

强制部分；应是此 POD 页记录的程序或函数的逗号分隔列表，例如

foo, bar - programs to do something

手册页索引器通常对本部分的格式非常挑剔，因此除本行外，不要在其中放置任何内容。应列出此 POD 页记录的每个程序或函数，并用逗号和空格分隔。对于 Perl 模块，只需给出模块名称。一个破折号，且仅一个破折号，应将程序或函数列表与说明分隔开。不要在该行中的任何位置使用任何标记，例如 C<> 或 B<>。函数不应使用 () 或类似方式限定。理想情况下，说明应放在一行上，即使手册程序用几个制表符替换破折号也是如此。

#SYNOPSIS

程序和函数的简短使用摘要。本部分对于第 3 部分页面是强制性的。对于 Perl 模块文档，通常将本部分的内容设为一个逐字块，显示模块典型使用方法的一些（简要）示例，会很方便。

#DESCRIPTION

程序或函数的扩展说明和讨论，或记录其他内容的手册页的文档正文。如果特别长，最好将其分解为子部分 =head2 指令，例如

=head2 Normal Usage

=head2 Advanced Features

=head2 Writing Configuration Files

或适合文档的任何内容。

对于模块，这通常是模块提供的接口文档所在的位置，通常以列表的形式显示，每个接口都有一个 =item。根据接口的数量，您可能希望将该文档分别放在 METHODS、FUNCTIONS、CLASS METHODS 或 INSTANCE METHODS 部分，并保留 DESCRIPTION 部分以供概述。

#选项

程序采用的每个命令行选项的详细说明。这应与 Pod::Usage 等解析器的使用说明分开。这通常显示为一个列表，每个选项作为一个单独的 =item。特定的选项字符串应包含在 B<> 中。选项采用的任何值都应包含在 I<> 中。例如，选项 --section=manext 的部分将以以下内容开头

=item B<--section>=I<manext>

同义选项（如短形式和长形式）在同一 =item 行上用逗号和空格分隔，或选择性地列为自己的项目，并引用规范名称。例如，由于 --section 也可以写成 -s，因此上述内容将为

=item B<-s> I<manext>, B<--section>=I<manext>

建议先写短选项，因为这样更容易阅读。长选项足够长，无论如何都会吸引眼球，而短选项可能会在视觉噪声中迷失。

#返回值

如果成功，程序或函数返回的内容。对于退出代码不重要的程序，可以省略此部分，前提是它们在成功时返回 0，在失败时返回非 0，这是标准做法。对于函数，它应该始终存在。对于模块，在此处总结模块接口的返回值可能很有用，或者在模块提供的每个函数或方法的文档中分别讨论返回值可能更有用。

#错误

异常、错误返回代码、退出状态和 errno 设置。通常用于函数或模块文档；程序文档则使用 DIAGNOSTICS。一般规则是，打印到 STDOUT 或 STDERR 且面向最终用户的错误记录在 DIAGNOSTICS 中，而传递给调用程序内部且面向其他程序员的错误记录在 ERRORS 中。当记录设置 errno 的函数时，应在此处提供可能的 errno 值的完整列表。

#DIAGNOSTICS

程序可以打印出的所有可能消息及其含义。您可能希望遵循与 Perl 文档相同的文档风格；有关更多详细信息，请参阅 perldiag(1)（并查看 POD 源）。

如果适用，请包含用户应采取哪些措施来纠正错误的详细信息；将错误记录为指示“输入缓冲区太小”，而不告诉用户如何增加输入缓冲区的大小（或至少告诉他们这是不可能的），并没有什么用。

#EXAMPLES

提供程序或函数的一些示例用法。不要偷工减料；用户通常会发现这是文档中最有用的部分。示例通常作为逐字段落提供。

不要只提供示例而不解释其作用。添加一个简短的段落来说明示例的作用，可以极大地增加示例的价值。

#ENVIRONMENT

程序关心的环境变量，通常使用 =over、=item 和 =back 作为列表呈现。例如

=over 6

=item HOME

Used to determine the user's home directory.  F<.foorc> in this
directory is read for configuration details, if it exists.

=back

由于环境变量通常全部大写，因此通常不需要额外的特殊格式；它们本身就足够显眼了。

#FILES

程序或函数使用的所有文件，通常作为列表呈现，以及它将它们用于什么。文件名应括在 F<> 中。记录可能被修改的文件尤为重要。

#CAVEATS

需要特别注意的事项，有时称为 WARNINGS。

#BUGS

已损坏或无法正常工作的事项。

#RESTRICTIONS

您不打算修复的错误。 :-)

#注释

其他评论。

#作者

撰写者（多人使用 AUTHORS）。最好包含您的当前电子邮件地址（或应发送错误报告的电子邮件地址）或其他联系方式，以便用户可以与您联系。请记住，程序文档往往会比您预期的时间长，因此请选择一种可能持续存在的联系方式。

#历史记录

源自其他来源的程序有时会有此记录。有些人在此处保留修改日志，但这通常会很长，通常最好在单独的文件中维护。

#版权和许可证

版权

Copyright YEAR(s) YOUR NAME(s)

获得许可的最简单方法是使用与 Perl 本身相同的许可

This library is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.

这使用户可以轻松地将您的模块与 Perl 一起使用。请注意，此许可示例既不是认可也不是要求，您当然可以自由选择任何许可。

#另请参阅

其他手册页，如 man(1)、man(7)、makewhatis(8) 或 catman(8)。通常是用逗号分隔的手册页的简单列表，或给出参考书名称的段落。手册页引用如果使用标准的 name(section) 形式，则不必用 L<> 括起来（尽管建议这样做），但本节中的其他内容在适当的时候可能应该这样做。

如果软件包有邮件列表，请在此处包含 URL 或订阅说明。

如果软件包有网站，请在此处包含 URL。

面向对象库或模块的文档可能希望使用 CONSTRUCTORS 和 METHODS 部分，或 CLASS METHODS 和 INSTANCE METHODS 部分，以详细记录库的各个部分，并将 DESCRIPTION 部分保存为概述。具有函数接口的大型模块可能出于类似的原因使用 FUNCTIONS。如果描述很长，有些人会使用 OVERVIEW 来总结描述。

部分顺序会有所不同，尽管 NAME 必须始终是第一个部分（否则您将破坏某些手册页系统），如果存在，NAME、SYNOPSIS、DESCRIPTION 和 OPTIONS 通常始终首先按该顺序出现。一般来说，SEE ALSO、AUTHOR 和类似的材料应留到最后。一些系统还将 WARNINGS 和 NOTES 移到最后。上面给出的顺序应该适用于大多数目的。

某些系统使用 CONFORMING TO 来标注与相关标准的一致性，并使用 MT-LEVEL 来标注在多线程程序或信号处理程序中使用时的安全性。这些标题主要在记录 C 库的部分时有用。

最后，作为一般性说明，请尽量不要使用过多的标记。如本文档和 Pod::Man 中所记录，你可以安全地不使用标记修饰 Perl 变量、函数名称、手册页引用等，POD 翻译器会为你弄清楚。这使得以后编辑文档变得更加容易。请注意，许多现有的翻译器在用 L<> 包装电子邮件地址时会做错，所以不要这样做。

#作者

Russ Allbery <[email protected]>，本部分文档的大部分内容取自 Larry Wall 和 Tom Christiansen 对原始 pod2man 实现的文档。

#版权和许可证

SPDX-License-Identifier: FSFAP

#另请参阅

有关可能更准确的附加信息，请参阅 man(5) 或 man(7)，具体取决于你的系统手册部分编号约定。

此文档作为 podlators 分发的一部分进行维护。当前版本始终可在其网站 https://www.eyrie.org/~eagle/software/podlators/ 上获得。

目录

#名称

#说明

#作者

#版权和许可证

#另请参阅