Perl POD 文檔

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

POD 是一種簡單而易用的標記型語言（置標語言）。

POD 文件使用規則：

POD 文件以=head1 開始，  =cut 結束， =head1 前與=cut 後面新增一空行。

Perl 會忽略 POD 中的文件。實例如下：

#!/usr/bin/perl

print "Hello, World\n";

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
=cut

print "Hello, php\n";

執行上述程序，輸出結果為：

Hello, World
Hello, php

我們也可以使用"__END__" 或"__DATA__" 將所在行之後的內容全部"註解"掉：

#!/usr/bin/perl

print "Hello, World\n";

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

__END__

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, php\n";

執行上述程序，輸出結果為：

Hello, World

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, php\n";

以下實例不讀取POD 文件：

#!/usr/bin/perl

print "Hello, World\n";

__END__

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, php\n";

執行以上程序，輸出結果為：

Hello, World

什麼是POD？

Pod(Plain Old Documentation), 是一種簡單而易用的標記型語言（置標語言），它經常用於在perl程式和模組中的文件書寫。

Pod 的 轉換器可以將 Pod 轉換成很多種格式，例如 text, html, man 等很多。

Pod 標記語言包含三種基本基本類型： 普通, 原文, 和 指令。

• 普通段落: 你可以在普通段落中使用格式化程式碼，如黑體，斜體，或程式碼風格，底線等。

• 原文段落: 原文段落，用於程式碼區塊或其他不需要轉換器處理的部分，而且不需要段落重排。

• 命令段落: 指令段落作用於整個的文檔，通常用於標題設定或清單標記。

  所有的指令段落（他只有一行的長度）使用 "=" 開始，然後是識別碼。 隨後的文本將被這條命令所影響。現在廣泛使用的指令包括

  =pod (开始文档)
  =head1 标题文本
  =head2 标题文本
  =head3 标题文本
  =head4 标题文本
  =over 缩进空格数量
  =item 前缀
  =back (结束列表)
  =begin 文档格式
  =end 结束文档格式
  =for 格式文本
  =encoding 编码类型
  =cut (文档结束)

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

考慮以下 POD 實例：

=begin html
=encoding utf-8

=head1 php中文网

=cut

pod2html時會原文拷貝此段程式碼。

使用pod2html 指令執行，將其轉換為HTML 程式碼：

$ pod2html test.pod > test.html

在瀏覽器中開啟test.html，連結部分為索引，顯示如下:

以下實例在POD 文件中直接寫入HTML:

=begin html
=encoding utf-8

<h1>php中文网</h1>
<p> www.php.cn </p>

=end html

pod2html時會原文拷貝此段程式碼。

使用pod2html 指令執行，將其轉換為HTML 程式碼：

$ pod2html test.pod > test.html

在瀏覽器中開啟test.html，連結部分為索引，顯示如下: