Perl POD 文檔

Perl POD 文檔

Perl 中可以在模塊或腳本中嵌入 POD（Plain Old Documentation） 文檔。

POD 是一種簡(jiǎn)單而易用的標(biāo)記型語言（置標(biāo)語言）。

POD 文檔使用規(guī)則：

POD 文檔以 =head1 開始， =cut 結(jié)束， =head1 前與 =cut 后添加一空行。

Perl 會(huì)忽略 POD 中的文檔。實(shí)例如下：

#!/usr/bin/perl

print "Hello, World\n";

=head1 Hello, World 實(shí)例
這是一個(gè) Perl 的簡(jiǎn)單實(shí)例。
=cut

print "Hello, W3Cschool\n";

執(zhí)行以上程序，輸出結(jié)果為：

Hello, World
Hello, W3Cschool

我們還可以使用 "__END__" 或 "__DATA__" 將所在行之后的內(nèi)容全部"注釋"掉：

#!/usr/bin/perl

print "Hello, World\n";

while(<DATA>){
  print $_;
}

__END__

=head1 Hello, World 實(shí)例
這是一個(gè) Perl 的簡(jiǎn)單實(shí)例。
print "Hello, W3Cschool\n";

執(zhí)行以上程序，輸出結(jié)果為：

Hello, World

=head1 Hello, World 實(shí)例
這是一個(gè) Perl 的簡(jiǎn)單實(shí)例。
print "Hello, W3Cschool\n";

以下實(shí)例不讀取 POD 文檔：

#!/usr/bin/perl

print "Hello, World\n";

__END__

=head1 Hello, World 實(shí)例
這是一個(gè) Perl 的簡(jiǎn)單實(shí)例。
print "Hello, W3Cschool\n";

執(zhí)行以上程序，輸出結(jié)果為：

Hello, World

什么是 POD？

Pod(Plain Old Documentation), 是一種簡(jiǎn)單而易用的標(biāo)記型語言（置標(biāo)語言），它經(jīng)常用于在perl程序和模塊中的文檔書寫。

Pod 的 轉(zhuǎn)化器可以將 Pod 轉(zhuǎn)換成很多種格式，例如 text, html, man 等很多。

Pod 標(biāo)記語言包含三種基本基本類型： 普通, 原文, 和 命令。

• 普通段落: 你可以在普通段落中使用格式化代碼，如黑體，斜體，或代碼風(fēng)格，下劃線等。

• 原文段落: 原文段落，用于代碼塊或者其他不需要轉(zhuǎn)換器處理的部分，而且不需要段落重排。

• 命令段落: 命令段落作用于整個(gè)的文檔，通常用于標(biāo)題設(shè)置或列表標(biāo)記。

  所有的命令段落（他只有一行的長(zhǎng)度）使用 "=" 開始，然后是一個(gè)標(biāo)識(shí)符。 隨后的文本將被這條命令所影響?，F(xiàn)在被廣泛使用的命令包括

  =pod (開始文檔)
  =head1 標(biāo)題文本
  =head2 標(biāo)題文本
  =head3 標(biāo)題文本
  =head4 標(biāo)題文本
  =over 縮進(jìn)空格數(shù)量
  =item 前綴
  =back (結(jié)束列表)
  =begin 文檔格式
  =end 結(jié)束文檔格式
  =for 格式文本
  =encoding 編碼類型
  =cut (文檔結(jié)束)

在perl中，可以使用 pod2html **.pod >**.html 來生成html格式的pod文檔。

考慮以下 POD 實(shí)例：

=begin html
=encoding utf-8

=head1 W3Cschool教程

=cut

pod2html時(shí)會(huì)原文拷貝此段代碼。

使用 pod2html 命令執(zhí)行，將其轉(zhuǎn)換為 HTML 代碼：

$ pod2html test.pod > test.html 

在瀏覽器中打開 test.html，鏈接部分為索引

以下實(shí)例在 POD 文檔中直接寫入 HTML:

=begin html
=encoding utf-8

<h1>W3Cschool教程</h1>
<p> m.hgci.cn </p>

=end html

pod2html時(shí)會(huì)原文拷貝此段代碼。

使用 pod2html 命令執(zhí)行，將其轉(zhuǎn)換為 HTML 代碼：

$ pod2html test.pod > test.html 

在瀏覽器中打開 test.html，鏈接部分為索引