Perl：写POD文档

官方手册：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