Perl 嵌入式文档

嵌入式文档

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

以空行开始文档，在开头以a=head1命令，并以a=cut结尾

Perl将忽略您在代码中输入的纯文本。以下是在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部分-
```
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标记包含三种基本类型的段落-

普通段落 -您可以在普通段落中使用格式代码，包括粗体，斜体，代码样式，超链接等。
Verbatim段落 -Verbatim段落通常用于表示不需要任何特殊解析或格式且不应该包装的代码块或其他文本。
命令段落 -命令段落用于特殊处理整个文本块，通常作为标题或列表的一部分。所有命令段落均以=开头，后跟一个标识符，然后是该命令可以随意使用的任意文本。当前公认的命令是-


=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(pod2html -o test.html test.pod)，因此它将产生以下结果-


<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">



<ul id="index">
  <li><a href="#SYNOPSIS-Copyright-2005-CAINIAOYA">SYNOPSIS Copyright 2005 [CAINIAOYA].</a></li>
</ul>

<h1 id="SYNOPSIS-Copyright-2005-CAINIAOYA">SYNOPSIS Copyright 2005 [CAINIAOYA].</h1>


</body>

</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时，它将产生以下结果-


<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">



<ul id="index">
  <li>
    <ul>
      <li><a href="#An-Example-List">An Example List</a></li>
    </ul>
  </li>
  <li><a href="#POD-ERRORS">POD ERRORS</a></li>
</ul>

<h2 id="An-Example-List">An Example List</h2>

<ul>

</ul>

<h1 id="POD-ERRORS">POD ERRORS</h1>

<p>Hey! <b>The above document had some coding errors, which are explained below:</b></p>

<dl>

<dt id="Around-line-3">Around line 3:</dt>
<dd>

<p>=over should be: '=over' or '=over positive_number'</p>

<p>=over without closing =back</p>

</dd>
<dt id="Around-line-16">Around line 16:</dt>
<dd>

<p>=end html without matching =begin.  (Stack: =over)</p>

</dd>
</dl>


</body>

</html>