目录

• 名称
• 描述
  • 普通段落
  • 逐字段落
  • 命令段落
  • 格式化代码
  • 意图
  • 在 Perl 模块中嵌入 Pod
  • 编写 Pod 的提示
• 另请参阅
• 作者

#名称

perlpod - 纯文本文档格式

#描述

Pod 是一种易于使用的标记语言，用于编写 Perl、Perl 程序和 Perl 模块的文档。

有可用于将 Pod 转换为各种格式（如纯文本、HTML、手册页等）的翻译器。

Pod 标记包含三种基本类型的段落：普通、逐字和命令。

#普通段落

文档中的大多数段落将是普通文本块，就像这一段。你可以直接输入文本，无需任何标记，只需在前后留空行。当它被格式化时，它将进行最小的格式化，比如重新换行、可能放入比例字体，甚至可能对齐。

你可以在普通段落中使用格式化代码，用于粗体、斜体、代码样式、超链接等。此类代码在下面的“格式化代码”部分中进行了解释。

#逐字段落

逐字段落通常用于呈现代码块或不需要任何特殊解析或格式化且不应换行的其他文本。

逐字段落以空格或制表符开头。 （通常，其所有行都以空格和/或制表符开头。）它应该被原样复制，假设制表符在 8 列边界上。没有特殊的格式化代码，所以你不能使用斜体或类似的格式。\ 表示 \，没有其他含义。

#命令段落

命令段落用于对整段文本进行特殊处理，通常作为标题或列表的一部分。

所有命令段落（通常只有一行长）都以“=”开头，后跟一个标识符，再后跟命令可以随意使用的任意文本。目前识别的命令是

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=head5 Heading Text
=head6 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

详细说明每个命令

#=head1 标题文本

#=head2 标题文本

#=head3 标题文本

#=head4 标题文本

#=head5 标题文本

#=head6 标题文本

head1 到 head6 生成标题，head1 是最高级别。本段剩余文本是标题的内容。例如

=head2 Object Attributes

文本“对象属性”构成那里的标题。这些标题命令中的文本可以使用格式化代码，如下所示

=head2 Possible Values for C<$/>

此类命令在下面的“格式化代码”部分中进行了解释。

请注意，head5 和 head6 是在 2020 年和 Pod::Simple 3.41 中引入的，于 2020 年 10 月发布，因此它们可能不受您使用的 Pod 解析器支持。

#=over 缩进级别

#=item 内容...

#=back

Item、over 和 back 需要更多解释："=over" 启动一个区域，专门用于使用 "=item" 命令生成列表，或用于缩进（组）普通段落。在列表末尾，使用 "=back" 结束列表。"=over" 的 缩进级别选项指示缩进的距离，通常以 ems 为单位（其中一个 em 是文档基本字体中“M”的宽度）或大致相当的单位；如果没有 缩进级别选项，则默认为 4。（有些格式化程序可能会忽略您提供的任何 缩进级别。）在 =item 内容... 中的 内容中，您可以使用格式化代码，如下所示

=item Using C<$|> to Control Buffering

此类命令在下面的“格式化代码”部分中进行了解释。

另请注意，使用 "=over" ... "=back" 区域有一些基本规则

• 不要在 "=over" ... "=back" 区域之外使用 "=item"。

• 在 "=over" 命令之后的第一个内容应该是 "=item"，除非这个 "=over" ... "=back" 区域中根本没有任何项目。

• 不要在 "=over" ... "=back" 区域内放置 "=headn" 命令。

• 也许最重要的是，保持项目一致：要么对所有项目使用 "=item *”，以生成项目符号；要么使用 "=item 1.", "=item 2.", 等，以生成编号列表；要么使用 "=item foo", "=item bar", 等——即，看起来不像项目符号或数字的东西。（如果你有一个列表，其中包含：1）看起来不像项目符号或数字的东西，加上 2）看起来像项目符号或数字的东西，你应该在项目符号或数字项之前加上 Z<>。有关示例，请参见下面的 Z<>。）

  如果你从项目符号或数字开始，请坚持使用它们，因为格式化程序使用第一个 "=item" 类型来决定如何格式化列表。

#=cut

要结束一个 Pod 块，请使用一个空行，然后是一行以 "=cut" 开头，然后是它之后的空行。这可以让 Perl（和 Pod 格式化程序）知道这是 Perl 代码恢复的位置。（"=cut" 之前的空行在技术上不是必需的，但许多较旧的 Pod 处理器需要它。）

#=pod

"=pod" 命令本身不会做什么，但它向 Perl（和 Pod 格式化程序）发出信号，表示 Pod 块从此处开始。Pod 块以任何命令段落开头，因此通常仅在你想要使用普通段落或逐字段落开始 Pod 块时才使用 "=pod" 命令。例如

=item stuff()

This function does stuff.

=cut

sub stuff {
  ...
}

=pod

Remember to check its return value, as in:

  stuff() || die "Couldn't do stuff!";

=cut

#=begin formatname

#=end formatname

#=for formatname text...

For、begin 和 end 将允许你拥有文本/代码/数据区域，这些区域通常不会被解释为普通 Pod 文本，而是直接传递给特定格式化程序，或者以其他方式特殊处理。可以使用该格式的格式化程序将使用该区域，否则它将被完全忽略。

命令 "=begin formatname"、一些段落和命令 "=end formatname"，表示介于两者之间的文本/数据是为理解称为formatname 的特殊格式的格式化程序准备的。例如，

=begin html

<hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

=end html

命令 "=for formatname text..." 指定本段的其余部分（从formatname 之后开始）采用该特殊格式。

=for html <hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

这意味着与上述“=begin html”...“=end html”区域相同。

也就是说，使用“=for”时，只能有一段文本（即“=foo targetname text...”中的文本），但使用“=begin targetname”...“=end targetname”时，中间可以包含任意数量的内容。（请注意，“=begin”命令后仍然必须有一行空白，而“=end”命令前也必须有一行空白。）

以下是一些使用方法示例

=begin html

<br>Figure 1.<br><IMG SRC="figure1.png"><br>

=end html

=begin text

  ---------------
  |  foo        |
  |        bar  |
  ---------------

^^^^ Figure 1. ^^^^

=end text

格式化程序当前已知接受的一些格式名称包括“roff”、“man”、“latex”、“tex”、“text”和“html”。（一些格式化程序会将其中一些视为同义词。）

格式名称“comment”通常用于仅仅做笔记（大概是你自己做的笔记），这些笔记不会出现在 Pod 文档的任何格式化版本中

=for comment
Make sure that all the available options are documented!

一些格式名称需要一个前导冒号（如"=for :formatname"或"=begin :formatname" ... "=end :formatname"），以表示文本不是原始数据，而是是 Pod 文本（即可能包含格式化代码），但不是用于普通格式化（例如，可能不是普通使用的段落，但可能是用于格式化为脚注）。

#=encoding encodingname

此命令用于声明文档的编码。大多数用户不需要此命令；但如果你的编码不是 US-ASCII，那么请在文档的开头放一个=encoding encodingname命令，以便 pod 格式化程序知道如何解码文档。对于encodingname，请使用Encode::Supported模块识别的名称。一些 pod 格式化程序可能会尝试猜测 Latin-1 或 CP-1252 与 UTF-8 编码之间的区别，但它们可能会猜错。如果你使用严格的 ASCII 以外的任何内容，最好明确说明。示例

=encoding latin1

=encoding utf8

=encoding koi8-r

=encoding ShiftJIS

=encoding big5

=encoding影响整个文档，并且只能出现一次。

另外请记住，除=encoding之外的所有命令都会持续到其段落的末尾，而不是其行尾。因此，在下面的示例中，你可以看到每个命令都需要在其后放置一行空白，以结束其段落。（并且一些较旧的 Pod 转换器可能还需要=encoding行后面也有一行空白，即使省略它是合法的。）

一些列表示例包括

=over

=item *

First item

=item *

Second item

=back

=over

=item Foo()

Description of Foo function

=item Bar()

Description of Bar function

=back

#格式化代码

在普通段落和一些命令段落中，可以使用各种格式化代码（又称“内部序列”）

#I<text> -- 斜体文本

用于强调（“be I<careful!>”）和参数（“redo I<LABEL>”）

#B<text> -- 粗体文本

用于开关（“perl's B<-n> switch”）、程序（“some systems provide a B<chfn> for that”）、强调（“be B<careful!>”）等（“and that feature is known as B<autovivification>”）。

#C<code> -- 代码文本

以打字机字体呈现代码，或给出其他一些指示，表示这代表程序文本（“C<gmtime($^T)>”）或其他形式的计算机术语（“C<drwxr-xr-x>”）。

#L<name> -- 超链接

有各种语法，如下所列。在给定的语法中，text、name 和 section 不能包含字符 '/' 和 '|'；并且任何 '<' 或 '>' 都应匹配。

• L<name>

  链接到 Perl 手册页（例如，L<Net::Ping>）。请注意，name 不应包含空格。此语法偶尔也用于引用 Unix 手册页，如 L<crontab(5)>。

• L<name/"sec"> 或 L<name/sec>

  链接到其他手册页中的一个部分。例如，L<perlsyn/"For Loops">

• L</"sec"> 或 L</sec>

  链接到本手册页中的一个部分。例如，L</"Object Methods">

部分由命名标题或项开始。例如，L<perlvar/$.> 或 L<perlvar/"$."> 都链接到 perlvar 中由 “=item $.” 开始的部分。而 L<perlsyn/For Loops> 或 L<perlsyn/"For Loops"> 都链接到 perlsyn 中由 “=head2 For Loops” 开始的部分。

要控制用于显示的文本，请使用 “L<text|...>”，如下所示

• L<text|name>

  将此文本链接到该手册页。例如，L<Perl Error Messages|perldiag>

• L<text|name/"sec"> 或 L<text|name/sec>

  将此文本链接到该手册页中的该部分。例如，L<postfix "if"|perlsyn/"Statement Modifiers">

• L<text|/"sec"> 或 L<text|/sec> 或 L<text|"sec">

  将此文本链接到本手册页中的该部分。例如，L<the various attributes|/"Member Data">

或者，你可以链接到一个网页

• L<scheme:...>

  L<text|scheme:...>

  链接到绝对 URL。例如，L<https://www.perl5.cn/> 或 L<The Perl Home Page|https://www.perl5.cn/>。

#E<escape> -- 字符转义

与 HTML/XML &foo; “实体引用”非常相似

• E<lt> -- 一个字面上的 <（小于）

• E<gt> -- 一个字面上的 >（大于）

• E<verbar> -- 一个字面上的 |（vertical bar）

• E<sol> -- 一个字面上的 /（solidus）

  除了在其他格式化代码中（特别是 L<...>）以及在大写字母前面时，以上四个是可选的。

• E<htmlname>

  一些非数字 HTML 实体名称，例如 E<eacute>，其含义与 HTML 中的 é 相同，即带有锐音（/- 形）重音的小写字母 e。

• E<number>

  具有该数字的 ASCII/Latin-1/Unicode 字符。前导“0x”表示数字是十六进制，如 E<0x201E>。前导“0”表示数字是八进制，如 E<075>。否则，数字将被解释为十进制，如 E<181>。

  请注意，较旧的 Pod 格式化程序可能无法识别八进制或十六进制数字转义，并且许多格式化程序无法可靠地呈现 255 以上的字符。（一些格式化程序甚至可能不得不使用折衷的呈现方式来呈现 Latin-1/CP-1252 字符，例如将 E<eacute> 呈现为一个普通的“e”。）

#F<filename> -- 用于文件名

通常以斜体显示。示例：“F<.cshrc>”

#S<text> -- 文本包含不换行空格

这意味着text 中的单词不应跨行断开。示例：S<$x ? $y : $z>。

#X<topic name> -- 索引条目

大多数格式化程序会忽略此项，但有些格式化程序可能会使用它来构建索引。它总是呈现为空字符串。示例：X<absolutizing relative URLs>

#Z<> -- 空（零效果）格式化代码

这很少使用。有时，这是绕过使用 E<...> 代码的一种方法。例如，你可以编写“NZ<><3”（“Z<>”将“N”和“<”分开，以便它们不能被视为（虚构的）“N<...>”代码的一部分），而不是“NE<lt>3”（表示“N<3”）。

另一种用途是表示 =item Z<>stuff... 中的stuff 不应被视为项目符号或数字。例如，如果没有 Z<>，则行

=item Z<>500 Server error

可能会被解析为编号列表中的一个项目，但实际上并非如此。

还有一种用途是保持 =item 行之间的视觉空间。如果你指定

=item foo

=item bar

它通常会呈现为

foo
bar

这可能是您想要的，但如果您真正想要的是

foo

bar

您可以使用 Z<> 来实现

=item foo

Z<>

=item bar

大多数情况下，您只需要一组尖括号来限定格式化代码的开始和结束。但是，有时您会希望在格式化代码中放置一个真正的右尖括号（大于号，'>'）。这在使用格式化代码为代码片段提供不同字体时尤其常见。与 Perl 中的所有内容一样，有多种方法可以做到这一点。一种方法是简单地使用 E 代码转义闭合括号

C<$a E<lt>=E<gt> $b>

这将产生：“$a <=> $b”

一种更具可读性，并且可能更“简洁”的方法是使用不需要转义单个“>”的备用分隔符集。双尖括号（“<<”和“>>”）可以使用当且仅当在开分隔符后面有空格，在闭合分隔符前面有空格！例如，以下内容将完成此操作

C<< $a <=> $b >>

事实上，您可以使用任意数量的重复尖括号，只要在开分隔符和闭合分隔符中它们的数目相同，并确保空格紧跟开分隔符的最后一个 '<'，并紧接闭合分隔符的第一个 '>'。（空格被忽略。）因此，以下内容也将起作用

C<<< $a <=> $b >>>
C<<<<  $a <=> $b     >>>>

它们都与以下内容完全相同

C<$a E<lt>=E<gt> $b>

多括号形式不影响格式化代码内容的解释，只影响其必须如何结束。这意味着上面的示例也与以下内容完全相同

C<< $a E<lt>=E<gt> $b >>

作为进一步的示例，这意味着如果您想将这些代码片段放入 C（代码）样式

open(X, ">>thing.dat") || die $!
$foo->bar();

您可以像这样操作

C<<< open(X, ">>thing.dat") || die $! >>>
C<< $foo->bar(); >>

这可能比旧方法更容易阅读

C<open(X, "E<gt>E<gt>thing.dat") || die $!>
C<$foo-E<gt>bar();>

目前由 pod2text (Pod::Text)、pod2man (Pod::Man) 和任何其他使用 Pod::Parser 1.093 或更高版本或 Pod::Tree 1.02 或更高版本的 pod2xxx 或 Pod::Xxxx 翻译器支持。

#意图

目标是易于使用，而不是表达能力强。段落看起来像段落（块格式），以便在视觉上突出显示，以便我可以轻松地通过fmt来重新格式化它们（在我的vi版本中是 F7，在我的emacs版本中是 Esc Q）。我希望翻译器始终以逐字模式保留'和`以及"引号，以便我可以导入一个工作程序，将其移动四个空格，并让它逐字打印出来。并且可能使用等宽字体。

Pod 格式不一定足以编写一本书。Pod 只是旨在成为 nroff、HTML、TeX 和其他标记语言的防呆通用源，这些语言用于在线文档。存在pod2text、pod2html、pod2man（适用于 nroff(1) 和 troff(1)）、pod2latex 和pod2fm的翻译器。CPAN 中还有其他各种翻译器可用。

#在 Perl 模块中嵌入 Pod

你可以在 Perl 模块和脚本中嵌入 Pod 文档。以空行、开头的“=head1”命令开始你的文档，并以“=cut”命令和空行结束。perl 可执行文件将忽略 Pod 文本。你可以在perl期望新语句开头的位置放置 Pod 语句，但不能在语句内放置，因为那样会导致错误。有关示例，请参阅任何提供的库模块。

如果你要将 Pod 放在文件末尾，并且正在使用__END__或__DATA__分隔符，请确保在第一个 Pod 命令之前放置一个空行。

__END__

=head1 NAME

Time::Local - efficiently compute time from local and GMT time

如果没有“=head1”之前的空行，许多翻译器将无法识别“=head1”作为 Pod 块的开头。

#编写 Pod 的提示

• podchecker命令用于检查 Pod 语法是否存在错误和警告。例如，它会检查 Pod 块中是否存在完全空白的行以及未知的命令和格式化代码。你仍然应该通过一个或多个翻译器传递你的文档并校对结果，或打印结果并校对。发现的一些问题可能是翻译器中的错误，你可能希望解决这些错误，也可能不希望解决。

• 如果你更熟悉用 HTML 而不是 Pod 来编写，你可以尝试用简单的 HTML 编写文档，并使用实验性的Pod::HTML2Pod模块（在 CPAN 中可用）将其转换为 Pod，并查看结果代码。CPAN 中的实验性Pod::PXML模块也可能有用。

• 许多较早的 Pod 翻译器要求在每个 Pod 命令之前和之后（包括“=cut”！）都有一行空白行。如下内容

  # - - - - - - - - - - - -
  =item $firecracker->boom()
  
  This noisily detonates the firecracker object.
  =cut
  sub boom {
  ...

  ...将使此类 Pod 翻译器完全无法看到 Pod 块。

  相反，应如下所示

  # - - - - - - - - - - - -
  
  =item $firecracker->boom()
  
  This noisily detonates the firecracker object.
  
  =cut
  
  sub boom {
  ...

• 一些较早的 Pod 翻译器要求段落（包括命令段落，如“=head2 函数”）由完全空行分隔。如果您有一行明显为空行，但其中有一些空格，则此类翻译器可能不会将其视为分隔符，这可能会导致格式奇怪。

• 较早的翻译器可能会在 L<> 链接周围添加文字，例如，L<Foo::Bar> 可能变为“Foo::Bar 手册页”。因此，如果您希望翻译后的文档可读，则不应编写诸如 the L<foo> documentation 之类的内容。相反，编写 the L<Foo::Bar|Foo::Bar> documentation 或 L<the Foo::Bar documentation|Foo::Bar>，以控制链接的显示方式。

• 在逐字块中超过第 70 列可能会被一些格式化程序不优雅地换行。

#另请参阅

perlpodspec、perlsyn 中的“POD：嵌入式文档”、perlnewmod、perldoc、pod2html、pod2man、podchecker。

#作者

Larry Wall、Sean M. Burke

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如果您对网站本身、搜索或文档呈现有任何疑问，请通过 GitHub 问题跟踪器 或 电子邮件 联系他。

Perl 文档由 Perl 5 Porters 在 Perl 开发中维护。如果您对文档的内容或格式有任何疑问，请通过 Perl 问题跟踪器、邮件列表 或 IRC 联系他们。