pod2text - 将 POD 数据转换为格式化的 ASCII 文本
pod2text [-aclostu] [--code] [-e 编码] [--errors=样式] [--guesswork=规则[,规则...]] [-i 缩进] [-q 引号] [--nourls] [--stderr] [-w 宽度] [输入 [输出 ...]]
pod2text -h
pod2text 是 Pod::Text 及其子类的包装脚本。它使用它们从 POD 源生成格式化的文本。它可以选择使用术语表序列或 ANSI 颜色转义序列来格式化文本。
输入 是读取 POD 源的文件（POD 可以嵌入在代码中）。如果未给出 输入，则默认为 STDIN。如果给出了 输出，则它是写入格式化输出的文件。如果未给出 输出，则格式化输出将写入 STDOUT。可以通过在命令行上提供多个 输入 和 输出 文件对，在同一 pod2text 调用中处理多个 POD 文件（节省模块加载和编译时间）。
默认情况下，输出编码与输入文件的编码相同，如果未设置该编码，则为 UTF-8（EBCDIC 系统除外）。请参阅 -e 选项以明确设置输出编码，并参阅 Pod::Text 中的“编码” 以了解更多讨论。
每个选项都带有 podlators 版本的注释，其中该选项以其当前含义添加。
[1.00] 使用备用输出格式，其中包括使用不同的标题样式，并在左页边空白处用冒号标记 =item 条目。
[1.11] 在输出中包含输入文件中任何非 POD 文本。对于使用 POD 块记录的代码，在 POD 呈现且代码保持完整的情况下，此功能非常有用。
[1.00] 使用 ANSI 颜色转义序列设置输出格式。使用此选项需要在系统上安装 Term::ANSIColor。
[5.00] 指定输出的编码。encoding 必须是 Encode 模块识别的编码（请参阅 Encode::Supported）。如果输出包含无法在此编码中表示的字符，则这是一个错误，将根据 errors 选项的配置进行报告。如果错误处理不是 die，则不可表示的字符将替换为 Encode 替换字符（通常为 ?）。
警告：POD 源的输入编码独立于输出编码，设置此选项不会影响 POD 输入的解释。除非您的 POD 源是 US-ASCII，否则应在源中尽可能靠近文件顶部使用 =encoding 命令声明其编码。如果没有执行此操作，Pod::Simple 将尝试猜测编码，如果它是 Latin-1 或 UTF-8，则可能会成功，但它会产生警告。有关更多信息，请参阅 perlpod(1)。
[2.5.0] 设置错误处理样式。die 表示对任何 POD 格式错误抛出异常。stderr 表示在标准错误中报告错误，但不抛出异常。pod 表示在生成的文档中包含一个 POD ERRORS 部分，总结错误。none 尽可能完全忽略 POD 错误。
默认值为 die。
[5.01] 默认情况下，pod2text 应用一些默认格式化规则，这些规则基于猜测和正则表达式，旨在简化 Perl 文档的编写，并减少显式标记。这些规则可能并不总是适用，特别是对于与 Perl 无关的文档。此选项允许关闭全部或部分规则。
特殊规则 all 启用所有猜测。出于向后兼容性的原因，这也是默认值。特殊规则 none 禁用所有猜测。否则，此选项的值应为以下一个或多个关键字用逗号分隔的列表
如果未启用任何猜测，则 nroff（终端）输出中用 C<> 括起来的任何文本都将用双引号括起来，除非内容已用引号括起来。当启用此猜测时，Perl 变量、函数名、函数调用、数字和十六进制常量的引号也将被禁止。
任何未知的猜测名称都会被静默忽略（出于潜在的未来兼容性），因此请注意拼写。
[1.00] 设置缩进常规文本所需的空格数，以及 =over 块的默认缩进。如果未给出此选项，则默认为 4 个空格。
[1.00] 打印出使用信息并退出。
[1.00] 在 =head1 标题后打印一个空行。通常，=head1 后不会打印空行，尽管 =head2 后仍然会打印一个空行，因为这是手册页的预期格式；如果你正在格式化任意文本文档，建议使用此选项。
[1.24] 左边距的宽度（以空格为单位）。默认为 0。这是所有文本的边距，包括标题，而不是缩进常规文本的量；对于后者，请参见 -i 选项。
[2.5.0] 通常，带有 URL 但有锚文本的 L<> 格式化代码被格式化为同时显示锚文本和 URL。换句话说
L<foo|http://example.com/>格式化为
foo <http://example.com/>如果给定了此标志，则在给定锚文本时会禁止 URL，因此此示例将格式化为仅foo。在 URL 并不特别重要的情况下，这会产生不太杂乱的输出。
[1.06] 使用删除线打印格式化输出。粗体文本呈现为字符、退格、字符。斜体和文件名呈现为下划线、退格、字符。许多寻呼机（如less）知道如何将其转换为粗体或下划线文本。
[4.00] 将用于包围 C<> 文本的引号设置为quotes。如果quotes 是单个字符，则它用作左右引号。否则，它将被分成两半，字符串的前半部分用作左引号，后半部分用作右引号。
quotes 还可以设置为特殊值none，在这种情况下，不会在 C<> 文本周围添加引号。
[1.00] 假设每个句子以两个空格结尾，并尝试保留该间距。如果没有此选项，则非原义段落中的所有连续空格都会压缩成一个空格。
[2.1.3] 默认情况下，如果在 POD 输入中检测到任何错误，pod2text 会终止。如果给定了--stderr 且没有--errors 标志，则错误将发送到标准错误，但pod2text 不会中止。这等效于--errors=stderr，并且受支持以实现向后兼容性。
[1.00] 尝试从 termcap 确定屏幕的宽度以及终端的粗体和下划线序列，并在格式化输出时使用该信息。输出将在比终端设备宽度小两列的位置换行。使用此选项需要系统在 Term::Cap 可以找到它的某个位置具有 termcap 文件，并且需要系统支持 termios。使用此选项，pod2text 的输出将包含针对当前终端类型的终端控制序列。
[2.2.0] 将输出编码设置为 UTF-8。这等效于 --encoding=UTF-8，并且受支持以实现向后兼容性。
[1.00] 在右侧换行文本的列。默认为 76，除非给出了 -t，在这种情况下，它比终端设备的宽度少两列。
只要所有处理的文档都产生一些输出，即使该输出包含错误（使用 --errors=pod 生成的 POD ERRORS 部分），pod2text 将退出状态为 0。如果正在处理的任何文档未生成输出文档，则 pod2text 将退出状态为 1。如果正在处理的 POD 文档中存在语法错误，并且错误处理样式设置为默认的 die，则 pod2text 将立即中止，退出状态为 255。
如果 pod2text 因错误而失败，请参阅 Pod::Text 和 Pod::Simple 以了解这些错误可能意味着什么。在内部，它还可以生成以下诊断
(F) 给出了 -c 或 --color，但无法加载 Term::ANSIColor。
(F) 给出了未知的命令行选项。
此外，其他 Getopt::Long 错误消息可能由无效的命令行选项导致。
如果给出了 -t，则 pod2text 将从此环境变量（如果可用）获取屏幕的当前宽度。它将覆盖 TERMCAP 中的终端宽度信息。
如果给出了 -t，则 pod2text 将使用此环境变量的内容（如果可用）来确定当前终端设备的正确格式化序列。
Russ Allbery <[email protected]>。
版权所有 1999-2001、2004、2006、2008、2010、2012-2019、2022 Russ Allbery <[email protected]>
此程序是免费软件；你可以根据与 Perl 自身相同的条款重新发布和/或修改它。
Encode::Supported、Pod::Text、Pod::Text::Color、Pod::Text::Overstrike、Pod::Text::Termcap、Pod::Simple、perlpod(1)
此脚本的当前版本始终可从其网站 https://www.eyrie.org/~eagle/software/podlators/ 获取。它也是 Perl 5.6.0 及更高版本的核心发行版的一部分。