怎么写POD

Category: Basic Keywords: pod

简介

pod(Plain Old Documentation), 它是一种简单而易用的标记型语言（置标语言），用于perl程序和模块中的文档书写。
pod中用段分可以分为三种，普通段落，字面段落（Verbatim Paragraph）和命令段落。
三者的区分非常简单，以=pod|head1|cut|over等指示字开始的段落为命令段落，以空格或制表符（\t）等缩进开始的段落为字面段落，其余的就是普通段落。
pod中有其独特的格式代码来表现粗体，斜体，超链接等。
对于字面段落是不进行格式代码转义的。pod2html时用<pre>将其包围。所以字面段落适合引用语言与代码块。
值得注意的是，对于pod2xxx脚本来说，段落意味着前有一个空行后也有一个空行。
下面着重介绍的pod都是为了pod2html而准备。

命令指示字

=head1
=head2
=head3
=head4
此四个指示字生产指定级别的标题。pod2html时用其对应的<h1> .. </h4>包围此段落，并且自动生成a的命名/name和索引/index.

一个简单的例子：

=head1 NAME

pod2html - convert .pod files to .html files

pod2html后NAME的标签为h1, 而后面的那段为p。

=pod
=cut
=pod 只告诉编译器pod文档开始了，而=cut则是pod文档的结束。

一个简单的例子：

return;
}

=pod

Here we start our pod

=cut

sub _ {

=over NUMBER
=item SYMBOL
=back
这三者是连上一起的。=over后面必须要跟一个=back，而这两者之间最少要有一个=item，同时不能有=head1..4。
pod2html时依据item后面的SYMBOL不同将其转化为<dl><ol><ul>中的一种。
当SYMBOL为数字时使用ol, SYBMOL为*时使用ul, 其余的使用dl.
而=over后面的NUMBER只是确定缩进的空格。不同的格式器(pod2xxxx)将其不同地处理，有些格式器对此进行忽略。默认的NUMBER为4.
=item 能自动生成a的命名，但不参加索引/index（与head不同）。

一个简单的例子：


=over 4

=item L<http://www.perl.com/>

Perl 的首页 (由欧莱礼公司维护)

=item L<http://www.cpan.org/>

Perl 综合典藏网 (Comprehensive Perl Archive Network)

=item L<http://lists.perl.org/>

Perl 邮递论坛一览

=back

此例子摘自perlcn.pod

=for format text
=begin format
=end format
此指示字的作用是对此段落使用特殊的格式/format（如html, text等）。
=for与=begin+=end作用相同。区别在于=for只处理一个段落，而=begin+=end能处理它们中间的多个段落。
format为html时，可以用于增加“命令指示字和格式代码”都不能实现的特殊格式。如<img或其它html标签。

一个简单的例子：


=begin html

<hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

=end html

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

=encoding
用于制定文档的编码，默认为不指定。

格式代码

格式代码可以用于除字面段落外的所有段落，包括命令段落。

I<text>
用斜体表示text, 效果如text
B<text>
用粗体表示text, 效果如text
C<code>
pod2html时用<code>包围。
L<text|name/sec>
超链接。
其中name可以为模块名，也可以为一个网址。pod2html时，当name为模块名时转化为module/name.html.name为a里href参数内容
其中text为连接所显示的内容，若没有text，name为模块名时显示 the module::name manpage, name为网址时不允许存在text。pod2html时转化为<a>和</a>之间的东西。
sec参数当name为模块名时指向该模块名的sec部分，没有name时指向当前页的sec部分。此sec部分一般为=head或=item所定义。pod2html时转化为href里的#部分。
```
正确的：
L<Net::Ping> - <a href="/Net/Ping.html">the Net::Ping manpage</a>
L<http://www.1313s.com> - <a href='http://www.1313s.com'>http://www.1313s.com/</a>
L<Perl Error Messages|perldiag> - <a href='perldiag.html'>Perl Error Message</a>
L<perlsyn/"For Loops"> - <a href='perlsyn.html#for_loops'>the perlsyn manpage</a>

错误的：
L<fayland|http://www.1313s.com> - name为网址时不允许存在text
```
E<escape>
字符转义。
- E<lt> - <
- E<gt> - >
- E<verbar> - |
- E<sol> - /
- 更多的请参考perldoc perlpod
更多的如F<filename>, S<text>等请参考perldoc perlpod

Examples

一个简单的例子用以加深印象。


=pod

=head1 Examples

it's just a examples for pod newcomer.

=head1 how to write a pod?

=over 4

=item 1

know all pod command's meanings such as "head1, over, item, begin".

=item 2

try to write a example by yourself.

=item 3

use 'pod2html' utility convert pod to html format.

=item 4

modify and pod2html again until u a satisfied.

=back

=head1 FAQ

=head2 want to add a B<img>?

use code as follows:

 =begin html
 
 <img src='http://www.1313s.com/f/fayland_gmail.png' />
 
 =end html

=head2 how to add E<lt>bE<gt> etc.

 E<lt>bE<gt>

=head1 link I<this> page

L<http://www.1313s.com/f/POD.html>

=cut

perldoc & pod2html

pod可以转化为n多种格式。在bin目录下以pod2开头的工具有很多，也有2pod的工具。但最常用的是perldoc和pod2html.
perldoc用于在命令控制台下查看pod文档，而pod2html则把pod转化为html格式。

pod2html

你可以通过pod2html --help来查看pod2html的所有参数。因为所有的参数都是很容易看懂的，也就不多加解释了。
将上面的例子保存为examples.pod, 然后进入控制台/console：

pod2html <examples.pod >examples.html -css=Active.css

All is Done.

参考


=over 4

=item *

perldoc L<perlpod>

=item *

perldoc L<perlpodspec>

=item *

<Programming Perl> Chapter 26 大骆驼书第26章

=back

:) have fun.

perldoc perlpod
perldoc perlpodspec
Chapter 26 大骆驼书第26章