perlpodstyle - Perl POD 風格指南
這些是一些撰寫 Perl 腳本和模組的 POD 文件的通用準則，它們基於撰寫良好的 UNIX 手冊頁面的通用準則。當然，所有這些準則都是可選的，但遵循這些準則將使您的文件與系統上的其他文件保持一致。
慣例上，要記錄的程式名稱會以粗體（使用 B<>）撰寫，就像所有程式選項一樣。參數應以斜體（I<>）撰寫。函數名稱傳統上以斜體撰寫；如果您將函數寫成 function()，Pod::Man 會為您處理這項工作。文字程式碼或命令應在 C<> 中。對其他手冊頁面的參照應採用 manpage(section) 或 L<manpage(section)> 形式，而 Pod::Man 會自動適當地格式化這些參照。第二種形式，帶有 L<>，用於要求 POD 格式化程式在可能的情況下建立到手冊頁面的連結。作為一個例外，在參照模組文件時通常會省略章節，因為不清楚模組文件將位於哪個章節中；改用 L<Module::Name> 作為模組參照。
對其他程式或函數的參照通常採用手冊頁面參照的形式，以便交叉參照工具可以為使用者提供連結等。不過，這樣做可能會過度，因此請小心不要用過多的標記來弄亂您的文件。對未作為手冊頁面參照給出的其他程式的參照應包含在 B<> 中。
主要標題應使用 =head1 指令設定，並且歷來以相當驚人的全大寫格式撰寫；這不是強制性的，但強烈建議這麼做，以便各個軟體套件的章節具有相符的名稱。次要標題可以使用 =head2 加入，並且通常以混合大小寫表示。
手冊頁的標準章節為
強制性章節；應為此 POD 頁面所記錄的程式或函數的逗號分隔清單，例如
foo, bar - programs to do something手冊頁索引器通常對此章節的格式極為挑剔，因此除了這行之外，不要在其中放入任何內容。此 POD 頁面記錄的每個程式或函數都應列出，並以逗號和空格分隔。對於 Perl 模組，只需提供模組名稱。單一破折號，且僅限單一破折號，應將程式或函數清單與說明分隔開來。請勿在此行中的任何位置使用任何標記，例如 C<> 或 B<>。函數不應限定為 () 或類似。說明理想上應放在單一行中，即使 man 程式將破折號替換為幾個 tab 也是如此。
程式和函數的簡短使用摘要。此章節是第 3 節頁面的強制性章節。對於 Perl 模組文件，通常很方便將此章節的內容設為逐字區塊，顯示模組典型使用方式的一些（簡短）範例。
程式或函數的延伸說明和討論，或記錄其他內容的手冊頁的文件主體。如果特別長，建議將其分為小節 =head2 指令，例如
=head2 Normal Usage
=head2 Advanced Features
=head2 Writing Configuration Files或任何適合您文件內容的指令。
對於模組，這通常是放置模組提供的介面文件的地方，通常以清單形式表示，每個介面有一個 =item。根據介面的數量，您可能希望將該文件放在 METHODS、FUNCTIONS、CLASS METHODS 或 INSTANCE METHODS 等獨立章節中，並將 DESCRIPTION 章節保留為概觀。
程式所採用的每個命令列選項的詳細說明。這應與類似 Pod::Usage 的剖析器使用說明分開。這通常以清單呈現，每個選項為一個獨立的 =item。特定選項字串應以 B<> 括起。選項採用的任何值應以 I<> 括起。例如，選項 --section=manext 的區段會以以下方式介紹
=item B<--section>=I<manext>同義選項（例如簡短和長格式）以逗號和空格分隔，位於同一個 =item 行上，或選擇性地列為其自己的項目，並參考正規名稱。例如，由於 --section 也可寫成 -s，因此上述內容會是
=item B<-s> I<manext>, B<--section>=I<manext>建議先寫簡短選項，因為這樣比較容易閱讀。長選項夠長，可以吸引目光，而簡短選項在視覺雜訊中可能會被忽略。
如果成功，程式或函式傳回的內容。對於其精確結束代碼不重要的程式，可以省略此區段，只要它們在成功時傳回 0，失敗時傳回非 0，這符合標準。函式應始終包含此區段。對於模組，在此摘要模組介面的傳回值可能很有用，或在模組提供的每個函式或方法的說明文件中分別討論傳回值可能更有用。
例外、錯誤傳回代碼、結束狀態和 errno 設定。通常用於函式或模組說明文件；程式說明文件改用 DIAGNOSTICS。一般經驗法則為，印出至 STDOUT 或 STDERR 且供最終使用者閱讀的錯誤記錄在 DIAGNOSTICS 中，而傳遞至呼叫程式內部且供其他程式設計師閱讀的錯誤記錄在 ERRORS 中。在說明設定 errno 的函式時，應在此處提供可能的 errno 值的完整清單。
程式可以印出的所有可能訊息及其含義。您可能希望遵循與 Perl 說明文件相同的說明文件樣式；請參閱 perldiag(1) 以取得更多詳細資料（並查看 POD 來源）。
如果適用，請包含使用者應如何修正錯誤的詳細資料；將錯誤記錄為指示「輸入緩衝區太小」，卻沒有告訴使用者如何增加輸入緩衝區的大小（或至少告訴他們這是不可能的），並非很有用。
提供程式或函式的部分範例用法。不要偷工減料；使用者通常會覺得這是文件中最有用的部分。範例通常以逐字段落提供。
不要只提供範例，而不說明它做了什麼。加入簡短的段落說明範例將執行什麼動作，可以大幅增加範例的價值。
程式關心的環境變數，通常使用 =over、=item 和 =back 呈現為清單。例如
=over 6
=item HOME
Used to determine the user's home directory. F<.foorc> in this
directory is read for configuration details, if it exists.
=back由於環境變數通常都是大寫，因此通常不需要額外的特殊格式；它們本身就夠顯眼了。
程式或函式使用的所有檔案，通常以清單呈現，以及它如何使用這些檔案。檔案名稱應以 F<> 括起來。特別重要的是記錄可能會被修改的檔案。
需要特別注意的事項，有時稱為警告。
損壞或無法正常運作的事項。
您不打算修復的錯誤。 :-)
其他評論。
由誰撰寫（多人時使用 AUTHORS）。建議包含您的現行電子郵件地址（或應傳送錯誤報告的電子郵件地址）或其他連絡資訊，以便使用者有管道與您連絡。請記住，程式文件往往會比您預期的更久才被廣泛使用，因此請選擇一個可能會持續使用的連絡方式。
源自其他來源的程式有時會有這個。有些人會在此保留修改記錄，但這通常會很長，而且通常會以獨立檔案妥善維護。
關於著作權
Copyright YEAR(s) YOUR NAME(s)（不，不需要 (C)。不，不需要「保留所有權利」。）
關於授權，最簡單的方式是使用與 Perl 相同的授權
This library is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.這樣可以讓使用者輕鬆地將您的模組與 Perl 搭配使用。請注意，這個授權範例既不是認可也不是要求，您當然可以自由選擇任何授權。
其他手冊頁面，例如 man(1)、man(7)、makewhatis(8) 或 catman(8)。通常是使用逗號分隔的手冊頁面清單，或提供參考著作名稱的段落。手冊頁面參考，如果使用標準的 name(section) 格式，則不必包含在 L<> 中（儘管建議這麼做），但本節中的其他內容在適當情況下可能應該包含在其中。
如果套件有郵件清單，請在此處包含 URL 或訂閱說明。
如果套件有網站，請在此處包含 URL。
物件導向函式庫或模組的說明文件可能需要使用 CONSTRUCTORS 和 METHODS 區段，或 CLASS METHODS 和 INSTANCE METHODS 區段，以詳細說明函式庫的各個部分，並將 DESCRIPTION 區段保留給概觀。具有函式介面的大型模組可能需要使用 FUNCTIONS 出於類似的原因。有些人會使用 OVERVIEW 來摘要說明，如果說明很長的話。
區段順序會有所不同，儘管 NAME 必須永遠是第一個區段（否則您會中斷一些手冊頁系統），而且 NAME、SYNOPSIS、DESCRIPTION 和 OPTIONS 通常總是會先出現，且依此順序出現（如果存在的話）。一般來說，SEE ALSO、AUTHOR 和類似的資料應留到最後。有些系統也會將 WARNINGS 和 NOTES 移到最後。上面給出的順序應該合理適用於大多數目的。
有些系統使用 CONFORMING TO 來註明符合相關標準，並使用 MT-LEVEL 來註明在執行緒程式或訊號處理常式中使用的安全性。這些標題主要在說明 C 函式庫的各個部分時很有用。
最後，作為一般注意事項，請嘗試不要使用過多的標記。如本文檔和 Pod::Man 中所述，您可以安全地保留 Perl 變數、函式名稱、手冊頁參考等，而不會被標記修飾，而且 POD 轉譯器會為您找出它們。這使得稍後編輯說明文件變得容易許多。請注意，許多現有的轉譯器在用 L<> 包裹電子郵件地址時會出錯，所以請不要這麼做。
Russ Allbery <rra@cpan.org>，這份說明文件的大部分取自 Larry Wall 和 Tom Christiansen 對原始 pod2man 實作的說明文件。
著作權 1999、2000、2001、2004、2006、2008、2010、2015、2018 Russ Allbery <rra@cpan.org>
允許在任何媒體中複製和散佈此檔案，無論是否修改，只要保留著作權公告和此公告即可。此檔案以原樣提供，不提供任何保證。
SPDX-License-Identifier: FSFAP
如需對您的特定系統更準確的其他資訊，請參閱 man(5) 或 man(7)，具體取決於您的系統手冊章節編號慣例。
此文件是 podlators 發行的一部分。最新版本隨時可以在其網站上取得，網址為 https://www.eyrie.org/~eagle/software/podlators/。