=head1 NAME
The name of your program or module.
=head1 SYNOPSIS
A one-line description of what your program or module does (purportedly).
=head1 DESCRIPTION
The bulk of your documentation. (Bulk is good in this context.)
=head1 AUTHOR
Who you are. (Or an alias, if you are ashamed of your program.)
=head1 BUGS
What you did wrong (and why it wasn't really your fault).
=head1 SEE ALSO
Where people can find related information (so they can work around your bugs).
=head1 COPYRIGHT
The copyright statement. If you wish to assert an explicit copyright, you should say something like:
Copyright 2013, Randy Waterhouse. All Rights Reserved.
注意：每个=标签上下必须隔一行，否则就会错误解析。
=for html 或者 =for text
是把下面的单行注视当作html或者text来处理，与其功能类似的是 =begin html / =end html ; =begin text / =end text 两对。begin和end之间可以处理多行。
=over 4
=item SOMEWORD
*************
=item somewordelse
******
=back
以上写法是写一个列表，以over开头，后面的数字是列表中每行的缩进量。最后以=back 结尾。
=cut 是结束pod块的标志，与程序分开。
在perl中，可以使用 pod2html **.pm >**.html 来生成html格式的pod文档。
空行加空格加内容加空行
这个内容再pod2html后就会变成code代码框。
Perlpod -- Perl Plain Old Documentation
基本上，對於 pod2xxx ("xxx" 可以是 txt, html, latex or man)來說，一個 pod 文件只有三種東西:
1. Verbatim Paragraph -- 這種段落以空白或 tab 開始(就是有縮排)，段落 中的文字不會被轉譯，例如 '/' 就是 '/'。 2. Command -- pod 的命令是以 '=' 開始，後面接英文字，至於他有哪些命令 ，會在稍後介紹。 3. 一段文字 -- 與 1. 不同之處在於這裡面可以加些類似 "Markup" 的東西， 也可以加 link，由 pod2html 幫你處理。後面也會介紹他有哪些功能。
值得注意的是，對於 pod2xxx 這些轉譯程式來說，上面三種東西最好都是用前後 各一行空白來將他們區隔開來。不然轉出來的東西，其格式可能不甚符合你的期望。
接下來介紹 2. Command。總共就十個命令而已：
=head1 heading =head2 heading =item text =over N =back =cut =pod =for X =begin X =end X
1. =headN heading
這看來就知道是用來當標題文字的，後面接的 "heading" 就是此標題名。例如:
=head1 篇名
perlfaq7 - Perl 語言相關問題
=head1 概述
本篇內的問題主要是無法納入其他部份且與 Perl 語言相關的一般問題。
=head2 我能拿到 Perl 的 BNF/yacc/RE 嗎?
轉成 html 後還可以自動做出同頁連結。可參考 perlfaq 的結果。
2. =item, =over and =back
對於熟悉 HTML 的人來說，這三樣分別相當於 <li>, [<ul>|<ol>], [</ul>|</ol>], (這裡用正規表示式來描述。)所以要產生一個列表，用 =over 開始，以 =item 鋪陳 出每個項目，然後用 =back 結尾。請不要在 =over .. =back 這圈圈外使用 =item! =over n 後面的 n 可以用來表示預定的縮排字數，預設為 4。
=item * 表示此列表是沒有排順序的，亦即 unordered list，而 =item 1., =item 2. 則是用數字表示，當然 =item foo ,=item bar 也是合法的用法。使用時 請注意其一致性。以下即為範例：
=over 4
=item *
第一個項目
=item *
第二個項目
=back
=over 4
=item Foo()
Description of Foo function
=item Bar()
Description of Bar function
=back 3. =cut 和 =pod
這兩個是難兄難弟，其實他最大的用途在於當你寫 Perl 程式，裡面有包含 pod 格式的說明文字時，用 =pod 開頭， =cut 結尾包起來的那幾段都會被 Perl 直譯器 給忽略。就這樣，跟常看到的 "--- cut here ---" 用法與意義差不多。
4. =for, =begin 和 =end
以 =for 為首的那一段文字(請注意，只有其緊接下來的一段文字而已)，會被 pod 轉譯程式忽略，直接送給所指定的 formatter，例如以下就是標明一段 html 文字：
=for html <br> <P>這是一段 HTML 文件</P>
所以 =for 後面接的就是格式名，目前所接受的格式有(大多都在 Unix 下)： "roff", "man", "latex", "tex", "text", 和 "html"。
=begin 和 =end 的用途和 =for 一樣，只是他兩就相當於擔任劃清界線的功用，就 不只限於一段文字，可以是很多段了... 例如：
=begin html
<br>Figure 1.<IMG SRC="figure1.png"><br>
=end html
=begin text
--------------- | foo | | bar | ---------------
^^^^ Figure 1. ^^^^
=end text
只要切記，每個段落或命令之間都要用一行空白來隔開，則寫 pod 就很簡單了。
接下來介紹一些類似 HTML 標籤的用法：
I<text> 傾斜文字 B<text> 加粗文字 S<text> 包含了連續空白的文字 C<code> 表示一段文字碼 L<name> 連結到 "name" 去，用法有以下幾種： L<name> 其他說明文件 L<name/ident> 其他說明文件中的某項目 L<name/"sec"> 其他說明文件中的某段落 L<"sec"> 本文件中的某段落( " 可有可無) L</"sec"> 同上 F<file> 用來表示檔案名 X<index> 表示一索引項目 Z<> 零長度字元 E<escape> 控制字元(相當近似於 html 的 escape character) E<lt> 代表 < E<gt> 代表 > E<n> 第 n 個字元 (ASCII 中的) E<html> 非數字的 HTML 實體字元，例如 E<Agrave>.
以下節錄一段 Perl FAQ Part 7，裡面有些用法：
注意 E<lt>FILEE<gt> I<不是> 用來指定檔案的形態，亦非此把手的名字。它只是將C<E<lt>E<gt>> 運算子用在 FILE 把手上。它自 FILE 把手讀入一行 (嗯，該說一筆記錄，參看 L<perlvar/$/>) 當作純量變數的內容，或讀入 I<全部> 當作陣列變數的內容。當使用開、關或其它 C<E<lt>E<gt>> 之外的動作於檔案上，或甚至只是提到把手時，切記 I<不要> 使用 C<E<lt>E<gt>>。下面的用法是正確的：C<eof(FH)>，C<seek(FH, 0,2)>以及 "copying from STDIN to FILE"。
這裡面用到了 E<>, I<>, C<>, 及 L<>。算是個不錯的範例。
Okay, 整個 POD 的命令與格式就是這麼簡單。目前進行中的 Perl FAQ 中文翻譯都是 直接翻 pod 檔，再交給 hsiao 先生轉成 html 格式。是還沒有什麼大問題。所以若 要省去發展格式與轉換程式的時間，那或許採用 pod 是個不錯的主意。 By the way, pod 的作者當然是 Larry Wall --- Perl 的爸爸。可以再參考 perlpod 的文件。
