骏马金龙

网名骏马金龙,钟情于IT世界里的各种原理和实现机制,强迫症重症患者。爱研究、爱翻译、爱分享。特借此一亩三分田记录自己成长点滴!!!
我本问道人,道心不坚,必将与道无缘!

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
posted @ 2018-10-13 01:11  骏马金龙  阅读(...)  评论(...编辑  收藏