Perl 简明教程
Perl - Embedded Documentation
您可以在 Perl 模块和脚本中嵌入 Pod（普通文本）文档。以下是使用 Perl 代码中的嵌入式文档的规则 -
You can embed Pod (Plain Old Text) documentation in your Perl modules and scripts. Following is the rule to use embedded documentation in your Perl Code −
以空行开始文档，在开头使用 = head1 命令，并以 = cut 结束文档
Start your documentation with an empty line, a =head1 command at the beginning, and end it with a =cut
Perl 将忽略您在代码中输入的 Pod 文本。以下是 Perl 代码中使用嵌入式文档的一个简单示例 -
Perl will ignore the Pod text you entered in the code. Following is a simple example of using embedded documentation inside your Perl code −
#!/usr/bin/perl
print "Hello, World\n";
=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
=cut
print "Hello, Universe\n";当以上代码执行后，它将产生以下结果 −
When above code is executed, it produces the following result −
Hello, World
Hello, Universe如果你将 Pod 放在文件末尾，并且正在使用 END 或 DATA 剪切标记，请确保在此处在第一个 Pod 命令之前放置一个空行，如下所示，否则如果没有空行 = head1 之前，很多翻译器就不会将 = head1 识别为开始一个 Pod 块。
If you’re going to put your Pod at the end of the file, and you’re using an END or DATA cut mark, make sure to put an empty line there before the first Pod command as follows, otherwise without an empty line before the =head1, many translators wouldn’t have recognized the =head1 as starting a Pod block.
#!/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";当以上代码执行后，它将产生以下结果 −
When above code is executed, it produces the following result −
Hello, World
=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";让我们再举一个没有读取 DATA 部分的相同代码的示例 −
Let’s take one more example for the same code without reading DATA part −
#!/usr/bin/perl
print "Hello, World\n";
__END__
=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";当以上代码执行后，它将产生以下结果 −
When above code is executed, it produces the following result −
Hello, WorldWhat is POD?
Pod 是一种简单易用的标记语言，用于编写 Perl 文档、Perl 程序和 Perl 模块。有各种翻译器可将 Pod 转换为各种格式，如纯文本、HTML、man 页面等。Pod 标记包含三种基本类型的段落 −
Pod is a simple-to-use markup language used for writing documentation for Perl, Perl programs, and Perl modules. There are various translators available for converting Pod to various formats like plain text, HTML, man pages, and more. Pod markup consists of three basic kinds of paragraphs −
-
Ordinary Paragraph − You can use formatting codes in ordinary paragraphs, for bold, italic, code-style , hyperlinks, and more.
-
Verbatim Paragraph − Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn’t be wrapped.
-
Command Paragraph − A command paragraph is used for special treatment of whole chunks of text, usually as headings or parts of lists. All command paragraphs start with =, followed by an identifier, followed by arbitrary text that the command can use however it pleases. Currently recognized commands are −
=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
=cutCopyright 2005 [TUTORIALSOPOINT].
接下来，考虑以下示例 −
Next, consider the following example −
=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 时，将生成以下结果 −
When you convert the above POD into HTML using pod2html, it will produce the following result −
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.