Plain Old Document －POD写法(perl)

慧9建

　　Plain Old Document －POD写法
一般包括一下几个部分：
　　=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 的文件。