• 丰搜首页
• 文档中心
• 视频中心
• 丰搜贴吧
• 问题集锦
• 更多功能

选择显示字体大小

• 最大
• 较大
• 标准

如何撰写pod

简介

pod(plain old documentation), 是一种简单而易用的标记型语言（置标语言），它经常用于在perl程序和模块中的文档书写。

在pod中，用段类型可分为三种，普通段落，字面段落（verbatim paragraph）和命令段落。

三者的区分非常简单，以=podhead1cutover等指示字开始的段落为命令段落，以空格或制表符（\t）等缩进字符开始的段落为字面段落，其余的就是普通段落。

pod中有其独特的格式代码来表现粗体，斜体，超链接等。

在pod中，对于字面段落的文本，是从来都不进行格式代码转义的。pod2html时用<pre >将其包围。所以字面段落非常适合在引用语言与代码块时运用。

当然，值得注意的是，对于pod2xxx脚本来说，段落意味着前后各有一个空行。

下面我们要介绍的pod，都是用于pod2html这项功能的。

命令指示字

=head1

=head2

=head3

=head4

上面的四个指示字产生指定级别的标题。在pod2html时，用他们各自对应的

..

来包围此段落，并且自动生成a的命名/name和索引/index.

一个简单的例子：

=head1 namepod2html - convert .pod files to .html files

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

=pod

=cut

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

一个简单的例子：

return;}=podhere we start our pod=cutsub _ {

=over number

=item symbol

=back

上面三个标签是连在一起的。=over后面必须要跟一个=back，而这两者之间最少要有一个=item，同时不能有=head1至head4。

pod2html时依据item后面的symbol不同将其转化为<dl><ol><ul>中的一种。

当symbol为数字时使用ol, sybmol为*时使用ul, 其余的使用dl.

而=over后面的number只是用来确定缩进中的空格。不同的格式器(pod2xxxx)对于number有着不同地处理，另外有些格式器对此则进行忽略。默认的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<textname/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 messagesperldiag> - <a href='perldiag.html'>perl error message</a>l<perlsyn/"for loops"> - <a href='perlsyn.html#for_loops'>the perlsyn manpage</a>而下面的一个例子就是一个典型的错误：l<faylandhttp://www.1313s.com> - name为网址时不允许存在text

• e<escape> 字符转义。
  • e<lt> – <
  • e<gt> – >
  • e<verbar> –
  • e<sol> – /
  • 更多的请参考perldoc perlpod
• 更多的如f<filename>, s<text>等请参考perldoc perlpod

实例

最后给出一个简单的例子，用以使大家加深对pod的印象。

=pod=head1 examplesit's just a examples for pod newcomer.=head1 how to write a pod?=over 4=item 1know all pod command's meanings such as "head1, over, item, begin".=item 2try to write a example by yourself.=item 3use 'pod2html' utility convert pod to html format.=item 4modify 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='/showimg.asp?p=/2006-4-19/23717nd_gmail.png' /> =end html=head2 how to add e<lt>be<gt> etc. e<lt>be<gt>=head1 link i<this> pagel<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章

 

关键字 本文所属关键字

相关 与本文相关文章

分类 所有文章关键字导航

标准 网站致力的规范