Perl POD 文档介绍
2017-09-27 17:42:23 
阿炯
Perl 中可以在模块或脚本中嵌入 POD(Plain Old Documentation) 文档，Pod是一种简单而易用的标记型语言(置标语言)，它经常用于在perl程序和模块中的文档编写，是perl的man文档，可以用perldoc输出，也可以直接用man输出。POD 文档使用规则：POD 文档以 =head1 开始， =cut 结束， =head1 前与 =cut 后添加一空行。
Perl 会忽略 POD 中的文档。实例如下：
print "Hello, World\n";
=head1 Hello, World 实例
这是一个 Perl 的简单实例。
=cut
print "Hello, FreeOA\n";
执行以上程序，输出结果为：
Hello, World
Hello, FreeOA
我们还可以使用 "__END__" 或 "__DATA__" 将所在行之后的内容全部"注释"掉：
print "Hello, World\n";
while(<DATA>){
print $_;
}
__END__
=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, FreeOA\n";
执行以上程序，输出结果为：
Hello, World
=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, FreeOA\n";
以下实例不读取 POD 文档：
print "Hello, World\n";
__END__
=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, FreeOA\n";
执行以上程序，输出结果为：
Hello, World
使用指令查看手册页：
$ perldoc Data::Dumper
$ man Data::Dumper
执行perldoc的时候，perldoc会搜索@INC下的Data/Dumper.pm和Data/Dumper.pod文件。
POD文档可以直接嵌入在程序文件内，perldoc会自动对内部的pod部分进行格式化输出，也可以独立写入一个".pod"文件。在嵌入程序文件内的时候，还可以和代码部分交叉，但并不建议这么做。POD嵌入在程序文件中时，建议的做法是将POD放在代码文件的最尾部(如果程序中包含了__DATA__或__END__，则放在它们的后面)。
当写好pod文档后，可以使用podcheck来检查pod文档的语法：
podchecker a.pod
podchecker a.pm
文档的结构
虽说文档可以随便写，但一般来说都遵循一些通用的、约定俗成的规则。一般来说，一个文档中包含以下几项信息：
NAME: 模块名
SYNOPSIS: 概要，使用简单的代码片段描述用法
DESCRIPTION: 描述，介绍模块用来干什么
EXPORT: 这是可选项。用来展示模块的导标签
FUNCTION/METHODS: 详细描述每个子程序/方法
BUGS: 列出bug
AUTHOR: 展示模块的作者
LICENSE: 模块的license条款
COPYRIGHT: 版权信息
除此之外，还有一些结构也可以包括进去，比如VERSION、DIAGNOSTICS、SEE ALSO、CONTRIBUTORS(贡献者一般用于列出那些非作者，但提供了补丁和反馈的人)。
Pod 的 转化器可以将 Pod 转换成很多种格式，例如 text, html, man 等很多。Pod 标记语言包含三种基本基本类型： 普通, 原文和命令。
普通段落: 你可以在普通段落中使用格式化代码，如黑体，斜体，或代码风格，下划线等。
原文段落: 原文段落，用于代码块或者其他不需要转换器处理的部分，而且不需要段落重排。
命令段落: 命令段落作用于整个的文档，通常用于标题设置或列表标记。
所有的命令段落(只有一行的长度)使用 "=" 开始，然后是一个标识符。 随后的文本将被这条命令所影响。现在被广泛使用的命令包括如下，不过文后还有针对这些命令的解释：
=pod (开始文档)
=head1 标题文本
=head2 标题文本
=head3 标题文本
=head4 标题文本
=over 缩进空格数量
=item 前缀
=back (结束列表)
=begin 文档格式
=end 结束文档格式
=for 格式文本
=encoding 编码类型
=cut (文档结束)
Pod 语法
pod中用段分可以分为三种，普通段落，字面段落(Verbatim Paragraph)和命令段落。三者的区分非常简单，以=pod|head1|cut|over等指示字开始的段落为命令段落，以空格或制表符(\t)等缩进开始的段落为字面段落，其余的就是普通段落。
=head1
=head2
=head3
=head4
此四个指示字生产指定级别的标题。pod2html时用其对应的<h1> .. </h4>包围此段落，并且自动生成a的命名/name和索引/index。
=pod
=cut
=pod 只告诉编译器pod文档开始了，而=cut则是pod文档的结束。
=over NUMBER 缩近多少
=item SYMBOL 产生bullet
=back
这三者是连上一起的。=over后面必须要跟一个=back，而这两者之间最少要有一个=item，同时不能有=head1..4。
格式代码
格式代码可以用于除字面段落外的所有段落，包括命令段落。
I<text>
用斜体表示text, 效果如text
B<text>
用粗体表示text, 效果如text
C<code>
pod2html时用<code>包围。
L<text|name>
超链接。
一个典型的示例
一般包括一下几个部分：
=head1 NAME
The name of your program or module.
=head1 SYNOPSIS
A one-line description of what your program or module does (purportedly).
=head1 DESCRIPTION
The bulk of your documentation. (Bulk is good in this context.)
=head1 AUTHOR
Who you are. (Or an alias, if you are ashamed of your program.)
=head1 BUGS
What you did wrong (and why it wasn't really your fault).
=head1 SEE ALSO
Where people can find related information (so they can work around your bugs).
=head1 COPYRIGHT
The copyright statement. If you wish to assert an explicit copyright, you should say something like:
Copyright 2013, Randy Waterhouse. All Rights Reserved.
注意：每个=标签上下必须隔一行，否则就会错误解析。
=for html 或者 =for text
是把下面的单行注视当作html或者text来处理，与其功能类似的是 =begin html / =end html ; =begin text / =end text 两对。begin和end之间可以处理多行。
=over 4
=item SOMEWORD
*************
=item somewordelse
******
=back
以上写法是写一个列表，以over开头，后面的数字是列表中每行的缩进量。最后以=back 结尾。
=cut 是结束pod块的标志，与程序分开。
在perl中，可以使用 pod2html freeoa.pm > freeoa.html 来生成html格式的pod文档。
空行加空格加内容加空行
这个内容再pod2html后就会变成code代码框。
基本上，对于 pod2xxx ("xxx" 可以是 txt, html, latex or man)来说，一个pod 文件只有三种东西：
1. Verbatim Paragraph -- 这种段落以空白或 tab 开始(就是有缩排)，段落中的文字不会被转译，例如 '/' 就是 '/'。
2. Command -- pod 的命令是以 '=' 开始，后面接英文字，至于他有哪些命令，会在稍后介绍。
3. 一段文字 -- 与 1. 不同之处在于这里面可以加些类似 "Markup" 的东西，也可以加 link，由 pod2html 帮你处理。后面也会介绍他有哪些功能。
需要注意的是，对于 pod2xxx 这些转译程式来说，上面三种东西最好都是用前后各一行空白来将他们区隔开来。不然转出来的东西，其格式可能不甚符合你的期望。
在perl中，可以使用 pod2html xx.pod >xx.html 来生成html格式的pod文档。
考虑以下 POD 实例：
=begin html
=encoding utf-8
=head1 FreeOA
=cut
使用 pod2html 命令执行，将其转换为 HTML 代码：
$ pod2html freeoa.pod > freeoa.html
在浏览器中打开 freeoa.html，链接部分为索引锚。
以下实例在 POD 文档中直接写入 HTML:
=begin html
=encoding utf-8
<h1>FreeOA</h1>
<p>www.freeoa.net</p>
=end html
encoding和注释
如果文档使用非latin-1或ascii写，比如中文，那么要设置encoding，例如设置为utf-8。
=encoding UTF-8
如果要设置pod的注释，即pod渲染的时候会忽略的内容，需要使用：
= for comment
例如：
=pod
=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.46.
See http://github.com/ingydotnet/swim-pm#readme
=encoding utf8
使用 pod2html 命令执行，将其转换为 HTML 代码：
$ pod2html freeoa.pod > freeoa.html
在浏览器中打开 freeoa.html，链接部分为索引。
pod2usage 在package中的使用，如果想显示 perl module中的pod，那么采用如下
use Pod::Find qw(pod_where);
pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__));
其中：-inc=>1 表示 Search @INC for the pod and also the scriptdir __PACKAGE__ 表示包文件，如果是A::B 则表示 A/B
pod_where 返回 文件句柄的引用，pod2usage 中default值是 $0, 当前文件而不是包本身。
常用命令解释
总共就十个命令而已：
=head1 heading
=head2 heading
=item text
=over N
=back
=cut
=pod
=for X
=begin X
=end X
1. =headN heading
这看来就知道是用来当标题文字的，后面接的 "heading" 就是此标题名。例如:
=head1 篇名
perlfaq7 - Perl 语言相关问题
=head1 概述
本篇内的问题主要是无法纳入其他部份且与 Perl 语言相关的一般问题。
=head2 我能拿到 Perl 的 BNF/yacc/RE 吗?
转成 html 后还可以自动做出同页连结。可参考 perlfaq 的结果。
2. =item, =over and =back
对于熟悉 HTML 的人来说，这三样分别相当于 <li>, [<ul>|<ol>], [</ul>|</ol>], (这里用正规表示式来描述。)所以要产生一个列表，用 =over 开始，以 =item 铺陈出每个项目，然后用 =back 结尾。请不要在 =over .. =back 这圈圈外使用 =item! =over n 后面的 n 可以用来表示预定的缩排字数，预设为 4。
=item * 表示此列表是没有排顺序的，亦即 unordered list，而 =item 1.,
=item 2. 则是用数字表示，当然 =item foo ,=item bar 也是合法的用法。使用时请注意其一致性。以下即为范例：
=over 4
=item *
第一个项目
=item *
第二个项目
=back
=over 4
=item Foo()
Description of Foo function
=item Bar()
Description of Bar function
=back
3. =cut 和 =pod
这两个是难兄难弟，其实他最大的用途在于当你写 Perl 代码，里面有包含 pod 格式的说明文字时，用 =pod 开头， =cut 结尾包起来的那几段都会被 Perl 直译器给忽略。就这样，跟常看到的 "--- cut here ---" 用法与意义差不多。
4. =for, =begin 和 =end
以 =for 为首的那一段文字(请注意，只有其紧接下来的一段文字而已)，会被 pod转译程式忽略，直接送给所指定的 formatter，例如以下就是标明一段 html 文字：
=for html <br>
<P>这是一段 HTML 文件</P>
所以 =for 后面接的就是格式名，目前所接受的格式有(大多都在 Unix 下)："roff", "man", "latex", "tex", "text", 和 "html"。
=begin 和 =end 的用途和 =for 一样，只是他两就相当于担任划清界线的功用，就不只限于一段文字，可以是很多段了... 例如：
=begin html
<br>Figure 1.<IMG SRC="figure1.png"><br>
=end html
=begin text
---------------
| foo |
| bar |
---------------
^^^^ Figure 1. ^^^^
=end text
只要切记，每个段落或命令之间都要用一行空白来隔开，则写 pod 就很简单了。接下来介绍一些类似 HTML 标签的用法：
I<text> 倾斜文字
B<text> 加粗文字
S<text> 包含了连续空白的文字
C<code> 表示一段文字码
L<name> 连结到 "name" 去，用法有以下几种：
L<name> 其他说明文件
L<name/ident> 其他说明文件中的某项目
L<name/"sec"> 其他说明文件中的某段落
L<"sec"> 本文件中的某段落( " 可有可无)
L</"sec"> 同上
F<file> 用来表示档案名
X<index> 表示一索引项目
Z<> 零长度字元
E<escape> 控制字元(相当近似于 html 的 escape character)
E<lt> 代表 <
E<gt> 代表 >
E<n> 第 n 个字元 (ASCII 中的)
E<html> 非数字的 HTML 实体字元，例如 E<Agrave>.
以下节录一段 Perl FAQ Part 7，里面有些用法。
pod文档格式中，有两种内容：段落声明格式和行内格式。
段落声明
段落声明都使用=FLAG表示，=必须顶格写，前面不能有任何空白，FLAG表示开启什么类型的段落，比如是一级标题、二级标题、有序和无序列表等。其中两个特殊的段落声明为：
1.=pod表示此处开始的是pod文档部分
2.=cut表示pod文档到此结束
例如：
sub reciprocal { return 1 / shift }
=pod # 这里表示pod文档段落从此处开始，下面属于pod文档
This is a paragraph in a POD section. When run through a formatter, the
paragraph text will rewrap as necesseary to fit the needs of your
particular output format.
=cut # 这里表示pod文档段落到此结束，下面不属于pod文档
sub not_reciprocal { return shift }
常见的段落声明有以下几种：
=pod
=cut
=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 # 编码类型
其中列表由=over NUM开始，NUM表示列表的缩进程度，由=back结束列表。有无序列表和有序列表两种形式。例如：
=over 4
=item * This is a list item
=item * This is a second list item.
This is an optional paragraph explaining the second list item.
=back
=over 4
=item 1. This is a list item
=item 2. This is a second list item.
This is an optional paragraph explaining the second list item.
=item 3.
=back
行内格式
行内格式一般是行内代码、加粗、斜体、链接等。
格式 意义
------------ -----------------
C<text> 代码
C<< text >> 代码段中保留大于号和小于号( C<< $age >= 18 >> )
B<text> 加粗
I<text> 斜体
E<text> 转义的HTML，例如可以使用E<lt>表示小于号(<)
S<text> All ‘s’paces are nonbreaking
L<text> 链接
主要解释下生成链接的方式。支持3种链接方式：链接到另一个文档、链接到另一个文档的某一小节，连接到本文档的某小节以及链接到某个URL：
L<name>：连接到另一个文档。例如L<Scalar::Util>、L<perlunitut>，注意链接的名称中不能有空格
L<name/"sec">或L<name/sec>：连接到另一个文档的某一小节，例如L<perlpod/"Formatting Codes">
L</"sec">或L</sec>：链接到本文档的某个小节
L<URL>：链接到某个URL，例如L<http://www.freeoa.net/>
注意：E<lt>FILEE<gt> I<不是> 用来指定档案的形态，亦非此把手的名字。它只是将C<E<lt>E<gt>> 运算子用在 FILE 把手上。它自 FILE 把手读入一行 (嗯，该说一笔记录，参看 L<perlvar/$/>) 当作纯量变数的内容，或读入 I<全部> 当作阵列变数的内容。当使用开、关或其它 C<E<lt>E<gt>> 之外的动作于档案上，或甚至只是提到把手时，切记 I<不要> 使用 C<E<lt>E<gt>>。下面的用法是正确的：C<eof(FH)>，C<seek(FH, 0,2)>以及 "copying from STDIN to FILE"。
这里面用到了 E<>, I<>, C<>, 及 L<>，算是个不错的范例。
Okay, 整个 POD 的命令与格式就是这么简单。目前进行中的 Perl FAQ 中文翻译都是直接翻 pod 档，再交给 hsiao 先生转成 html 格式。是还没有什么大问题。所以若要省去发展格式与转换程式的时间，那或许采用 pod 是个不错的主意。 By the way,pod 的作者当然是 Larry Wall，可以再参考 perlpod 的文件。
另外一个另类的用法就是《perl 多行注释》。