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, w3big\n";

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

Hello, World
Hello, w3big

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

#!/usr/bin/perl

print "Hello, World\n";

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

__END__

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

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

Hello, World

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

以下實例不讀取POD 文檔：

#!/usr/bin/perl

print "Hello, World\n";

__END__

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, w3big\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 本教程

=cut

pod2html時會原文拷貝此段代碼。

使用pod2html 命令執行，將其轉換為HTML 代碼：

$ pod2html test.pod > test.html

在瀏覽器中打開test.html，鏈接部分為索引，顯示如下:

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

=begin html
=encoding utf-8

<h1>本教程</h1>
<p> www.w3big.com </p>

=end html

pod2html時會原文拷貝此段代碼。

使用pod2html 命令執行，將其轉換為HTML 代碼：

$ pod2html test.pod > test.html

在瀏覽器中打開test.html，鏈接部分為索引，顯示如下: