pod2man - 将 POD 数据转换为格式化的 *roff 输入
pod2man [--center=string] [--date=string] [--encoding=encoding] [--errors=style] [--fixed=font] [--fixedbold=font] [--fixeditalic=font] [--fixedbolditalic=font] [--guesswork=rule[,rule...]] [--name=name] [--nourls] [--official] [--release=version] [--section=manext] [--quotes=quotes] [--lquote=quote] [--rquote=quote] [--stderr] [--utf8] [--verbose] [input [output] ...]
pod2man --help
pod2man 是围绕 Pod::Man 模块的包装脚本，使用它从 POD 源代码生成 *roff 输入。生成的 *roff 代码适合使用 nroff(1) 在终端上显示，通常通过 man(1)，或者使用 troff(1) 打印。
默认情况下（在非 EBCDIC 系统上），pod2man 输出 UTF-8 手册页。它的输出应该适用于使用 groff（大多数 Linux 发行版）或 mandoc（大多数 BSD 变体）的系统上的 man 程序，但在较旧的 UNIX 系统上可能会导致输出混乱。要在这些系统上选择不同的、可能更向后兼容的输出处理，请使用 --encoding=roff（早期 Pod::Man 版本中的默认值）。有关更多详细信息，请参见 --encoding 选项和 "Pod::Man 中的 ENCODING"。
input 是要读取 POD 源代码的文件（POD 可以嵌入到代码中）。如果未提供 input，则默认为 STDIN。如果提供了 output，则为写入格式化输出的文件。如果未提供 output，则格式化输出将写入 STDOUT。通过在命令行上提供多个 input 和 output 文件对，可以在同一个 pod2man 调用中处理多个 POD 文件（节省模块加载和编译时间）。
--section、--release、--center、--date 和 --official 可用于设置要使用的页眉和页脚。如果未指定，Pod::Man 将使用各种默认值。有关详细信息，请参见下文。
每个选项都标注了该选项在 podlators 中添加的版本及其当前含义。
[1.00] 将 .TH 宏的居中页眉设置为 string。默认值为 User Contributed Perl Documentation，但也可以参见下面的 --official。
[4.00] 将 .TH 宏的左页脚字符串设置为 string。默认情况下，将使用 POD_MAN_DATE、SOURCE_DATE_EPOCH、输入文件修改日期或当前日期（如果输入来自 STDIN）中的第一个，并且日期将为 UTC。有关详细信息，请参见 "Pod::Man 中的类方法"。
[5.00] 指定输出的编码。encoding 必须是 Encode 模块识别的编码（参见 Encode::Supported）。非 EBCDIC 系统上的默认值为 UTF-8。
如果输出包含无法在此编码中表示的字符，则会发生错误，该错误将根据 --errors 选项的配置进行报告。如果错误处理不是 die，则不可表示的字符将被替换为 Encode 替换字符（通常为 ?）。
如果 encoding 选项设置为特殊值 groff（EBCDIC 系统上的默认值），或者如果 Encode 模块不可用并且编码设置为除 roff 之外的任何值（参见下文），Pod::Man 将把所有非 ASCII 字符转换为 \[uNNNN] Unicode 转义符。这些传统上不是 *roff 语言的一部分，但受 groff 和 mandoc 以及当今使用的大多数手册页处理器支持。
如果encoding设置为特殊值roff，pod2man将执行其历史上的转换（某些）ISO 8859-1 字符到*roff 转义符，这些转义符可能在 troff 中足够，并且可能在 nroff 中可读（即使很丑）。这是 5.00 之前版本的 pod2man 的默认行为。使用此编码，所有其他非 ASCII 字符将被替换为 X。对于不支持 UTF-8 的非常旧的 troff 和 nroff 实现，这可能是必需的，但它对任何非 ASCII 字符的表示都非常差，并且通常特定于欧洲语言。不建议使用它。
警告：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。
[1.0] 用于逐字文本和代码的固定宽度字体。默认为 CW。某些系统可能需要 CR。仅对 troff 输出有效。
[1.0] 固定宽度字体的粗体版本。默认为 CB。仅对 troff 输出有效。
[1.0] 固定宽度字体的斜体版本（有点用词不当，因为大多数固定宽度字体只有斜体版本，而不是斜体版本）。默认为 CI。仅对 troff 输出有效。
[1.0] 固定宽度字体的粗体斜体（理论上，实际上可能是倾斜）版本。Pod::Man 不假定您拥有此字体，并默认使用 CB。一些系统（如 Solaris）提供此字体，名为 CX。仅对 troff 输出有效。
[5.00] 默认情况下，pod2man 会应用一些基于猜测和正则表达式的默认格式化规则，这些规则旨在简化 Perl 文档的编写，并减少显式标记的需求。这些规则可能并不总是适用，特别是对于与 Perl 无关的文档而言。此选项允许关闭所有或部分猜测规则。
特殊规则 all 启用所有猜测规则。出于向后兼容性的原因，这也是默认设置。特殊规则 none 禁用所有猜测规则。否则，此选项的值应为一个或多个以下关键字的逗号分隔列表
将函数引用（如 foo()）转换为粗体，即使它们没有标记。函数名称接受有效的 Perl 函数名称字符（包括 :），并且尾随括号必须存在且为空。
使手册页引用（如 foo(1)）的第一部分（括号之前）变为粗体，即使它们没有标记。节号必须是一个数字，可选地后跟小写字母。
如果未启用任何猜测规则，则在 nroff（终端）输出中，任何用 C<> 括起来的文本都将用双引号包围，除非内容已用引号包围。启用此猜测规则后，还将为 Perl 变量、函数名称、函数调用、数字和十六进制常量抑制引号。
将 Perl 变量名转换为固定宽度字体，即使它们没有标记。此转换仅在 troff 输出或其他支持固定宽度字体的输出格式（与 nroff 终端输出不同）中可见。
任何未知的猜测规则名称都会被静默忽略（为了潜在的未来兼容性），因此请注意拼写。
[1.00] 打印使用信息。
[1.00] 不再使用。pod2man 过去会检查其输入是否为有效的手册页，但现在应该由 podchecker(1) 代替。为了向后兼容性而接受；此选项不再有任何作用。
[5.00] 添加命令告诉groff输入文件使用的是哪种语言。此设置的值必须是groff提供补充配置的语言缩写，例如ja（日语）或zh（中文）。
这会在文件开头添加
.mso <language>.tmac
.hla <language>这些命令会为指定语言配置正确的换行。如果没有这些命令，如果手册页安装到正常的手册页目录（例如/usr/share/man），groff 可能不知道如何为中文和日文文本添加正确的换行。
在许多系统上，如果手册页安装到特定语言的手册页目录（例如/usr/share/man/zh_CN），则会自动执行此操作。在这种情况下，不需要此选项。
不幸的是，使用此选项添加的命令特定于groff，并且不适用于其他troff和nroff实现。
[4.08] 设置用于包围 C<> 文本的引号。--lquote 设置左引号，--rquote 设置右引号。两者也可以设置为特殊值none，在这种情况下，C<> 文本的两侧都不会添加引号（但字体仍然会为 troff 输出更改）。
另请参阅--quotes 选项，它可以用来同时设置两个引号。如果同时设置了--quotes 和其他选项之一，--lquote 或 --rquote 会覆盖--quotes。
[4.08] 将.TH 宏的手册页名称设置为name。如果没有此选项，手册名称将设置为正在转换的文件的基名称的大写形式，除非手册部分为 3，在这种情况下，将解析路径以查看它是否为 Perl 模块路径。如果是，则类似.../lib/Pod/Man.pm 的路径将转换为类似Pod::Man 的名称。如果给出此选项，它将覆盖对名称的任何自动确定。
虽然不必遵循此约定，但请注意，UNIX 手册页的约定是标题全部大写，即使命令不是。（但是，Perl 模块传统上使用混合大小写作为手册页标题。）
此选项在一次转换多个 POD 文件时可能没有用。
当从标准输入转换 POD 源代码时，如果未提供此选项，名称将设置为STDIN。强烈建议提供此选项以设置有意义的手册页名称。
[2.5.0] 通常，带有 URL 但有锚文本的 L<> 格式化代码将被格式化为显示锚文本和 URL。换句话说
L<foo|http://example.com/>格式化为
foo <http://example.com/>如果给出此标志，则在给出锚文本时会抑制 URL，因此此示例将仅格式化为 foo。在 URL 不太重要的情况下，这可以产生更简洁的输出。
[1.00] 如果未同时给出 --center，则将默认标题设置为指示此页面是标准 Perl 版本的一部分。
[4.00] 将用于包围 C<> 文本的引号设置为 quotes。如果 quotes 是单个字符，则它将用作左引号和右引号。否则，它将被分成两半，字符串的第一半用作左引号，第二半用作右引号。
quotes 也可以设置为特殊值 none，在这种情况下，C<> 文本周围不会添加引号（但字体仍然会为 troff 输出更改）。
另请参见 --lquote 和 --rquote 选项，它们可用于独立设置左引号和右引号。如果同时设置了 --quotes 和其他选项之一，则 --lquote 或 --rquote 将覆盖 --quotes。
[1.00] 将 .TH 宏的居中页脚设置为 version。默认情况下，这将设置为运行 pod2man 的 Perl 版本。将其设置为空字符串将导致某些 *roff 实现使用系统默认值。
请注意，某些系统 an 宏集假设居中页脚将是修改日期，并将添加类似 Last modified: 的内容。如果您的目标系统是这种情况，您可能希望将 --release 设置为上次修改日期，将 --date 设置为版本号。
[1.00] 设置 .TH 宏的节。标准节编号约定是使用 1 表示用户命令，2 表示系统调用，3 表示函数，4 表示设备，5 表示文件格式，6 表示游戏，7 表示杂项信息，8 表示管理员命令。但是，这里有很多变化；一些系统（如 Solaris）使用 4 表示文件格式，5 表示杂项信息，7 表示设备。还有一些系统使用 1m 代替 8，或者两者混合使用。唯一可靠一致的节号大约是 1、2 和 3。
默认情况下，将使用节 1，除非文件以 .pm 结尾，在这种情况下，将选择节 3。
[2.1.3] 默认情况下，如果在 POD 输入中检测到任何错误，pod2man 会退出。如果给出 --stderr 且没有 --errors 标志，错误将发送到标准错误，但 pod2man 不会中止。这等效于 --errors=stderr，并且为了向后兼容而支持。
[2.1.0] 此选项用于告诉 pod2man 生成 UTF-8 输出。由于从 5.00 版本开始，这已成为默认设置，因此它被忽略并且不会执行任何操作。
[1.11] 在生成每个输出文件时打印其名称。
只要所有处理的文档都产生一些输出，即使该输出包含勘误（使用 --errors=pod 生成的 POD ERRORS 部分），pod2man 都会以状态 0 退出。如果任何正在处理的文档没有产生输出文档，pod2man 将以状态 1 退出。如果正在处理的 POD 文档中存在语法错误，并且错误处理方式设置为默认的 die，pod2man 将立即中止并以退出状态 255 退出。
如果 pod2man 因错误而失败，请参阅 Pod::Man 和 Pod::Simple 以获取有关这些错误可能意味着什么的详细信息。
pod2man program > program.1
pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
pod2man --section=7 note.pod > note.7如果您想连续打印大量手册页，您可能需要设置 C 和 D 寄存器以设置连续页码和奇偶页码，至少在某些版本的 man(7) 上是这样。
troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...要在 STDERR 上获取索引条目，请打开 F 寄存器，例如
troff -man -rF1 perl.1索引仅通过 .tm 为每个主要页面、部分、子部分、项目以及任何 X<> 指令输出消息。
Russ Allbery <[email protected]>，基于 Larry Wall 和 Tom Christiansen 的原始 pod2man。
版权所有 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery <[email protected]>
本程序是自由软件；您可以根据与 Perl 本身相同的条款重新发布和/或修改它。
Pod::Man，Pod::Simple，man(1)，nroff(1)，perlpod(1)，podchecker(1)，perlpodstyle(1)，troff(1)，man(7)
记录 an 宏集的联机帮助页可能在您的系统上是 man(5) 而不是 man(7)。
此脚本的当前版本始终可从其网站获取：https://www.eyrie.org/~eagle/software/podlators/。它也是 Perl 核心发行版的一部分，从 5.6.0 版本开始。