官方手册：https://perldoc.perl.org/perlpod.html
POD文档是perl的man文档，可以用perldoc输出，也可以直接用man输出。在开始下面的文章之前，请先粗略浏览一到两篇perldoc文档，或去CPAN找几个模块的文档浏览下大致格式。
例如：
$ 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
pod文档格式中，有两种内容：段落声明格式和行内格式。
段落声明
段落声明都使用=FLAG表示，=必须顶格写，前面不能有任何空白，FLAG表示开启什么类型的段落，比如是一级标题、二级标题、有序和无序列表等。其中两个特殊的段落声明为：
=pod表示此处开始的是pod文档部分=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.overseas-exile.com/>
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
文档的结构
虽说文档可以随便写，但一般来说都遵循一些通用的、约定俗成的规则。一般来说，一个文档中包含以下几项信息：
- NAME: 模块名
- SYNOPSIS: 概要，使用简单的代码片段描述用法
- DESCRIPTION: 描述，介绍模块用来干什么
- EXPORT: 这是可选项。用来展示模块的导标签
- FUNCTION/METHODS: 详细描述每个子程序/方法
- BUGS: 列出bug
- AUTHOR: 展示模块的作者
- LICENSE: 模块的license条款
- COPYRIGHT: 版权信息
除此之外，还有一些结构也可以包括进去，比如VERSION、DIAGNOSTICS、SEE ALSO、CONTRIBUTORS(贡献者一般用于列出那些非作者，但提供了补丁和反馈的人)。
pod示例：base.pod
可以使用find随意搜索一个Pod文件来参考：
$ find /usr -type f -name "*.pod"
以下是base.pod的内容。
$ cat /usr/share/perl/5.26.1/base.pod
=head1 NAME
base - Establish an ISA relationship with base classes at compile time
=head1 SYNOPSIS
package Baz;
use base qw(Foo Bar);
=head1 DESCRIPTION
Unless you are using the C<fields> pragma, consider this module discouraged
in favor of the lighter-weight C<parent>.
Allows you to both load one or more modules, while setting up inheritance from
those modules at the same time. Roughly similar in effect to
package Baz;
BEGIN {
require Foo;
require Bar;
push @ISA, qw(Foo Bar);
}
When C<base> tries to C<require> a module, it will not die if it cannot find
the module's file, but will die on any other error. After all this, should
your base class be empty, containing no symbols, C<base> will die. This is
useful for inheriting from classes in the same file as yourself but where
the filename does not match the base module name, like so:
# in Bar.pm
package Foo;
sub exclaim { "I can have such a thing?!" }
package Bar;
use base "Foo";
There is no F<Foo.pm>, but because C<Foo> defines a symbol (the C<exclaim>
subroutine), C<base> will not die when the C<require> fails to load F<Foo.pm>.
C<base> will also initialize the fields if one of the base classes has it.
Multiple inheritance of fields is B<NOT> supported, if two or more base classes
each have inheritable fields the 'base' pragma will croak. See L<fields>
for a description of this feature.
The base class' C<import> method is B<not> called.
=head1 DIAGNOSTICS
=over 4
=item Base class package "%s" is empty.
base.pm was unable to require the base package, because it was not
found in your path.
=item Class 'Foo' tried to inherit from itself
Attempting to inherit from yourself generates a warning.
package Foo;
use base 'Foo';
=back
=head1 HISTORY
This module was introduced with Perl 5.004_04.
=head1 CAVEATS
Due to the limitations of the implementation, you must use
base I<before> you declare any of your own fields.
=head1 SEE ALSO
L<fields>
=cut