Pod::Text - 将 POD 数据转换为格式化文本
use Pod::Text;
my $parser = Pod::Text->new (sentence => 1, width => 78);
# Read POD from STDIN and write to STDOUT.
$parser->parse_from_filehandle;
# Read POD from file.pod and write to file.txt.
$parser->parse_from_file ('file.pod', 'file.txt');Pod::Text 是一个模块，可以将 POD 格式的文档（Perl 文档的首选语言）转换为格式化文本。它不使用任何特殊的格式控制或代码，因此其输出适合几乎所有设备。
Pod::Text 使用以下逻辑来选择输出编码，按顺序：
如果在输出文件句柄上设置了 PerlIO 编码层，则不进行任何输出编码，而是依赖 PerlIO 编码层。
如果设置了 encoding 或 utf8 选项，则使用这些选项指定的输出编码。
如果 POD 源文件的输入编码被显式指定（使用 =encoding）或由 Pod::Simple 自动检测，则也将其用作输出编码。
否则，如果在非 EBCDIC 系统上运行，则使用 UTF-8 作为输出编码。由于这是 ASCII 的超集，因此除非 POD 输入包含非 ASCII 字符而没有声明或自动检测编码（通常通过 E<> 转义），否则这将导致 ASCII 输出。
否则，对于 EBCDIC 系统，输出时不进行任何编码，希望这能起作用。
有一点需要注意：Pod::Text 必须在第一次输出非 ASCII 字符时确定输出编码，并且为了保持一致性，必须一直使用它。但是，=encoding 命令不必位于 POD 文档的开头。如果有人在文档开头使用转义字符（例如 E<0xEF>）输入非 ASCII 字符，然后在后面添加 =encoding iso-8859-1，理想情况下，Pod::Text 会遵循规则 3 并将整个文档输出为 ISO 8859-1。相反，它会在看到该转义字符后立即根据规则 4 确定为 UTF-8，然后在文档的其余部分保持该编码。
不幸的是，没有通用的最佳输出编码选择。每种选择在某些情况下都会不正确。选择这种方法主要是为了向后兼容。如果调用者知道用户可能期望的编码，则应考虑通过 encoding 强制输出编码。
特别是，如果可用，请考虑导入 Encode::Locale 模块，并将 encoding 设置为 locale，以使用适合用户区域设置的输出编码。但请注意，如果用户没有使用区域设置或使用的是 C 区域设置，Encode::Locale 会将输出编码设置为 US-ASCII。这会导致所有非 ASCII 字符被替换为 ?，并产生大量关于不支持字符的警告，这可能是你想要的，也可能不是。
创建一个新的 Pod::Text 对象。ARGS 应该是一个键值对列表，其中键从以下选项中选择。每个选项都用 Pod::Text 版本进行注释，该版本添加了该选项及其当前含义。
[2.00] 如果设置为真值，则选择一种备用输出格式，该格式除了其他内容外，还使用不同的标题样式，并在左边缘用冒号标记 =item 条目。默认为 false。
[2.13] 如果设置为真值，则输入文件的非 POD 部分将包含在输出中。这对于查看使用 POD 块进行文档化的代码很有用，其中 POD 已渲染，代码保持不变。
[5.00] 指定输出的编码。该值必须是 Encode 模块识别的编码（参见 Encode::Supported）。如果输出包含无法用此编码表示的字符，则会发生错误，并根据 errors 选项配置的错误报告方式进行报告。如果错误处理方式不是 die，则不可表示的字符将被替换为 Encode 替换字符（通常为 ?）。
如果输出文件句柄设置了 PerlIO 编码层，则此参数将被忽略，Pod::Man 不会进行任何编码。它将依赖于编码层来执行所需的输出编码转换。
警告：POD 源的输入编码与输出编码无关，设置此选项不会影响 POD 输入的解释。除非您的 POD 源是 US-ASCII，否则应在源文件中使用 =encoding 命令声明其编码，尽可能靠近文件顶部。如果未执行此操作，Pod::Simple 将尝试猜测编码，如果它是 Latin-1 或 UTF-8，则可能会成功，但会产生警告。有关更多信息，请参见 perlpod(1)。
[3.17] 如何报告错误。die 表示在任何 POD 格式化错误时抛出异常。stderr 表示在标准错误中报告错误，但不抛出异常。pod 表示在生成的文档中包含一个 POD ERRORS 部分，总结错误。none 完全忽略 POD 错误，尽可能地。
默认值为 pod。
[5.01] 默认情况下，Pod::Text 会应用一些基于猜测和正则表达式的默认格式化规则，这些规则旨在使编写 Perl 文档更容易，并减少显式标记的需求。这些规则并不总是适用，特别是对于与 Perl 无关的文档。此选项允许关闭全部或部分猜测。
特殊值 all 启用所有猜测。出于向后兼容性的原因，这也是默认值。特殊值 none 禁用所有猜测。否则，此选项的值应为以下关键字之一或多个的逗号分隔列表
如果未启用任何猜测，则在 nroff（终端）输出中，任何用 C<> 括起来的文本都将用双引号包围，除非内容已用引号包围。当启用此猜测时，引号也会被抑制，用于 Perl 变量、函数名、函数调用、数字和十六进制常量。
任何未知的猜测名称都会被静默忽略（为了潜在的未来兼容性），因此请注意拼写。
[2.00] 用于缩进常规文本的空格数，也是=over块的默认缩进。默认为 4。
[2.00] 如果设置为真值，则在=head1标题后打印一个空行。如果设置为假值（默认值），则在=head1后不打印空行，尽管在=head2后仍然打印一个空行。这是默认值，因为它是在手册页中预期的格式；如果您正在格式化任意文本文档，将此设置为 true 可能会导致更令人愉悦的输出。
[2.21] 左边距的宽度（以空格为单位）。默认为 0。这是所有文本的边距，包括标题，而不是常规文本缩进的量；对于后者，请参见indent选项。要设置右边距，请参见width选项。
[3.17] 通常，带有 URL 但有锚文本的 L<> 格式化代码被格式化为显示锚文本和 URL。换句话说
L<foo|http://example.com/>被格式化为
foo <http://example.com/>此选项，如果设置为真值，则在给出锚文本时会抑制 URL，因此此示例将仅格式化为foo。在 URL 不太重要的情况下，这可以产生更简洁的输出。
[4.00] 设置用于包围 C<> 文本的引号。如果值为单个字符，则它用作左引号和右引号。否则，它会被分成两半，字符串的前半部分用作左引号，后半部分用作右引号。
这也可以设置为特殊值none，在这种情况下，不会在 C<> 文本周围添加引号。
[3.00] 如果设置为真值，Pod::Text 将假定每个句子以两个空格结尾，并尝试保留该空格。如果设置为假值，则非文字段落中的所有连续空格将压缩为单个空格。默认为假值。
[3.10] 将有关无效 POD 的错误消息发送到标准错误，而不是将 POD ERRORS 部分附加到生成的输出中。这等效于将errors设置为stderr（如果errors尚未设置）。它支持向后兼容性。
[3.12] 如果此选项设置为真值，则输出编码将设置为 UTF-8。这等效于将encoding设置为UTF-8（如果encoding尚未设置）。它支持向后兼容性。
[2.00] 文本在右侧换行的列。默认为 76。
作为 Pod::Simple 的派生类，Pod::Text 支持相同的方法和接口。有关所有详细信息，请参阅 Pod::Simple。本节总结了最常用的方法以及 Pod::Text 添加的方法。
将 parse_file()、parse_lines() 或 parse_string_document() 的输出定向到文件句柄 FH，而不是 STDOUT。
将 parse_file()、parse_lines() 或 parse_string_document() 的输出定向到 REF 指向的标量变量，而不是 STDOUT。例如
my $man = Pod::Man->new();
my $output;
$man->output_string(\$output);
$man->parse_file('/some/input/file');请注意，该变量中的输出将已编码（请参阅 "Encoding"）。
从 PATH 读取 POD 源并格式化它。默认情况下，输出将发送到 STDOUT，但可以使用 output_fh() 或 output_string() 方法更改此设置。
从 INPUT 读取 POD 源，格式化它，并将结果输出到 OUTPUT。
parse_from_filehandle() 用于与旧版本的 Pod::Man 向后兼容。应改用 parse_from_file()。
将提供的行解析为 POD 源，将输出写入 STDOUT 或使用 output_fh() 或 output_string() 方法设置的文件句柄。此方法可以重复调用以提供更多输入行。应传递显式的 undef 以指示输入结束。
此方法期望的是原始字节，而不是解码后的字符。
将提供的标量变量解析为 POD 源，将输出写入 STDOUT 或使用 output_fh() 或 output_string() 方法设置的文件句柄。
此方法期望的是原始字节，而不是解码后的字符。
Pod::Text 导出一个函数，用于与旧版本向后兼容。此函数已弃用；应改用上面描述的面向对象的接口。
将 INPUT 中的 POD 源代码转换为文本并写入 OUTPUT。如果未指定 OUTPUT，则默认为 STDOUT。INPUT 可以是任何支持作为两个参数 open() 的第二个参数的表达式。
如果 -a 作为初始参数给出，则将 alt 选项传递给 Pod::Text 构造函数。这将启用备用格式。
如果 -NNN 作为初始参数给出，则将 width 选项传递给 Pod::Text 构造函数，并将数字 NNN 作为其参数。这将换行宽度设置为 NNN。
(W) 内部 =item 处理过程中出现错误。这些消息表明 Pod::Text 中存在错误；您不应该看到它们。
(F) Pod::Text 通过兼容模式 pod2text() 接口调用，并且它给定的输入文件无法打开。
(F) 构造函数的 errors 参数设置为未知值。
(F) 给定的引号规范（构造函数的 quotes 选项）无效。引号规范必须是一个字符长或一个偶数（大于一个）字符长。
(F) 正在格式化的 POD 文档存在语法错误，并且 errors 选项设置为 die。
Pod::Text 2.03（基于 Pod::Parser）是 Perl 5.6.0 中包含的此模块的第一个版本。早期版本的 Perl 有一个不同的 Pod::Text 模块，具有不同的 API。
基于 Pod::Simple 的当前 API 添加于 Pod::Text 3.00 版本。Pod::Text 3.01 版本包含在 Perl 5.9.3 中，这是第一个包含这些更改的 Perl 版本。这是第一个正确支持所有现代 POD 语法的版本。parse_from_filehandle() 方法为了向后兼容性在 Pod::Text 3.07 中重新添加，包含在 Perl 5.9.4 中。
Pod::Text 3.12 版本包含在 Perl 5.10.1 中，首次实现了当前的做法，即尝试将默认输出编码与 POD 源的输入编码匹配，除非被 utf8 选项（后来添加）或 encoding 选项覆盖。
对 URL 类型 L<> 链接中的锚文本的支持是在 Pod::Text 3.14 版本中添加的，包含在 Perl 5.11.5 中。
从 Pod::Text 3.18 版本开始，包含在 Perl 5.19.5 中，parse_lines()、parse_string_document() 和 parse_file() 方法如果尚未设置默认输出文件句柄，则将其设置为 STDOUT。
Pod::Text 4.00 版本包含在 Perl 5.23.7 中，对齐了模块版本和 podlators 发行版的版本。从该版本开始，podlators 中包含的所有模块以及 podlators 发行版本身都共享相同的版本号。
Pod::Text 4.09 版本包含在 Perl 5.25.7 中，修复了 EBCDIC 系统上的一个严重错误，该错误存在于 3.00 版本及更早版本中，会导致左括号消失。
Pod::Text 5.00 版本现在在非 EBCDIC 系统上默认使用 UTF-8 编码，前提是它在输入中看到非 ASCII 字符并且未指定输入编码。它还会在遇到第一个非 ASCII 字符时确定编码，并且如果输入编码发生变化，则不会更改输出编码。现在使用 Encode 模块进行所有输出编码，而不是 PerlIO 层，这修复了之前输出到标量时的错误。
Russ Allbery <[email protected]>，在很大程度上基于 Tom Christiansen <[email protected]> 的原始 Pod::Text 以及 Brad Appleton <[email protected]> 将其转换为 Pod::Parser。Sean Burke 最初将 Pod::Man 转换为使用 Pod::Simple，为如何使用 Pod::Simple 提供了必要的指导。
版权所有 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022 Russ Allbery <[email protected]>
本程序是自由软件；您可以在 Perl 本身相同的条款下重新发布和/或修改它。
Encode::Locale，Encode::Supproted，Pod::Simple，Pod::Text::Termcap，perlpod(1)，pod2text(1)
本模块的当前版本始终可从其网站获取：https://www.eyrie.org/~eagle/software/podlators/。它也是 Perl 核心发行版的一部分，从 5.6.0 版本开始。