Pod::Text - 將 POD 資料轉換為格式化文字
use Pod::Text;
my $parser = Pod::Text->new (sentence => 1, width => 78);
# Read POD from STDIN and write to STDOUT.
$parser->parse_from_filehandle;
# Read POD from file.pod and write to file.txt.
$parser->parse_from_file ('file.pod', 'file.txt');Pod::Text 是個模組，可以將 POD 格式（用來撰寫 Perl 文件的建議語言）的文件轉換為格式化文字。它不使用任何特殊的格式化控制或程式碼，因此其輸出幾乎適用於任何裝置。
Pod::Text 使用下列邏輯選擇輸出編碼，依序為
如果輸出檔案控制代碼設定 PerlIO 編碼層，則不執行任何輸出編碼，而會依賴 PerlIO 編碼層。
如果設定 encoding 或 utf8 選項，則使用這些選項指定的輸出編碼。
如果 POD 來源檔案的輸入編碼已明確指定（使用 =encoding）或已由 Pod::Simple 自動偵測，則也使用該編碼作為輸出編碼。
否則，如果在非 EBCDIC 系統上執行，則使用 UTF-8 作為輸出編碼。由於這是 ASCII 的超集，因此除非 POD 輸入包含未宣告或自動偵測編碼（通常透過 E<> 跳脫）的非 ASCII 字元，否則會產生 ASCII 輸出。
否則，對於 EBCDIC 系統，輸出時不執行任何編碼，並希望這樣做有效。
一個警告：Pod::Text 必須在輸出第一個非 ASCII 字元時承諾一個輸出編碼，然後必須堅持使用該編碼以保持一致性。然而，=encoding 指令不必位於 POD 文件的開頭。如果有人在文件開頭使用跳脫來使用非 ASCII 字元，例如 E<0xEF>，然後稍後輸入 =encoding iso-8859-1，理想情況下，Pod::Text 會遵循規則 3 並將整個文件輸出為 ISO 8859-1。相反地，它會在看到該跳脫後立即遵循規則 4 承諾使用 UTF-8，然後在文件剩餘部分堅持使用該編碼。
不幸的是，沒有普遍適用的輸出編碼選項。每個選項在某些情況下都會不正確。此方法主要基於向後相容性而選用。如果呼叫者對使用者可能預期的編碼有任何了解，則應考慮透過 encoding 強制執行輸出編碼。
特別是，如果可用，請考慮匯入 Encode::Locale 模組，並將 encoding 設定為 locale 以使用適於使用者語言環境的輸出編碼。但請注意，如果使用者未採用語言環境或採用 C 語言環境，Encode::Locale 會將輸出編碼設定為 US-ASCII。這將導致所有非 ASCII 字元都換成 ? 並產生大量關於不支援字元的警告，這可能不是您想要的。
建立一個新的 Pod::Text 物件。ARGS 應為一組鍵值對，其中鍵選自以下選項。每個選項都註明 Pod::Text 中新增該選項的版本及其目前的意義。
[2.00] 如果設定為 true 值，則選取備用輸出格式，其中包括使用不同的標題樣式，並在左邊空白處使用冒號標記 =item 項目。預設為 false。
[2.13] 如果設定為 true 值，輸入檔案中非 POD 部分將會包含在輸出中。這對於檢視使用 POD 塊註解的程式碼很有用，POD 已轉譯，而程式碼保持完整。
[5.00] 指定輸出的編碼。值必須是 編碼 模組識別的編碼 (請參閱 編碼::支援)。如果輸出包含無法用此編碼表示的字元，這是一個錯誤，將會依據 errors 選項設定進行報告。如果錯誤處理不是 die，無法表示的字元將會以編碼替換字元取代 (通常是 ?)。
如果輸出檔案控制代碼設定了 PerlIO 編碼層，此參數將會被忽略，Pod::Man 將不會進行任何編碼。它將會依賴編碼層進行任何所需的輸出編碼轉換。
警告：POD 來源的輸入編碼與輸出編碼無關，設定此選項不會影響 POD 輸入的詮釋。除非您的 POD 來源是 US-ASCII，否則應該在來源中使用 =encoding 指令宣告其編碼，並儘可能接近檔案頂端。如果沒有這麼做，Pod::Simple 將會嘗試猜測編碼，如果編碼是 Latin-1 或 UTF-8，它可能會成功，但會產生警告。請參閱 perlpod(1) 以取得更多資訊。
[3.17] 如何報告錯誤。die 表示在任何 POD 格式錯誤時擲回例外。stderr 表示在標準錯誤中報告錯誤，但不要擲回例外。pod 表示在產生的文件摘要中包含一個 POD ERRORS 區段，總結錯誤。none 盡可能完全忽略 POD 錯誤。
預設值是 pod。
[5.01] 預設情況下，Pod::Text 根據猜測和正規表示式套用一些預設格式化規則，這些規則旨在讓撰寫 Perl 文件更容易，並減少明確標記的需求。這些規則可能並不總是適當，特別是對於不是關於 Perl 的文件。此選項允許關閉全部或部分規則。
特殊值 all 啟用所有猜測。這也是基於向後相容性考量而設定的預設值。特殊值 none 停用所有猜測。否則，此選項的值應該是下列一個或多個關鍵字以逗號分隔的清單
如果未啟用任何猜測，任何以 C<> 括起來的文字，除非內容本身已加上引號，否則在 nroff（終端機）輸出中會加上雙引號。當啟用此猜測時，Perl 變數、函式名稱、函式呼叫、數字和十六進位常數的引號也會被抑制。
任何未知的猜測名稱都會被靜默略過（為了潛在的未來相容性），因此請小心拼寫。
[2.00] 縮排一般文字的空格數，以及 =over 區塊的預設縮排。預設為 4。
[2.00] 如果設定為 true 值，則會在 =head1 標題後列印空白行。如果設定為 false（預設），則不會在 =head1 後列印空白行，但仍會在 =head2 後列印空白行。這是預設值，因為它是手冊頁預期的格式；如果您正在格式化任意文字文件，將此設定為 true 可能會產生更令人滿意的輸出。
[2.21] 左邊界寬度，以空格為單位。預設為 0。這是所有文字的邊界，包括標題，而不是一般文字縮排的量；後者請參閱 indent 選項。若要設定右邊界，請參閱 width 選項。
[3.17] 通常，具有網址但有錨定文字的 L<> 格式化代碼會格式化為同時顯示錨定文字和網址。換句話說
L<foo|http://example.com/>會格式化為
foo <http://example.com/>如果將此選項設定為 true 值，則會在提供錨定文字時抑制網址，因此此範例將僅格式化為 foo。在網址不特別重要的情況下，這可以產生較不雜亂的輸出。
[4.00] 設定用於包圍 C<> 文字的引號。如果值為單一字元，則用於左右引號。否則，將其拆分為一半，字串的前半段用於左引號，後半段用於右引號。
也可以設定為特殊值 none，這樣就不會在 C<> 文字周圍加上引號。
[3.00] 如果設定為 true 值，Pod::Text 將假設每個句子以兩個空格結尾，並會嘗試保留該間距。如果設定為 false，非逐字段落中所有連續的空白會壓縮成一個空格。預設為 false。
[3.10] 將有關無效 POD 的錯誤訊息傳送至標準錯誤，而不是將 POD ERRORS 區段附加到產生的輸出。如果尚未設定 errors，這等於將 errors 設定為 stderr。支援此功能以維持向後相容性。
[3.12] 如果將此選項設定為 true 值，輸出編碼會設定為 UTF-8。如果尚未設定 encoding，這等於將 encoding 設定為 UTF-8。支援此功能以維持向後相容性。
[2.00] 右側換行文字的欄位。預設為 76。
作為 Pod::Simple 的衍生類別，Pod::Text 支援相同的方法和介面。有關所有詳細資訊，請參閱 Pod::Simple。本節摘要最常使用的方法和 Pod::Text 新增的方法。
將 parse_file()、parse_lines() 或 parse_string_document() 的輸出導向檔案處理常式 FH，而不是 STDOUT。
將 parse_file()、parse_lines() 或 parse_string_document() 的輸出導向由 REF 指向的純量變數，而不是 STDOUT。例如
my $man = Pod::Man->new();
my $output;
$man->output_string(\$output);
$man->parse_file('/some/input/file');請注意，該變數中的輸出已經編碼（請參閱 "編碼"）。
從 PATH 讀取 POD 來源並格式化。預設情況下，輸出會傳送至 STDOUT，但這可以使用 output_fh() 或 output_string() 方法變更。
從 INPUT 讀取 POD 來源，格式化，並將結果輸出至 OUTPUT。
parse_from_filehandle() 提供，以符合 Pod::Man 舊版本的向後相容性。應該改用 parse_from_file()。
將提供的行解析為 POD 來源，將輸出寫入 STDOUT 或使用 output_fh() 或 output_string() 方法設定的檔案處理。這個方法可以重複呼叫以提供更多輸入行。應該傳遞明確的 undef 以指出輸入結束。
這個方法預期原始位元組，而非已解碼字元。
將提供的純量變數解析為 POD 來源，將輸出寫入 STDOUT 或使用 output_fh() 或 output_string() 方法設定的檔案處理。
這個方法預期原始位元組，而非已解碼字元。
Pod::Text 匯出一個函式，以符合舊版本的向後相容性。這個函式已棄用；改用上面說明的物件導向介面。
將 INPUT 的 POD 來源轉換為文字，並寫入 OUTPUT。如果未提供 OUTPUT，預設為 STDOUT。INPUT 可以是任何表達式，支援作為 two-argument open() 的第二個引數。
如果 -a 作為初始引數提供，請將 alt 選項傳遞至 Pod::Text 建構函式。這會啟用另類格式化。
如果 -NNN 作為初始引數提供，請將 width 選項傳遞至 Pod::Text 建構函式，並將數字 NNN 作為其引數。這會將換行寬度設定為 NNN。
(W) 內部 =item 處理中發生錯誤。這些訊息表示 Pod::Text 中的錯誤；您永遠不應看到它們。
(F) Pod::Text 是透過相容性模式 pod2text() 介面呼叫的，且無法開啟給予它的輸入檔案。
(F) 建構函式的 errors 參數設定為未知值。
(F) 給定的引號規格（建構函式的 quotes 選項）無效。引號規格必須為一個字元長，或偶數（大於一）個字元長。
(F) 正在格式化的 POD 文件有語法錯誤，且 errors 選項設定為 die。
Pod::Text 2.03（基於 Pod::Parser）是此模組在 Perl 5.6.0 中包含在 Perl 中的第一個版本。較早版本的 Perl 有不同的 Pod::Text 模組，其 API 不同。
基於 Pod::Simple 的目前 API 是在 Pod::Text 3.00 中新增的。Pod::Text 3.01 包含在 Perl 5.9.3 中，這是第一個包含這些變更的 Perl 版本。這是第一個正確支援所有現代 POD 語法的版本。parse_from_filehandle() 方法已在 Pod::Text 3.07 中重新新增，以維持向後相容性，並包含在 Perl 5.9.4 中。
包含在 Perl 5.10.1 中的 Pod::Text 3.12 首先實作了目前嘗試將預設輸出編碼與 POD 來源的輸入編碼配對的做法，除非被 utf8 選項或（稍後新增的）encoding 選項覆寫。
在 Pod::Text 3.14 中新增了對 URL 類型的 L<> 連結中錨定文字的支援，並包含在 Perl 5.11.5 中。
包含在 Perl 5.19.5 中的 Pod::Text 3.18 中，parse_lines()、parse_string_document() 和 parse_file() 設定了預設輸出檔案處理為 STDOUT，如果尚未設定。
包含在 Perl 5.23.7 中的 Pod::Text 4.00 將模組版本與 podlators 發行版的版本對齊。從此點開始，包含在 podlators 中的所有模組，以及 podlators 發行版本身，都共用相同的版本號碼。
包含在 Perl 5.25.7 中的 Pod::Text 4.09 修復了 EBCDIC 系統中的一個嚴重錯誤，此錯誤存在於從 3.00 回溯的所有版本中，會導致開啟括號消失。
Pod::Text 5.00 現在預設於非 EBCDIC 系統中，如果在輸入中看到非 ASCII 字元且未指定輸入編碼，則預設為 UTF-8 編碼。它也會在第一個非 ASCII 字元時提交編碼，且如果輸入編碼變更，則不會變更輸出編碼。Encode 模組現在用於所有輸出編碼，而非 PerlIO 層，這修正了先前輸出至純量時的問題。
Russ Allbery <rra@cpan.org>，根據 Tom Christiansen <tchrist@mox.perl.com> 的原始 Pod::Text 以及 Brad Appleton <bradapp@enteract.com> 將其轉換為 Pod::Parser 的基礎。
Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022 Russ Allbery <rra@cpan.org>
此程式為自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它。
Encode::Locale, Encode::Supproted, Pod::Simple, Pod::Text::Termcap, perlpod(1), pod2text(1)
此模組的目前版本隨時可在其網站取得，網址為 https://www.eyrie.org/~eagle/software/podlators/。它也是 Perl 5.6.0 之後的 Perl 核心套件的一部分。