perldocstyle - 編寫 Perl 文件的風格指南
本文件是撰寫和維護 Perl 附帶文件的指南。這包括以下內容
數十個手冊章節，其檔名以「perl」開頭，例如 perlobj、perlre 和 perlintro。（還有 perl。）
所有 Perl 附帶模組的文件（如 perlmodlib 所列）。
從 perlfunc 檔案衍生的數百個個別呈現的參考章節。
本指南以後將根據 Unix 慣例將使用者手冊章節檔案稱為「手冊頁」。
本風格指南旨在為 Perl 核心文件建立適用的標準、程序和理念。
遵守這些標準將有助於確保 Perl 手冊的任何一部分都具有與其他部分一致的語氣和風格。與 Perl 項目的其他部分一樣，該語言的文檔集合是一個開源項目，由許多人在很長一段時間內編寫的。在如此廣泛的工作中保持一致性是一個挑戰；本指南提供了一個基礎來幫助減輕這種困難。
這將有助於其讀者——尤其是 Perl 新手——對 Perl 的文檔感到更受歡迎和參與，而這反過來又將通過擁有更多、更多樣化和更有信心的知識用戶群體來幫助 Perl 項目本身變得更強大。
任何有興趣為 Perl 核心文檔做出貢獻的人員都應熟悉本指南概述的標準。
除了 Perl 項目本身之外，記錄自己工作的程式設計師也可能會發現本指南很有價值，特別是如果他們希望自己的工作擴展 Perl 自身手冊的語氣和風格。
本指南最初起草於 2020 年底，借鑒了與 Perl 同時代的幾種開源技術的文檔風格指南。這包括 Python、Raku、Rust 和 Linux 核心。
作者打算將本指南用作啟動對 Perl 大量現有文檔進行審查的起點，並期望進行此審查的人員應根據 Perl 編程手冊的特殊要求和怪癖來發展和修改本指南。
Perl 的所有核心文件都使用 Pod（「純舊文件」），這是一種簡單的標記語言，來格式化其原始文字。Pod 的精神類似於其他當代輕量級標記技術，例如 Markdown 和 reStructuredText，並且與 Perl 本身有著數十年的共同歷史。
有關 Pod 語法的完整參考，請參閱 perlpod。為了閱讀本指南，熟悉 Pod 語法中的章節標題（=head2 等）和內嵌文字格式（C<like this>）應已足夠。
Perl 程式設計師也會使用 Pod 來記錄自己的腳本、函式庫和模組。這種 Pod 用法有其自己的風格指南，由 perlpodstyle 概述。
Perl 的核心文件以英語撰寫，偏好使用美式拼字和詞組表達。這表示「color」優於「colour」、「math」優於「maths」、「the team has decided」而非「the team have decided」，依此類推。
我們命名一種英語風格，以確保 Perl 文件的一致性，就像軟體專案可能會宣告四個空格的縮排標準一樣，即使這不會影響程式碼編譯的順利程度。這兩種做法都能避免在文件中間出現令人不快的格式或風格變更，進而讓閱讀更輕鬆。
Perl 文件的貢獻者應注意，此規則說明了專案的最終已發布輸出，並不規定社群貢獻中使用的方言。文件小組熱烈歡迎任何英語貢獻，並會在有需要時積極協助將拼字和風格美式化。
Perl 文件有社群編寫的翻譯，涵蓋各種語言。雖然 Perl 計畫感謝這些翻譯工作，並在適用的情況下推廣這些翻譯，但它並未正式支援或維護任何翻譯。
話雖如此，保持 Perl 文件清晰、簡潔和簡短，對任何此類翻譯計畫都有助益。
（請注意，Perl 原始碼發行版中包含的中文、日文和韓文 README 檔案是此語言選擇的例外，但這些文件不在本指南的範圍內。）
Perl 核心文件編碼為 UTF-8，可以使用此編碼允許的全範圍字元。
因此，每個核心文件（或每個核心模組的 Pod 區段）都應該以 =encoding utf8 宣告開始。
Perl 文件使用第 17 版的芝加哥手冊風格（CMOS）作為其風格和語法的基礎指南。雖然您目前正在閱讀的文件努力作為 Perl 文件編寫的適當獨立風格指南，但作者應將 CMOS 視為未在此處涵蓋的任何相關主題的最終權威。
因為 CMOS 不是免費資源，因此取得 CMOS 並不是參與 Perl 文件編寫的先決條件；文件團隊將協助參與者了解並視需要套用其準則。不過，我們確實鼓勵任何有興趣大幅參與文件編寫的人取得或至少閱讀 CMOS。（大部分公共圖書館應該都有提供副本，而且也可以在網路上找到衍生自 CMOS 的基礎知識。）
Perl 和任何程式語言一樣，其優劣取決於其文件。Perl 仰賴清晰、友善且詳盡的文件，才能歡迎全新使用者、教授並說明語言的各種概念和元件，並作為經驗豐富的 Perl 程式設計師的終身參考。因此，Perl 專案歡迎並重視所有改善語言文件的社群努力。
Perl 透過與程式碼貢獻相同的開源專案管道接受文件貢獻。請參閱 perlhack 以取得更多資訊。
本節詳細說明所有 Perl 核心文件應遵循的特定 Pod 語法和樣式，以確保一致性和可讀性。
每一份 Perl 核心文件，無論是包含在 .pod 檔案中或在標準程式碼模組的 Pod 區段中，其結構都遵循許多長期的 Unix 手冊頁慣例。（因此本指南使用「手冊頁」來指 Perl 文件的任何一個獨立部分。）
遵循這些慣例有助於 Pod 格式化程式以不同的內容呈現 Perl 手冊頁，無論是終端機、網路甚至列印。下列許多需求都源自 perlpodstyle，而其建議又是源自這些根深蒂固的做法。
在 Perl 手冊頁的 =encoding utf8 宣告之後，必須 呈現一個名為「NAME」（字面上）的一級標題，後面接一個包含頁面名稱和非常簡短說明的段落。
名為 perlpodexample 的假設頁面的前幾行
=encoding utf8
=head1 NAME
perlpodexample - An example of formatting a manual page's title line大多數 Perl 手冊頁面也包含一個 DESCRIPTION 區段，其中摘要或介紹文件內容和目的。
此區段也應該以某種方式清楚地指出手冊頁面的受眾，特別是如果它對讀者的先備知識有預期。例如，深入探討 Perl 正規表示式引擎內部運作的手冊頁面應在前頭說明其假設，並快速將尋找更基礎的參考或教學課程的讀者重新導向。
適當的情況下，參考頁面可以在 DESCRIPTION 前面加上一個 SYNOPSIS 區段，其中列出一個或多個程式碼區塊，提供所參考功能使用的一些非常簡短的範例。此區段應顯示一些常見情況和最佳實務範例，而不是列出所有可用的模糊方法或替代語法的詳盡清單。
適當的情況下，頁面應以 SEE ALSO 區段作結，其中包含 Perl 手冊相關區段、其他 Unix 手冊頁面或適當網頁的超連結。透過 L<...> 超連結每個此類交叉參照。
要包含哪些其他區段完全取決於手邊的主題。作者應自由包含進一步的 =head1 層級區段，無論是 perlpodstyle 列出的其他標準區段，或特定於頁面主題的區段；在任何情況下，都應以全大寫字母呈現這些頂層標題。
然後，您可以在它們下方包含任意多個子區段，以符合本指南其他地方建議的清晰度、可及性和交叉參照關聯性標準。
在大部分情況下，Perl 的獨立手冊頁（包含在 .pod 檔案中）不需要包含任何關於它們自己的版權或授權資訊。它們的原始 Pod 檔案是 Perl 自身核心軟體儲存庫的一部分，而這已經在與 Perl 相同的版權和授權條款下涵蓋它們。您不需要包含您自己的額外「LICENSE」或「COPYRIGHT」部分。
這些手冊頁可以選擇在「AUTHOR」或「CONTRIBUTORS」標題下，註明它們的主要作者或列出重要的貢獻者。請注意，作者姓名出現並不排除特定頁面 以與 Perl 其他文件一致的語氣撰寫。
請注意，這些指南不適用於與 Perl 一起提供的核心軟體模組。這些模組有自己的作者身分和版權聲明標準，如在 perlpodstyle 中所述。
Perl 手冊頁 Pod 原始檔中的每一行長度應為 72 個字元或更少。
請將段落分成短行的區塊，而不是在沒有換行的情況下「軟換行」跨越數百個字元的段落。
就像它們周圍的文字一樣，所有程式碼範例都應盡可能簡短且易讀，僅顯示說明手邊概念所絕對必要的複雜性。
為了在 Perl 的手冊頁內部和跨手冊頁之間保持一致性，所有範例都必須遵守 perlstyle 所設定的程式碼佈局原則。
範例程式碼應僅在必要時偏離這些標準：例如，在展示 Perl 如何忽略空白時，或為了無法避免的冗長說明而暫時切換到兩欄縮排。
您可以在範例程式碼中加入註解，以進一步釐清或標示程式碼的內聯行為。您也可以將註解用作一般存在的程式碼的佔位符，但與目前主題無關，如下所示
while (my $line = <$fh>) {
#
# (Do something interesting with $line here.)
#
}即使是最簡單的程式碼區塊通常也需要使用範例變數和子常式，您應該仔細選擇其名稱。
在一段文字中，引用或參照任何 Perl 程式碼時，請使用 C<...>，即使它只有一個字元長。
例如，在說明性段落中參照 Perl 的將兩個數字相加的運算子時，您會寫成「C<+>」。
使用 C<...> 以等寬字型呈現所有 Perl 函數名稱，無論它們出現在文字中的何處。
除非您需要特別引用帶有引數清單的函數呼叫，否則請不要在文字中函數名稱後加上一對空括號。也就是說，在一般參照 Perl 的 print 函數時，請寫成「print」，而不是「print()」。
以全大寫表示函數預期的引數，不使用符號，並使用 C<...> 以等寬字型呈現它們。這些引數應具有簡短的名稱，以清楚說明其性質和目的。慣例指定了幾個在 Perl 文件中常見的引數
EXPR
「通用」引數：任何純量值，或評估為一個純量值的 Perl 表達式。
ARRAY
陣列，儲存在命名變數中。
HASH
雜湊，儲存在命名變數中。
BLOCK
大括號程式碼區塊或子常式參考。
LIST
任何數量的值，儲存在任何數量的變數或表達式中，函數將「扁平化」這些值並將它們視為單一清單。（而且由於它可以包含任何數量的變數，因此它必須是最後一個引數，如果存在的話。）
如果可能，請為標量引數命名，以建議它們在引數中的用途。例如，請參閱 substr 的文件，其中列出的引數包括 EXPR、OFFSET、LENGTH 和 REPLACEMENT。
在 Pod 來源中，請使用直引號，而不是「捲曲引號」：「這樣」，而不是「這樣」。撇號也是一樣：以下是正面的範例，而這是負面的範例。
將連字號呈現為兩個連字號，就像這樣
Render em dashes as two hyphens--like this.交由格式化程式重新格式化並重新調整這些標點符號的形狀，以最適合它們各自的目標媒體。
當使用其自己的手冊頁 (在 Perl 的文件之外) 參照 Unix 程式或 C 函式時，請在括號中包含其手冊部分編號。例如：malloc(3) 或 mkdir(1)。
如果在手冊頁或部分中第一次提到這個程式，請將其設為交叉參照，例如 L<malloc(3)>。
否則，請勿對此文字進行樣式設定。
請大量使用 Pod 的 L<...> 語法，以建立超連結至目前手冊頁的其他部分，或其他文件，無論是在讀者的電腦上其他地方，或透過 URL 在網際網路上。
在提到時，請使用 L<...> 連結至目前手冊頁的另一個部分，並利用其頁面和部分語法連結至 Perl 文件中個別頁面的最特定部分。通常，當您第一次在特定頁面或部分中參照特定函式、程式或概念時，請考慮連結至其完整文件。
超連結不會取代本指南要求的其他格式設定；Pod 允許巢狀文字格式，您應該視需要使用此功能。
以下是一個範例句子，其中提到 Perl 的 say 函式，並連結至 perlfunc 手冊頁中的文件部分
In version 5.10, Perl added support for the
L<C<say>|perlfunc/say FILEHANDLE LIST> function.請注意使用垂直線條（「|」）來區分連結會如何顯示給讀者（「C<say>」）以及格式化程式連結到的完整頁面和區段規格。
Pod 並未正式支援表格。若要最佳呈現表格資料，請將表格包含為 HTML 和純文字表示法，後者為縮排的程式碼區塊。使用 =begin / =end 指令分別將這些表格設定為 html 和 text Pod 格式化程式。例如
=head2 Table of fruits
=begin text
Name Shape Color
=====================================
Apple Round Red
Banana Long Yellow
Pear Pear-shaped Green
=end text
=begin html
<table>
<tr><th>Name</th><th>Shape</th><th>Color</th></tr>
<tr><td>Apple</td><td>Round</td><td>Red</td></tr>
<tr><td>Banana</td><td>Long</td><td>Yellow</td></tr>
<tr><td>Pear</td><td>Pear-shaped</td><td>Green</td></tr>
</table>
=end html數字和圖形插圖也是如此。Pod 本身不支援內嵌圖形，但您可以將 HTML <img> 標籤與等寬字體文字藝術表示法混合使用，來呈現這些影像的內容。
部分原因是這些限制，大多數 Perl 手冊頁面都不使用表格或圖表。不過，就像文件工具包中的任何其他工具一樣，當它們可以提升說明的清晰度，而不會增加其複雜性時，您可以考慮將它們包含在內。
如同任何其他類型的原始碼，Pod 讓您可以插入註解，這些註解僅對直接閱讀原始碼的其他人員可見，而轉換 Pod 成為各種對人類友善的輸出格式（例如 HTML 或 PDF）的格式化程式會忽略這些註解。
若要註解 Pod 文字，請使用 =for 和 =begin / =end Pod 指令，將它們設定為目標為「comment」的（假設）格式化程式。以下提供幾個範例
=for comment Using "=for comment" like this is good for short,
single-paragraph comments.
=begin comment
If you need to comment out more than one paragraph, use a
=begin/=end block, like this.
None of the text or markup in this whole example would be visible to
someone reading the documentation through normal means, so it's
great for leaving notes, explanations, or suggestions for your
fellow documentation writers.
=end comment依照任何良好開源專案的傳統，您應該自由但明智地使用註解，以在需要時留下內嵌「元文件」，供其他 Perl 文件撰寫人員（包括未來的您）使用。
perlfunc 手冊頁面是每個 Perl 內建函式的完整參考，它有幾項在 Perl 文件中其他地方看不到的格式化規則。
在 Perl 建置過程中使用的軟體（Pod::Functions）會根據特定規則剖析此頁面，以便為每個 Perl 函式建立個別的手冊頁面，以及達成其他索引效果。因此，perlfunc 的貢獻者必須了解並遵守其特定規則。
大部分的 perfunc 手冊頁面包含一個清單，位於標題 "Perl 函式的字母順序清單" 下方。每個函式參考都是清單上的項目，由三部分組成，順序如下
一個 =item 行清單，每個行以範本格式示範如何呼叫此函數。對於函數所接受的每個參數組合（如果適用，包括沒有參數），都應該有一行。
如果現代最佳實務偏好某些呼叫函數的方式，那麼這些方式應該列在清單的最前面。
清單的第一個項目應該緊接著一個或多個 X<...> 項目，列出值得索引的主題；如果沒有其他主題，則列出函數名稱，不帶參數。
一個針對 Pod::Functions 的 =for 行，包含一行描述函數功能的說明。這會寫成一個片語，以命令式動詞開頭，沒有開頭大寫字母或結尾標點符號。範例包括「引用字詞清單」和「變更檔名」。
函數定義和參考文件，包括所有說明文字和程式碼範例。
需要將文字分為小節的複雜函數（根據「慷慨地套用小節標題和範例」的原則），可以使用子清單，並將 =item 元素當作標題文字。
一個虛構的函數「myfunc」，它將清單作為選用參數，在 perlfunc 中的條目可能如下所示
=item myfunc LIST
X<myfunc>
=item myfunc
=for Pod::Functions demonstrate a function's perlfunc section
[ Main part of function definition goes here, with examples ]
=over
=item Legacy uses
[ Examples of deprecated syntax still worth documenting ]
=item Security considerations
[ And so on... ]
=back除了「元」文件（例如 perlhist 或 perlartistic），Perl 的每個手冊頁都應該符合 Daniele Procida 所著的《文件系統》 所建議的四種文件「模式」之一。這些模式包括教學、食譜、說明和參考，我們在下面會更詳細地定義這些術語。
每種文件模式都針對不同的受眾，不只是背景和技能層級不同的人，還有個別讀者，他們對語言文件的需求會根據脈絡而有所不同。例如，一位有充裕時間學習 Perl 新概念的程式設計師可以輕鬆地閱讀相關教學，然後再透過研究說明來進一步擴展他們的知識。稍後，同一位程式設計師在處理大量實際程式碼，只需要查詢某些函數的精確語法時，會希望取用參考頁面。
Perl 的文件必須努力滿足這些不同的情境期待，方法是將每個手冊頁限制為單一模式。這有助於撰寫者確保他們提供給讀者所需或預期的文件，儘管情況不斷變化。
教學手冊的重點在於學習，理想上是透過實作。它會提供讀者一些小而有趣的範例，讓他們可以透過自己的 Perl 詮譯器跟著做。教學手冊透過讓讀者立即體驗（並實驗）相關概念，激發他們的理解力。範例包括 perlxstut、perlpacktut 和 perlretut。
教學手冊必須從一開始就努力營造出親切且令人安心的語氣；它們很可能是 Perl 新手讀到的第一份文件，在他們是否決定繼續學習 Perl 中扮演重要的角色。即使是經驗豐富的程式設計師，也能從關於進階主題的教學手冊中獲得勇氣。在完成教學手冊後，讀者應該會覺得自己從對該主題一無所知，進步到對其基本概念有振奮人心的理解，並對進一步學習和實驗感到興奮。
教學手冊當然可以使用真實世界的範例，只要這些範例有助於提供清晰且相關的示範，並持續專注於教學即可——更實務的問題解決應留給食譜手冊（如下所述）。教學手冊也不必探討事物在表面下運作的原因或方式，或探索替代的語法和解決方案；這些內容更適合由說明手冊和參考頁面處理。
食譜手冊的重點在於結果。就像它的名稱所暗示的，它會針對某個主題周圍的各種真實世界問題，提供簡潔的分步解決方案。食譜手冊的程式碼範例較少用於啟發，而更多用於提供快速且可立即貼上的解決方案，讓讀者可以立即套用於他們面臨的情況。
Perl 食譜手冊示範了所有工具和技術如何在其他地方說明的情況下，共同運作以達成實務結果。任何更深入的說明都應該放在說明手冊和參考頁面中。（當然，食譜手冊可以交叉參照其他手冊，以滿足讀者的好奇心，讓他們在解決眼前的問題後，有機會進一步學習。）
隨 Perl 本身附帶的最顯著的食譜頁面是其眾多的常見問題解答頁面，特別是 perlfaq4 及後續版本，這些頁面以問答形式提供實用問題的簡短解決方案。perlunicook 顯示另一個範例，包含各種國際化文字操作的實用程式碼片段。
(題外話：文件系統將此模式稱為「操作指南」，但 Perl 創作料理的歷史偏好我們在此使用的更貼近廚房的術語。)
參考頁面著重於描述。簡潔、統一且簡練的參考頁面（通常排列在一個包含相互類似子頁面的完整區段中）非常適合讓讀者「隨機存取」，讀者精確知道他們需要什麼知識，在返回手邊任務之前只需要最少量的資訊。
Perl 本身最棒的參考範例是 perlfunc，這個龐大的手冊頁詳細說明內建於 Perl 的每個函式的運作，每個函式的文件都以相同的順序呈現相同類型的資訊。有關單一主題較短的參考範例，請參閱 perlreref。
模組文件（包括 perlmodlib 中列出的所有模組的文件）也計為參考。它們遵循與 perlpodstyle 手冊頁中規定的類似原則，例如以範例豐富的「SYNOPSIS」區段開頭，或提供「METHODS」區段，簡潔地列出並定義物件導向模組的公開介面。
說明頁面著重於討論。每個說明都會深入探討與 Perl 相關的主題，花費所有必要的時間和空間，讓讀者對其有透徹的了解。說明旨在透過學習傳授知識。它們不假設學生已經啟動 Perl 解譯器並渴望立即的範例（例如教學課程），或需要快速解答的特定 Perl 問題（食譜和參考頁面可以提供協助）。
除了其參考頁面外，Perl 手冊的大部分內容都屬於此模式。這包括大部分名稱以「perl」開頭的手冊頁面。一個很好的例子是 perlsyn，即 Perl 語法頁面，它在廣泛的討論中探討了 Perl 獨特語法的來龍去脈，並包含許多對該語言的歷史、文化和驅動理念的參考。
Perl 的說明頁面讓作者有機會探索 Perl 對 TMTOWTDI 的偏好，說明使用討論中的語言功能的替代甚至晦澀的方式。然而，正如本指南的其餘部分所討論的，理想的 Perl 文件能夠清晰簡潔地傳達其訊息，而不是將單純的冗長當作完整性。
請記住，此分類的目的不是要規定內容——例如，一個非常徹底的說明頁面可能包含其自己的簡短參考部分，或者一個關於非常複雜函數的參考頁面可能在某些地方類似於一個說明頁面（例如 open）。相反，它確保任何給定手冊頁面的作者和貢獻者都同意該頁面針對哪種類型的受眾。
如果一個新的或其他未分類的手冊頁面表現得無法僅適合於四種模式中的其中一種，請考慮將其拆分為單獨的頁面。這可能表示建立一個新的「perl[...]」手冊頁面，或者（在模組文件的情況下）在該模組的命名空間下建立新的套件，僅用於保存其他文件。例如，Example::Module 的參考文件可能包含一個指向 Example::Module::Cookbook 的參閱連結。
Perl 的幾個關於 Unicode 的手冊頁面——包括一個簡短的教學課程、一個徹底的說明、一本食譜和一個常見問題解答——提供了一個很好的例子，說明如何將一個複雜的主題分佈在幾個具有不同且明確指示目的的手冊頁面上。
Perl 從其作為精通 C 編程和各種 Unix 實用程式的人員的工具的卑微開端以來，已經有了很大的發展。如今，學習 Perl 的人可能來自任何社會或技術背景，其可能的動機範圍遠遠超出了系統管理。
Perl 的核心文件必須通過對讀者的先驗知識做出盡可能少的假設來認識到這一點。雖然你應該假設 Perl 文件的讀者很聰明、好奇且渴望學習，但你不應該將此與對任何其他技術的預先存在的知識混淆，甚至是一般的編程——尤其是在教程或入門材料中。
除了專門探討 Perl 與其他程式語言關係的頁面之外，文件應將重點放在 Perl 上。避免對讀者可能不熟悉的其他技術進行類比。
例如，在記錄 Perl 的內建函式之一時，請寫作就好像讀者現在第一次在任何程式語言中學習該函式一樣。
選擇將其與等效或底層 C 函式進行比較可能不會讓當代讀者理解太多。更糟的是，這可能會讓不熟悉 C 的讀者有被排除在對主題的完全理解之外的風險——更不用說完全不熟悉電腦程式設計的讀者了。
然而，如果該函式與其 C 根源的聯繫可以讓 Perl 程式設計人員在實際應用中獲得更深入的理解，你可以在其更直接有用的文件之後提到該聯繫。否則，完全省略此資訊，將其留給其他文件或更關注於檢查 Perl 底層實作細節的外部文章。
特定領域的術語有其一席之地，特別是在文件中。但是，如果手冊頁面使用了典型讀者可能還不知道的術語，那麼該頁面應盡早努力定義該術語——明確地或透過交叉參照。
例如，Perl 喜歡使用檔案代號，因此這個字會出現在其文件當中。初次接觸 Perl 說明頁的新手程式設計師很可能會不知道「檔案代號」是什麼。任何提到檔案代號的 Perl 說明頁至少應該以超連結的方式將此術語連結到 Perl 文件中的其他說明。如果適當的話，例如在 open 函數的詳細參考 的引言中，也可以包含一個非常簡短的定義，以方便讀者理解。
在快速撰寫範例時，英語程式設計師有使用簡短無意義的字詞作為變數和其他符號的佔位符的悠久傳統，例如著名的 foo、bar 和 baz。然而，在程式語言的官方永久文件中找到的範例程式碼可以而且應該透過具體性來提供更清楚的說明。
在可能的情況下，程式碼範例應為變數、類別和其他程式設計師定義的符號提供清楚說明其功能及其彼此關係的名稱。例如，如果範例需要一個類別顯示與另一個類別的「is-a」關係，請考慮將它們命名為 Apple 和 Fruit，而不是 Foo 和 Bar。類似地，建立該類別的實例的範例程式碼應將其命名為 $apple，而不是 $baz。
即使是最簡單的範例也能從使用具體字詞的清晰語言中受益。優先使用類似 for my $item (@items) { ... } 的結構，而不是 for my $blah (@blah) { ... }。
雖然這份風格指南確實指定美式英語為文件語言以求內部一致性，但作者應避免僅限英語系美國人（或任何其他特定文化或社會）理解的文化或慣用語。Perl 核心文件的語言應盡可能追求文化普遍性，即使無法做到中立。區域性用語、取材自流行文化知識的範例，以及其他類似性質的修辭技巧應盡量少用，甚至不用。
作者可以自由地在「二階」Perl 文件中使用較為隨意的語言，例如書籍、部落格文章和雜誌文章，這些文件會在其他地方發布，且目標讀者較為狹窄。但 Perl 自身的說明文件應使用盡可能淺顯易懂且歡迎廣大讀者群的語言。
佔位文字不屬於 Perl 附帶的文件中。不應在任何節標題後加上「請注意此處」、「稍後包含」或類似文字。雖然 Perl 的原始檔可能會像任何其他積極維護的技術一樣變動和修改，但每次發布的技術反覆運算都應感覺完整且自給自足，不應出現此類未來的承諾或其他未完成事項。
善用 Perl 的定期發布週期。不要在文件中塞滿承諾稍後提供更多資訊的標誌，這些標誌的存在對今天的讀者完全沒有幫助，文件的維護團隊應將任何已知的遺漏文件視為與 Perl 專案中的任何其他問題一樣需要解決的問題。讓 Perl 的貢獻者、測試人員和發布工程師滿足此需求，並抗拒插入道歉的誘惑，因為道歉在文件中與未刪除的偵錯訊息在生產程式碼中的效用相同。
不論其語氣有多平易近人，技術文件中的單一文字方塊在視覺上可能對讀者造成意志薄弱的挑戰。作者可以透過將長篇幅的文章分成小節，並加上簡短且有意義的標題，來改善這種情況。
由於 Pod 中的每個節標題都可能作為交叉參照的潛在終點（透過 Pod 的 L<...> 語法），在文件中放入大量小節可讓其他手冊頁更精確地連結到特定主題。這會建立直接連結到最合適的節，而非整個頁面，並有助於為讀者建立一個豐富、一致且相互關聯的手冊的更緊密感。
在四種文件模式中，小節更自然地屬於教學課程和說明書。食譜的分步說明或參考頁的嚴謹定義通常沒有空間容納小節。但作者可以針對需要進一步細分以求清晰度的異常複雜概念，隨時做出例外處理。
另一方面，範例程式碼可以是任何文件模式的理想補充。程式碼區塊有助於在視覺上區分手冊頁，讓讀者安心，不論文字說明有多深入，他們永遠不會離另一個實務範例太遠，而這個範例會顯示如何使用一小段經過測試的 Perl 程式碼將所有內容組合在一起。
Perl 以提供程式設計師多種方法來執行任務而聞名。如同其他任何歷久不衰的程式語言，Perl 也建立了一個龐大且由社群維護的最佳實務概念，將某些方法視為優於其他方法，通常是為了讓程式碼更易於維護。
每當文件需要顯示 Perl 提供許多途徑的技術規則時，文件應始終以最佳實務為開頭。在討論 Perl 工具組中具有許多應用程式的部分時，文件應從展示其在最常見案例中的應用開始。
例如，open 函式在 Perl 程式中有無數潛在用途，但大部分時間程式設計師（尤其是 Perl 新手）會使用此參考，因為他們只是想開啟一個檔案以進行讀取或寫入。因此，open 的文件從這裡開始，並且僅在徹底記錄並展示其在常見案例中的運作方式後，才會深入探討函式的更晦澀用途。此外，在進行此展示時，open 文件不會立即以詳細說明透過最佳實務（三個引數樣式）以外的任何途徑呼叫 open 來加重讀者的負擔。
有時，徹底性需要記錄已棄用的技術。例如，某個 Perl 函數現在可能有一個備用語法，現在被認為是過時的，不再是最佳實務，但舊專案的維護者在探索舊程式碼時可能會合理地遇到它。在這種情況下，這些功能值得記錄，但要清楚說明現代 Perl 避免這種結構，並且不建議在新的專案中使用它們。
另一種看待此哲學的方法（以及一種從 Python 文件小組的夥伴那裡借來的方法）涉及在同情對 Perl 一無所知的程式設計師的同時進行寫作，他們可能對學習一個複雜的概念感到不確定。透過以清晰、正面的範例引導該概念的主要文件，我們可以立即讓這些讀者了解它在 Perl 中如何運作的簡單且真實的畫面，並提升他們自己開始使用此新知識的信心。當然，我們應該在合理需要時納入備用路線和勸告，但我們不必強調它們。相信讀者能快速理解基礎知識，並在有動力時繼續閱讀以獲得更深入的理解。
Perl 的文件應持續專注於 Perl 的現在行為，並對未來的方向點頭。
當某些 Perl 功能改變其行為時，關於該功能的文件也應該改變，而且同樣明確。文件沒有義務保留過去行為的描述，即使附加「在 5.10 版之前，[...]」等條款也是如此。
由於 Perl 的核心文件是 Perl 原始碼發行的一部分，因此它享有與 Perl 本身原始碼相同的版本控制和版本管理的優點。善用這一點，並在需要時大膽更新文字。即使你從當前版本的文件中刪除或取代過時的資訊，Perl 的歷史仍會保持安全。
Perl 的文件在有需要時可以承認或討論以前的行為，包括註明某些功能在特定版本號中出現在語言中的備註。作者應考慮套用類似於已棄用技術的原則，如上所述：提供資訊，但不要突出顯示。
否則，讓過去留在過去。一本沒有過時說明的簡潔手冊會更簡潔且更相關。
標記為「實驗性」的 Perl 功能（在未呼叫 experimental 實用指令的程式碼中使用時會產生警告）值得文件化，但僅限於特定情況，即使如此也應附帶警告。這些功能代表 Perl 可能的新方向，但它們的介面不穩定，未來存在不確定性。
文件應逐字說明「實驗性」的兩個含義。它不應阻止程式設計師在可能承擔其內在不穩定性的專案中嘗試新功能；這種實驗有助於 Perl 成長和改進。同樣地，文件應淡化這些功能在其他幾乎所有情況下的使用。
入門或概觀材料應完全省略對實驗性功能的說明。
更詳盡的參考材料或說明文章可以包含實驗性功能，但需要清楚標示為實驗性功能，並且不要像 Perl 的穩定功能一樣突出顯示它們。使用不穩定的功能很少與最佳實務相符，而優先採用最佳實務的文件應反映這一點。
儘管它來自許多人手和思維，並貫穿 Perl 生命週期的許多歲月，但該語言的文件應以單一一致的聲音發言。除了少數例外，文件應避免明確的第一人稱單數陳述，或類似於任何個別貢獻者的哲學或經驗的自我參照。
Perl 最初是由一位個人以極為個人的方式表達而誕生，這也廣為人知地延續到其文件的第一版修訂中。如今，Perl 社群了解到，這門語言的持續發展和支援來自許多共同合作的人，而非任何個人的願景或努力。其文件不應假裝否認這一點。
然而，文件應承襲 Larry Wall 在這門語言的早期所樹立的最佳傳統：以經濟且謙虛、微妙的機智寫作，寫出一本結合簡潔與友善可親的技術手冊。它避免了技術文件可能有的枯燥，但也不會過度依賴明顯的喜劇效果，以致於分散注意力，讓人對手邊的技術主題感到困惑。
如同最棒的書面作品，Perl 的文件是有靈魂的。作為讀者，熟悉它以內化其聲音，然後找到自己的方式在自己的貢獻中表達它。同時，清楚、簡潔地寫作，並了解受眾的期望，將能讓您完成大部分工作。
文件中每一行——無論是英文句子或 Perl 陳述——都應以傳達理解給讀者為目的。如果一個句子主要是為了開一個諷刺的玩笑，而無法增進讀者對 Perl 的了解，請將其擱置一旁，並考慮將其改寫成個人部落格文章或其他文章。
以輕鬆的心情和吝嗇的手寫作。
如上所述，本指南「繼承」了《芝加哥手冊風格》第 17 版中列出的所有首選術語，並增加了以下對 Perl 文件特別有用的術語。
非「內建」。
請參閱 macOS。
請使用此術語來表示 Apple 的作業系統，而非「Mac OS X」或其變體。
此術語也比「Darwin」更佳，除非需要特別指 macOS 的 Unix 層。
Unix 風格文件的一個單位。非「手冊頁」。比「手冊頁」更佳。
此程式語言的名稱是 Perl，開頭為大寫「P」，其餘為小寫。（絕非「PERL」。）
用於讀取和執行 Perl 程式碼的直譯器程式稱為「perl」，為小寫且為等寬字體（與其他命令名稱相同）。
通常，除非您特別撰寫關於命令列 perl 程式（例如 perlrun 所做的），否則請改用「Perl」。
文件不需要在 Perl 名稱後加上「5」或任何其他數字，除非在討論 Perl 的歷史、未來計畫或主要 Perl 版本之間的明確比較時。
在 2019 年之前，有時需要指定「Perl 5」以將此語言與 Perl 6 區分開來。隨著後者更名為「Raku」，此做法已不再必要。
請參閱 Raku。
負責 Perl 持續維護和開發的團隊全名為「Perl 5 Porters」，此綽號應在任何文件中的首次提及中寫出來。此後，可以稱呼該團隊為「porters」或「p5p」。
非「Perl5 Porters」。
由可執行 Perl 程式碼組成的獨立作品最通用的描述符。與「指令碼」同義，且較為優先使用。
Perl 的「姊妹語言」，其首頁為 https://raku.org。
以前稱為「Perl 6」。2019 年，其設計團隊將此語言重新命名，以更能反映其作為獨立於 Perl 專案的身分。因此，Perl 的文件應始終將此語言稱為「Raku」，而非「Perl 6」。
請參閱 程式。
Perl 程式碼中經常被忽略的標點符號。非「分號」。
非「UNIX」、「*nix」或「Un*x」。適用於 1970 年代的原始作業系統及其所有概念上的後代。在提到類 Unix 作業系統時，您可以簡單地寫「Unix」，而不用寫「類 Unix 作業系統」。
本指南最初由 Jason McIntosh (jmac@jmac.org) 起草，並獲得 Perl 基金會的補助金。