Plain Old Document －POD写法(perl)
2011-04-17 10:51
225 查看
=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 的文件。
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 的文件。
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐
- C++ POD(Plain Old Data)类型
- POD（plain old data）
- Plain old data structure(POD)
- C++ Aggregate 与 POD（Plain Old Data）的解释
- C++ trivial和non-trivial及POD类型POD(Plain Old Data)
- perl pod document
- Plain Old Data (POD)
- C++ POD(Plain Old Data)类型
- Plain Old Data (POD)
- Plain Old Data (POD) （转）
- C++ POD(Plain Old Data)类型
- C++ POD(Plain Old Data)类型
- C++ POD(Plain Old Data)类型
- C++ POD(Plain Old Data)类型
- C++中的Plain Old Data(POD)
- perl的Getopt::Long和pod::usage ？
- jQuery:理解$(document).ready()的特殊写法 推荐
- Passive data structure plain old data structure, or plain old data.
- perl Exporter一些神奇写法
- perl 将XML格式转换为html、txt、pod格式