Perl 简明教程

Perl - Embedded Documentation

您可以在 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

What is POD?

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

Ordinary Paragraph − 可以在普通段落中使用格式化代码，加粗，斜体，代码样式，超链接等。
Verbatim Paragraph − 原文段落通常用于显示代码块或其他不需要特殊解析或格式化且不应该折行的文本。
Command Paragraph − 命令段落用于特殊处理整个文本块，通常作为标题或列表的一部分。所有命令段落都以 = 开始，后面跟一个标识符，再后面是命令可以随意使用的任意文本。当前识别的命令有 −

=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 Examples

考虑以下 POD −

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

可以使用 Linux 上 pod2html 实用工具将以上 POD 转换为 HTML，因此它将产生以下结果 −

接下来，考虑以下示例 −

=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.