pod2text - 將 POD 資料轉換為格式化的 ASCII 文字
pod2text [-aclostu] [--code] [-e 編碼] [--errors=樣式] [--guesswork=規則[,規則...]] [-i 縮排] [-q 引號] [--nourls] [--stderr] [-w 寬度] [輸入 [輸出 ...]]
pod2text -h
pod2text 是 Pod::Text 及其子類別的包裝指令碼。它使用它們從 POD 來源產生格式化的文字。它可以選擇使用術語上限序列或 ANSI 顏色跳脫序列來格式化文字。
input 是要讀取 POD 來源的檔案 (POD 可以嵌入在程式碼中)。如果沒有提供 input，它會預設為 STDIN。如果提供了 output，它是要寫入格式化輸出的檔案。如果沒有提供 output，格式化輸出會寫入 STDOUT。可以在相同的 pod2text 呼叫中處理多個 POD 檔案 (節省模組載入和編譯時間)，方法是在命令列上提供多對 input 和 output 檔案。
預設情況下，輸出編碼與輸入檔案的編碼相同，或者如果未設定該編碼，則為 UTF-8 (EBCDIC 系統除外)。請參閱 -e 選項以明確設定輸出編碼，並參閱 Pod::Text 中的「編碼」 以了解更多說明。
每個選項都註解了 podlators 中新增該選項的版本，以及其目前的意義。
[1.00] 使用替代輸出格式，其中包括使用不同的標題樣式，並在左邊空白處用冒號標記 =item 條目。
[1.11] 在輸出中包含輸入檔案中的任何非 POD 文字。這對於檢視使用 POD 塊的文件化程式碼很有用，其中 POD 已呈現，而程式碼保持不變。
[1.00] 使用 ANSI 顏色跳脫序列格式化輸出。使用此選項需要在您的系統上安裝 Term::ANSIColor。
[5.00] 指定輸出的編碼。編碼必須是 Encode 模組識別的編碼（請參閱 Encode::Supported）。如果輸出包含無法在此編碼中表示的字元，則會產生錯誤，並會根據 errors 選項設定進行報告。如果錯誤處理不為 die，則無法表示的字元將會以 Encode 替換字元（通常為 ?）取代。
警告：POD 來源的輸入編碼與輸出編碼無關，設定此選項不會影響 POD 輸入的詮釋。除非您的 POD 來源為 US-ASCII，否則應在來源中盡可能靠近檔案頂端使用 =encoding 指令宣告其編碼。如果未執行此動作，Pod::Simple 將嘗試猜測編碼，如果編碼為 Latin-1 或 UTF-8，則可能會成功，但會產生警告。如需更多資訊，請參閱 perlpod(1)。
[2.5.0] 設定錯誤處理樣式。die 表示在任何 POD 格式化錯誤時擲回例外。stderr 表示在標準錯誤中報告錯誤，但不要擲回例外。pod 表示在產生的文件摘要中包含 POD ERRORS 區段，總結錯誤。none 盡可能完全忽略 POD 錯誤。
預設為 die。
[5.01] 預設情況下，pod2text 會套用一些基於猜測和正規表示式的預設格式化規則，目的是讓撰寫 Perl 文件更容易，而且需要較少的明確標記。這些規則可能並不總是適當，特別是對於與 Perl 無關的文件。此選項允許關閉全部或部分規則。
特殊規則 all 會啟用所有猜測。這也是出於向後相容性的原因而設定的預設值。特殊規則 none 會停用所有猜測。否則，此選項的值應為下列一個或多個關鍵字的逗號分隔清單
如果未啟用任何猜測，則任何括在 C<> 中的文字在 nroff（終端機）輸出中會加上雙引號，除非內容已經有引號。當啟用此猜測時，引號也會從 Perl 變數、函式名稱、函式呼叫、數字和十六進位常數中移除。
任何未知的猜測名稱會被靜默略過（為了潛在的未來相容性），因此請小心拼寫。
[1.00] 設定縮排一般文字的空格數，以及 =over 區塊的預設縮排。如果未提供此選項，預設為 4 個空格。
[1.00] 列印使用資訊並結束。
[1.00] 在 =head1 標題後列印空白行。一般來說，=head1 後不會列印空白行，但 =head2 後仍會列印，因為這是手冊頁預期的格式；如果您要格式化任意文字文件，建議使用此選項。
[1.24] 左邊距的寬度（以空格為單位）。預設為 0。這是所有文字的邊距，包括標題，而不是縮排一般文字的量；對於後者，請參閱 -i 選項。
[2.5.0] 一般而言，L<> 格式化代碼會使用一個 URL 但錨定文字會格式化為顯示錨定文字和 URL。換句話說
L<foo|http://example.com/>會格式化為
foo <http://example.com/>如果給定此標誌，則在給定錨定文字時會隱藏 URL，因此此範例會格式化為僅顯示 foo。在 URL 不特別重要的情況下，這可以產生較不雜亂的輸出。
[1.06] 使用刪除線列印格式化輸出。粗體文字會呈現為字元、退格鍵、字元。斜體字和檔案名稱會呈現為底線、退格鍵、字元。許多分頁器（例如 less）知道如何將其轉換為粗體或底線文字。
[4.00] 設定用於圍繞 C<> 文字的引號為 quotes。如果 quotes 是單一字元，則會用於左引號和右引號。否則，會將其一分為二，字串的前半段用於左引號，後半段用於右引號。
quotes 也可以設定為特殊值 none，這樣就不會在 C<> 文字周圍加上引號。
[1.00] 假設每個句子都以兩個空格結束，並嘗試保留該間距。沒有這個選項，非逐字段落中所有連續的空白都會壓縮成一個空格。
[2.1.3] 預設情況下，如果在 POD 輸入中偵測到任何錯誤，pod2text 會終止。如果給定 --stderr 且沒有 --errors 標誌，錯誤會傳送至標準錯誤，但 pod2text 不會中止。這等同於 --errors=stderr，並支援向後相容性。使用此選項，pod2text 的輸出將包含您目前終端機類型的終端機控制序列。
[1.00] 嘗試從 termcap 中判斷螢幕寬度以及終端機的粗體和底線序列，並在格式化輸出時使用該資訊。輸出會換行，比您的終端機裝置寬度少兩欄。使用此選項需要您的系統在 Term::Cap 可以找到的地方有一個 termcap 檔案，並且需要您的系統支援 termios。使用此選項，pod2text 的輸出將包含您目前終端機類型的終端機控制序列。
[2.2.0] 將輸出編碼設定為 UTF-8。這等於 --encoding=UTF-8，並支援向後相容性。
[1.00] 在右側換行文字的欄位。預設為 76，除非給定 -t，否則它比終端裝置的寬度少兩欄。
只要所有處理的文件都產生一些輸出，即使輸出包含錯誤（使用 --errors=pod 產生的 POD ERRORS 區段），pod2text 都會以狀態 0 退出。如果任何正在處理的文件沒有產生輸出文件，pod2text 都會以狀態 1 退出。如果正在處理的 POD 文件有語法錯誤，而且錯誤處理樣式設定為預設的 die，pod2text 會立即中止，並以退出狀態 255 退出。
如果 pod2text 因錯誤而失敗，請參閱 Pod::Text 和 Pod::Simple，以取得這些錯誤可能代表的意義的資訊。在內部，它也可以產生下列診斷
(F) 給定了 -c 或 --color，但無法載入 Term::ANSIColor。
(F) 給定了未知的命令列選項。
此外，其他 Getopt::Long 錯誤訊息可能是由無效的命令列選項所造成的。
如果指定 -t，pod2text 會從這個環境變數取得目前螢幕寬度（如果可用）。它會覆寫 TERMCAP 中的終端機寬度資訊。
如果指定 -t，pod2text 會使用這個環境變數的內容（如果可用）來決定目前終端機裝置的正確格式化順序。
Russ Allbery <rra@cpan.org>。
Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery <rra@cpan.org>
此程式為自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它。
Encode::Supported、Pod::Text、Pod::Text::Color、Pod::Text::Overstrike、Pod::Text::Termcap、Pod::Simple、perlpod(1)
此腳本的目前版本隨時可以在其網站 https://www.eyrie.org/~eagle/software/podlators/ 取得。它也是 Perl 核心套件的一部分，從 5.6.0 版開始。