内容

• 名称
• 语法
• 选项/参数
  • podchecker()
• 描述
• 诊断
  • 错误
  • 警告
  • 超链接
• 返回值
• 示例
• 脚本
• 接口
• 作者

#名称

Pod::Checker - 检查 Pod 文档的语法错误

#语法

use Pod::Checker;

$syntax_okay = podchecker($filepath, $outputpath, %options);

my $checker = Pod::Checker->new(%options);
$checker->parse_from_file($filepath, \*STDERR);

#选项/参数

$filepath 是要读取的输入 POD，$outputpath 是要写入 POD 语法错误消息的位置。任一参数都可以是表示文件路径的标量，也可以是对打开的文件句柄的引用。如果未指定，则输入文件默认为 \*STDIN，输出文件默认为 \*STDERR。

#podchecker()

此函数可以采用一个选项哈希

#-warnings => val

打开/关闭警告。val 通常为 1 表示打开，但较高的值会触发其他警告。请参见 "Warnings"。

#-quiet => val

如果 val 为真，则不打印任何错误/警告。

#说明

podchecker 将对 Perl5 POD 格式文档执行语法检查。

欢迎好奇/有抱负的用户提出他们希望在 Pod::Checker 和 podchecker 中看到的其他功能，并验证这些检查是否与 perlpod 一致。

目前执行以下检查

• 未知的“=xxxx”命令、未知的“X<...>”内部序列以及未终止的内部序列。

• 检查 =begin 和 =end 的正确平衡。此类块的内容通常会被忽略，即不执行任何语法检查。

• 检查 =over、=item 和 =back 的正确嵌套和平衡。

• 检查相同的嵌套内部序列（例如 L<...L<...>...>）。

• 检查格式错误或不存在的实体 E<...>。

• 检查超链接 L<...> 的正确语法。有关详细信息，请参阅 perlpod。

• 检查未解析的文档内部链接。此检查还可能显示拼写错误的链接，这些链接看起来像是内部链接，但应该是指向其他内容的链接。

#诊断

#错误

• 空 =headn

  没有文本的标题（=head1 或 =head2）？那不是标题！

• 第 N 行的 =over 没有关闭 =back

• 你在“=headN”之前忘记了“=back”

• =over 是文档中的最后一项？！

  =over 命令在下一个标题（=head1 或 =head2）或文件结尾之前没有对应的 =back。

• '=item' 在任何 '=over' 之外

• =back 没有 =over

  在 =over/=back 块之外找到了 =item 或 =back 命令。

• 在 =over N 中不能有 0

  你需要缩进一个严格为正的空格数，而不是 0。

• =over 应该是：'=over' 或 '=over positive_number'

  要么没有参数的 =over，要么其参数是一个严格为正的数字。

• =begin TARGET 没有匹配的 =end TARGET

  找到了一个没有匹配的 =end 命令的 =begin 命令。

• =begin 没有目标？

  找到了一个未跟随格式化程序规范的 =begin 命令。

• =end TARGET 没有匹配的 =begin。

  找到了一个独立的 =end 命令。

• '=end' 没有目标？

  '=end' 指令需要有一个目标，就像 =begin 指令一样。

• '=end TARGET' 无效。

  TARGET 需要是一个单词

• =end CONTENT 与 =begin TARGET 不匹配

  内容需要匹配 =begin 的目标。

• =for 没有目标？

  =for 命令后未指定格式化程序。

• 未解析的内部链接名称

  给定的到名称的链接在当前 POD 中没有匹配的节点。当未用 "" 括起单字节点名称时也会发生这种情况。

• 未知指令：CMD

  已找到无效的 POD 命令。有效命令包括 =head1、=head2、=head3、=head4、=over、=item、=back、=begin、=end、=for、=pod、=cut

• 删除未知格式化代码SEQ

  已遇到无效的标记命令。有效命令包括：B<>、C<>、E<>、F<>、I<>、L<>、S<>、X<>、Z<>

• 未终止的SEQ<>序列

  未关闭的格式化代码

• E<...> 围绕着奇怪的内容

  找不到的字符串无法解释为字符实体。

• 一个空的 E<>

• 一个空的 L<>

• 一个空的 X<>

  E、L 和 X 格式化代码中需要有内容。

• =pod / =cut 之后有杂散文本

  =pod 和 =cut 命令不接受任何参数。

• =back 不接受任何参数，但您说了 =back 参数

  =back 命令不接受任何参数。

• =pod 指令不应超过一行长！忽略所有N行内容

  不言自明

• =cut 在 pod 块外部找到。

  在非 POD 中间找到一个“=cut”指令

• 无效的 =encoding 语法：内容

  =encoding 指令中的语法错误

#警告

这些不一定造成麻烦，但表示风格平庸。

• 嵌套命令CMD<...CMD<...>...>

  已找到两个嵌套的相同标记命令。通常这是没有意义的。

• 链接目标名称出现多次（N 次）

  POD 文件中有一些 =item 和/或 =head 命令具有相同的文本。在这种情况下，指向此类文本的潜在超链接无法唯一。此警告仅在警告级别大于 1 时打印。

• 段落中仅包含空白的行

  看似空行上有一些空白。POD 对此类内容非常敏感，因此会标记出来。vi 用户开启 list 选项以避免此问题。

• =item 没有内容

  有一个列表 =item 没有文本内容。您可能想要删除空项。

• 除非在 =over 之后的第一个内容是 =item，否则您不能有 =item（如第 N 行）

  由 =over 引入的列表以文本或逐字段落开头，但以 =item 继续。将非项目段落移出 =over/=back 块。

• 预期“=item 预期值”

• 预期“=item *”

• 可能的 =item 类型不匹配：“x” 发现导致假定的定义 =item

  一个列表以例如项目符号状的 =item 开头，并以编号列表继续。这显然不一致。对于大多数翻译者，第一个 =item 的类型决定了列表的类型。

• 您有“=item x”而不是预期的“=item N”

  错误编号 =item 编号；它们需要连续递增。

• E<内容> 中未知的 E 内容

  发现了一个不属于标准 ISO 集或 POD 特殊字符 verbar 和 sol 的字符实体。目前，此警告仅在发现没有 Unicode 字符的字符实体时才会出现。应该修复此问题以符合原始警告。

• 空的 =over/=back 块

  用 =over 打开的列表不包含任何内容。

• 前一段落中的空部分

  前一段落（由 =head 命令引入）不包含任何有效内容。这通常表示缺少某些内容。注意：紧跟 =head2 之后的 =head1 不会触发此警告。

• NAME 部分中的逐字段落

  NAME 部分（=head1 NAME）应由一个段落组成，其中包含脚本/模块名称，后跟一个破折号 `-` 和对该事物用途的非常简短的描述。

• =headn 没有前置更高级别

  例如，如果在 POD 文件中，=head2 位于 =head1 之前。

• 非空的 Z<>

  Z<> 序列应该为空。警告：此问题在 Pod::Simple 中被检测到，并且会被任何客户端代码标记为 ERROR；Z<...> 的任何内容都会被忽略。

#超链接

对于格式错误的超链接，有一些警告

• 忽略链接中前导/尾随空格

  L<...> 的内容的开头或结尾有空格。

• 备用文本/节点“%s”包含未转义的 | 或 /

  在 L<...> 上下文中，| 和 / 字符是特殊的。尽管超链接解析器会尽力确定在有疑问的情况下哪个“/”是文本，哪个是分隔符，但应该像这样转义这些文字字符

  /     E<sol>
  |     E<verbar>

请注意，错误/警告的行号可能指的是错误/警告所在的段落的开始行号，而不是错误/警告所在的行号。此错误存在于与格式代码相关的错误/警告中。此问题应得到修复。

#返回值

podchecker 返回找到的 POD 语法错误数，如果文件中根本没有找到 POD 命令，则返回 -1。

#示例

请参见 "SYNOPSIS"

#脚本

此发行版附带的 podchecker 脚本是此模块的一个精简包装器。请使用以下命令查看在线手册

podchecker -help
podchecker -man

#接口

在检查时，此模块会收集文档属性，例如超链接的节点（=headX、=item）和索引条目（X<>）。POD 翻译器可以在实际开始转换之前使用此功能进行语法检查并获取节点。这在执行时间方面代价较高，但允许进行非常可靠的转换。

从 v1.24 开始，Pod::Checker 模块仅使用 poderror 方法来打印错误和警告。摘要输出（例如“Pod 语法正常”）已从模块中删除，并已包含在 podchecker（脚本）中。这使用户可以完全控制输出行为。podchecker（脚本）的用户可以获得众所周知的行为。

v1.45 继承自 Pod::Simple，而所有以前版本都继承自 Pod::Parser。在使用 Pod::Checker 时，不要使用 Pod::Simple 的接口，除非此页面上某个地方有记录。我再说一遍，不要使用 POD::SIMPLE 的接口。

以下列表记录了对 Pod::Simple 的覆盖，主要是为了让 Pod::Coverage 满意

#end_B

#end_C

#end_Document

#end_F

#end_I

#end_L

#end_Para

#end_S

#end_X

#end_fcode

#end_for

#end_head

#end_head1

#end_head2

#end_head3

#end_head4

#end_item

#end_item_bullet

#end_item_number

#end_item_text

#handle_pod_and_cut

#handle_text

#handle_whiteline

#hyperlink

#scream

#start_B

#start_C

#start_Data

#start_F

#start_I

#start_L

#start_Para

#start_S

#start_Verbatim

#start_X

#start_fcode

#start_for

#start_head

#start_head1

#start_head2

#start_head3

#start_head4

#start_item_bullet

#start_item_number

#start_item_text

#start_over

#start_over_block

#start_over_bullet

#start_over_empty

#start_over_number

#start_over_text

#whine

#Pod::Checker->new( %options )

返回对一个新的 Pod::Checker 对象的引用，该对象继承自 Pod::Simple，用于稍后调用所需的方法。识别以下选项

-warnings => num 如果 num 为 true，则打印警告。num 的值越高，打印的警告越多。目前只有 1 和 2 两个级别。

-quiet => num 如果 num 为真，则不打印任何错误/警告。当 Pod::Checker 用于将 POD 代码从 POD 格式化程序中转换成纯文本时，此功能非常有用。

#$checker->poderror( @args )

#$checker->poderror( {%opts}, @args )

用于打印错误和警告的内部方法。如果没有给出选项，则仅打印“@_”。识别以下选项并将其用于形成输出

-msg

在 @args 之前打印的消息。

-line

发生错误的行号。

-file

发生错误的文件（名称）。默认为正在处理的当前文件的文件名。

-severity

错误级别，应为“WARNING”或“ERROR”。

#$checker->num_errors()

设置（如果指定了参数）并检索找到的错误数。

#$checker->num_warnings()

设置（如果指定了参数）并检索找到的警告数。

#$checker->name()

设置（如果指定了参数）并检索在 =head1 NAME 部分中找到的 POD 的规范名称。

#$checker->node()

添加（如果指定了参数）并检索当前 POD 的节点（由 =headX 和 =item 定义）。节点按其出现的顺序返回。它们由纯文本组成，每一块空白都折叠成一个空格。

#$checker->idx()

添加（如果指定了参数）并检索当前 POD 的索引条目（由 X<> 定义）。它们由纯文本组成，每一块空白都折叠成一个空格。

#$checker->hyperlinks()

检索一个包含指向当前 POD 外部内容的超链接的数组（由 L<> 定义）。

每个都是一个类的实例，具有以下方法

#line()

返回遇到链接的大致行号

#type()

返回链接的类型；其中之一："url"（用于类似 http://www.foo 的内容）、"man"（用于手册页）或 "pod"。

#page()

返回链接到的页面或 URL。

#node()

返回链接到的页面中的锚点或节点，如果链接中没有出现锚点或节点，则返回空字符串 ("")。

#AUTHOR

请使用 http://rt.cpan.org 报告错误。

Brad Appleton <[email protected]>（初始版本），Marek Rouchal <[email protected]>，Marc Green <[email protected]>（移植到 Pod::Simple），Ricardo Signes <[email protected]>（更多移植到 Pod::Simple），Karl Williamson <[email protected]>（更多移植到 Pod::Simple）

基于 Tom Christiansen <[email protected]> 编写的 Pod::Text::pod2text() 的代码。

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如有任何关于网站本身、搜索或文档呈现的问题，请联系他，途径为 GitHub 问题追踪器 或 电子邮件。

Perl 文档由 Perl 5 Porters 在 Perl 开发中维护。如有任何关于文档内容或格式的问题，请联系他们，途径为 Perl 问题追踪器、邮件列表 或 IRC。