嵌入式文档（Embedded Documentation）

优质

小牛编辑

138浏览

2023-12-01

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

使用空行开始您的文档，在开头使用a = 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标记包含三种基本类型的段落 -

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示例

考虑以下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.