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>> 咚阕佑迷
（编辑：李大同）
【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!
