14 January 2005
This post may be outdated due to it was written on 2005. The links may be broken. The code may be not working anymore. Leave comments if needed.

简介

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.


blog comments powered by Disqus