Perl - 嵌入式文档

您可以在 Perl 模块和脚本中嵌入 Pod（纯旧文本）文档。 以下是在 Perl 代码中使用嵌入式文档的规则 −

以空行开始您的文档，开头是 =head1 命令，并以 =cut 结束

Perl 将忽略您在代码中输入的 Pod 文本。 以下是在 Perl 代码中使用嵌入式文档的简单示例 −

#!/usr/bin/perl

print "Hello, World\n";

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
=cut

print "Hello, Universe\n";

执行上述代码时，会产生以下结果 −

Hello, World
Hello, Universe

如果您要将 Pod 放在文件末尾，并且使用 __END__ 或 __DATA__ 剪切标记，请确保在第一个 Pod 命令之前放一个空行，如下所示，否则之前没有空行 =head1，许多翻译人员不会将 =head1 识别为启动 Pod 块。

#!/usr/bin/perl

print "Hello, World\n";

while(<DATA>) {
  print $_;
}

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

执行上述代码时，会产生以下结果 −

Hello, World

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

让我们为相同的代码再举一个例子，而不阅读 DATA 部分 −

#!/usr/bin/perl

print "Hello, World\n";

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

执行上述代码时，会产生以下结果 −

Hello, World

什么是 POD?

Pod 是一种简单易用的标记语言，用于为 Perl、Perl 程序和 Perl 模块编写文档。 有多种翻译器可用于将 Pod 转换为各种格式，如纯文本、HTML、手册页等。 Pod 标记由三种基本类型的段落组成 −

• 普通段落 − 您可以在普通段落中使用格式代码，用于粗体、斜体、代码样式、超链接等。

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

• 命令段落 − 命令段落用于对整个文本块进行特殊处理，通常作为标题或列表的一部分。 所有命令段落都以 = 开头，后跟标识符，然后是命令可以随意使用的任意文本。 当前识别的命令是 −

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

POD 示例

考虑以下 POD −

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

您可以使用 Linux 上的 pod2html 实用程序将上面的 POD 转换为 HTML，因此会产生以下结果 −

Copyright 2005 [TUTORIALSOPOINT].

接下来，考虑以下示例 −

=head2 An Example List

=over 4
=item * This is a bulleted list.
=item * Here's another item.
=back
=begin html
<p>
Here's some embedded HTML.  In this block I can
include images, apply <span style="color: green">
styles</span>, or do anything else I can do with
HTML.  pod parsers that aren't outputting HTML will
completely ignore it.
</p>

=end html

当您使用 pod2html 将上述 POD 转换为 HTML 时，将产生以下结果 −

An Example List
   This is a bulleted list.
   Here's another item.
Here's some embedded HTML. In this block I can include images, apply 
styles, or do anything else I can do with HTML. pod parsers that aren't 
outputting HTML will completely ignore it.