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