perl pod 文档——迹忆客-ag捕鱼王app官网

perl 中可以在模块或脚本中嵌入 pod（plain old documentation） 文档。

pod 是一种简单而易用的标记型语言（置标语言）。

pod 文档使用规则：

pod 文档以 =head1 开始， =cut 结束， =head1 前与 =cut 后添加一空行。

perl 会忽略 pod 中的文档。实例如下：

#!/usr/bin/perl
 
print "hello, world\n";
 
=head1 hello, world 实例
这是一个 perl 的简单实例。
=cut
 
print "hello, jiyik\n";

执行以上程序，输出结果为：

hello, world
hello, jiyik

我们还可以使用 "__end__" 或 "__data__" 将所在行之后的内容全部"注释"掉：

#!/usr/bin/perl
 
print "hello, world\n";
 
while(){
  print $_;
}
 
__end__
 
=head1 hello, world 实例
这是一个 perl 的简单实例。
print "hello, jiyik\n";

执行以上程序，输出结果为：

hello, world
=head1 hello, world 实例
这是一个 perl 的简单实例。
print "hello, jiyik\n";

以下实例不读取 pod 文档：

#!/usr/bin/perl
 
print "hello, world\n";
 
__end__
 
=head1 hello, world 实例
这是一个 perl 的简单实例。
print "hello, jiyik\n";

执行以上程序，输出结果为：

hello, world

什么是 pod？

pod(plain old documentation), 是一种简单而易用的标记型语言（置标语言），它经常用于在perl程序和模块中的文档书写。

pod 的 转化器可以将 pod 转换成很多种格式，例如 text, html, man 等很多。

pod 标记语言包含三种基本基本类型： 普通, 原文, 和 命令。

• 普通段落: 你可以在普通段落中使用格式化代码，如黑体，斜体，或代码风格，下划线等。
• 原文段落: 原文段落，用于代码块或者其他不需要转换器处理的部分，而且不需要段落重排。
• 命令段落: 命令段落作用于整个的文档，通常用于标题设置或列表标记。

所有的命令段落（他只有一行的长度）使用 "=" 开始，然后是一个标识符。 随后的文本将被这条命令所影响。现在被广泛使用的命令包括

=pod (开始文档)
=head1 标题文本
=head2 标题文本
=head3 标题文本
=head4 标题文本
=over 缩进空格数量
=item 前缀
=back (结束列表)
=begin 文档格式
=end 结束文档格式
=for 格式文本
=encoding 编码类型
=cut (文档结束)

在perl中，可以使用 pod2html *]*.pod >**.html 来生成html格式的pod文档。

考虑以下 pod 实例：

=begin html
=encoding utf-8
 
=head1 迹忆客
 
=cut

pod2html时会原文拷贝此段代码。

使用 pod2html 命令执行，将其转换为 html 代码：

$ pod2html test.pod > test.html 

在浏览器中打开 test.html，链接部分为索引，显示如下:

以下实例在 pod 文档中直接写入 html:

=begin html
=encoding utf-8
 www.jiyik.com 
=end html

pod2html时会原文拷贝此段代码。

使用 pod2html 命令执行，将其转换为 html 代码：

$ pod2html test.pod > test.html 

在浏览器中打开 test.html，链接部分为索引，显示如下: