Plain Old Document －POD写法(perl)

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 的文件。