pod2man - 將 POD 資料轉換為格式化的 *roff 輸入
pod2man [--center=字串] [--date=字串] [--encoding=編碼] [--errors=樣式] [--fixed=字型] [--fixedbold=字型] [--fixeditalic=字型] [--fixedbolditalic=字型] [--guesswork=規則[,規則...]] [--name=名稱] [--nourls] [--official] [--release=版本] [--section=manext] [--quotes=引號] [--lquote=引號] [--rquote=引號] [--stderr] [--utf8] [--verbose] [輸入 [輸出] ...]
pod2man --help
pod2man 是 Pod::Man 模組的包裝指令碼，使用它從 POD 來源產生 *roff 輸入。產生的 *roff 程式碼適合使用 nroff(1) 在終端機上顯示，通常透過 man(1)，或使用 troff(1) 列印。
預設情況下（在非 EBCDIC 系統上），pod2man 會輸出 UTF-8 手冊頁面。其輸出應可在使用 groff（大多數 Linux 發行版）或 mandoc（大多數 BSD 變體）的系統上的 man 程式運作，但可能在較舊的 UNIX 系統上導致輸出混亂。若要在這些系統上選擇不同的、可能更向後相容的輸出混亂，請使用 --encoding=roff（Pod::Man 較早版本中的預設值）。請參閱 --encoding 選項和 "ENCODING" in Pod::Man 以取得更多詳細資訊。
輸入是供 POD 來源閱讀的檔案（POD 可內嵌於程式碼中）。如果未提供輸入，則預設為 STDIN。如果提供了輸出，則為寫入格式化輸出的檔案。如果未提供輸出，則格式化輸出會寫入 STDOUT。在同一個 pod2man 呼叫中，可透過在命令列提供多組輸入和輸出檔案，來處理多個 POD 檔案（節省模組載入和編譯時間）。
--section、--release、--center、--date 和 --official 可用於設定要使用的標頭和頁尾。如果未提供，Pod::Man 將假設各種預設值。詳情請見下方說明。
每個選項都附註了 podlators 加入該選項並賦予其目前意義的版本。
[1.00] 將 .TH 巨集的置中頁面標題設定為字串。預設為 使用者貢獻的 Perl 文件，但另請參閱下方的 --official。
[4.00] 將 .TH 巨集的左邊頁尾字串設定為字串。預設會使用 POD_MAN_DATE、SOURCE_DATE_EPOCH、輸入檔案的修改日期或目前日期（如果輸入來自 STDIN）中的第一個，且日期會使用 UTC。有關更多詳細資料，請參閱 Pod::Man 中的「CLASS METHODS」。
[5.00] 指定輸出的編碼。編碼必須是 Encode 模組識別的編碼（請參閱 Encode::Supported）。非 EBCDIC 系統的預設值為 UTF-8。
如果輸出包含無法用此編碼表示的字元，則會產生錯誤，且會根據 --errors 選項的設定報告錯誤。如果錯誤處理方式不是 die，則無法表示的字元會以 Encode 替換字元（通常為 ?）取代。
如果 encoding 選項設定為特殊值 groff（EBCDIC 系統上的預設值），或如果 Encode 模組不可用，且編碼設定為任何值（除了 roff，請參閱下方），Pod::Man 將會把所有非 ASCII 字元轉換為 \[uNNNN] Unicode 逸出字元。這些逸出字元傳統上並非 *roff 語言的一部分，但受到 groff 和 mandoc 支援，因此也受到現今大多數手冊頁面處理器支援。
如果 encoding 設定為特殊值 roff，pod2man 會執行其歷史轉換，將（部分）ISO 8859-1 字元轉換為 *roff 逸出字元，這些逸出字元可能足夠用於 troff，且可能在 nroff 中可讀（儘管醜陋）。這是 5.00 之前的 pod2man 版本的預設行為。使用此編碼時，所有其他非 ASCII 字元都將會被替換為 X。這可能是針對非常舊的 troff 和 nroff 實作所需要的，這些實作不支援 UTF-8，但它對任何非 ASCII 字元的表示都很差，而且通常特定於歐洲語言。不建議使用。
警告：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。
[1.0] 用於逐字文字和程式碼的固定寬度字型。預設為 CW。某些系統可能想要使用 CR。僅適用於 troff 輸出。
[1.0] 固定寬度字型的粗體版本。預設為 CB。僅適用於 troff 輸出。
[1.0] 固定寬度字型的斜體版本（有點名不符實，因為大多數固定寬度字型只有傾斜版本，沒有斜體版本）。預設為 CI。僅適用於 troff 輸出。
[1.0] 固定寬度字型的粗斜體（理論上，實際上可能是傾斜）版本。Pod::Man 沒有假設您有這個字型，並預設為 CB。某些系統（例如 Solaris）將此字型設為 CX。僅適用於 troff 輸出。
[5.00] 預設情況下，pod2man 會根據猜測和正規表示式套用一些預設格式化規則，這些規則旨在讓撰寫 Perl 文件更容易，且需要較少的明確標記。這些規則可能並不總是適當，特別是對於與 Perl 無關的文件。這個選項允許關閉全部或部分規則。
特殊規則 all 會啟用所有猜測。基於向後相容性的原因，這也是預設值。特殊規則 none 會停用所有猜測。否則，這個選項的值應為下列一個或多個關鍵字以逗號分隔的清單
將函式參考（例如 foo()）轉換為粗體，即使它們沒有標記。函式名稱接受函式名稱的有效 Perl 字元（包括 :），且尾隨的括弧必須存在且為空。
將手冊頁參考（例如 foo(1)）的第一部分（括弧前）轉換為粗體，即使它們沒有標記。章節必須是單一數字，後接小寫字母（可選）。
如果未啟用任何猜測，則任何包含在 C<> 中的文字都會在 nroff（終端機）輸出中加上雙引號，除非內容已經有引號。當啟用這個猜測時，Perl 變數、函式名稱、函式呼叫、數字和十六進位常數的引號也會被抑制。
將 Perl 變數名稱轉換為等寬字型，即使它們沒有標記。這個轉換只會在 troff 輸出或其他支援等寬字型的輸出格式（與 nroff 終端機輸出不同）中顯現。
任何未知的猜測名稱都會被靜默忽略（為了潛在的未來相容性），因此請小心拼寫。
[1.00] 列印使用資訊。
[1.00] 不再使用。pod2man 過去會檢查其輸入作為手冊頁的有效性，但現在應該改由 podchecker(1) 來執行。接受向後相容性；這個選項不再執行任何動作。
[5.00] 加入指令，告訴 groff 輸入檔案使用指定的語言。此設定的值必須是語言縮寫，而 groff 提供補充設定，例如 ja（日文）或 zh（中文）。
這會加入
.mso <language>.tmac
.hla <language>到檔案開頭，為指定的語言設定正確的換行。沒有這些指令，如果手冊頁面安裝到一般手冊頁面目錄（例如 /usr/share/man），groff 可能不知道如何為中文和日文文字加入適當的換行。
在許多系統中，如果手冊頁面安裝到特定語言的手冊頁面目錄（例如 /usr/share/man/zh_CN），系統會自動執行此動作。在這種情況下，不需要此選項。
很不幸地，使用此選項加入的指令是特定於 groff，無法與其他 troff 和 nroff 實作搭配使用。
[4.08] 設定用於包圍 C<> 文字的引號。--lquote 設定左引號，--rquote 設定右引號。兩者都可以設定為特殊值 none，這樣就不會在 C<> 文字的該側加入引號（但字型仍然會變更為 troff 輸出）。
另請參閱 --quotes 選項，可用於同時設定兩個引號。如果 --quotes 和其他選項之一都設定，--lquote 或 --rquote 會覆寫 --quotes。
[4.08] 將手冊頁面的名稱設定為 .TH 巨集的 name。沒有此選項，手冊名稱會設定為轉換檔案的基本名稱大寫，除非手冊章節為 3，這樣會解析路徑，查看是否為 Perl 模組路徑。如果是，類似 .../lib/Pod/Man.pm 的路徑會轉換為類似 Pod::Man 的名稱。如果提供此選項，會覆寫名稱的任何自動判定。
雖然不必遵循此慣例，但請注意 UNIX 手冊頁面的慣例是標題全部使用大寫，即使命令不是這樣。（不過，Perl 模組傳統上會對手冊頁面標題使用混合大小寫。）
這個選項在一次轉換多個 POD 檔案時可能沒有用。
從標準輸入轉換 POD 來源時，如果未提供此選項，名稱將設定為 STDIN。強烈建議提供此選項以設定有意義的手冊頁面名稱。
[2.5.0] 通常，具有 URL 但有錨點文字的 L<> 格式化代碼會格式化為同時顯示錨點文字和 URL。換句話說
L<foo|http://example.com/>會格式化為
foo <http://example.com/>如果給定此標誌，則會在給定錨點文字時抑制 URL，因此此範例將僅格式化為 foo。在 URL 不特別重要的情況下，這樣可以產生較不混亂的輸出。
[1.00] 如果未同時給定 --center，則設定預設標頭以表示此頁面是標準 Perl 發行版本的一部分。
[4.00] 設定用於包圍 C<> 文字的引號為 quotes。如果 quotes 是單一字元，則它用作左引號和右引號。否則，它會被分成兩半，字串的前半部分用作左引號，後半部分用作右引號。
quotes 也可能設定為特殊值 none，在這種情況下，不會在 C<> 文字周圍加上引號（但字型仍會變更為 troff 輸出）。
另請參閱 --lquote 和 --rquote 選項，可用於獨立設定左引號和右引號。如果同時設定 --quotes 和其他選項之一，則 --lquote 或 --rquote 會覆寫 --quotes。
[1.00] 將 .TH 巨集的置中頁尾設定為 version。預設情況下，這會設定為您在 pod2man 下執行的 Perl 版本。將其設定為空字串會導致部分 *roff 實作使用系統預設值。
請注意，某些系統 an 巨集設定會假設置中的頁尾會是修改日期，並會加上類似 上次修改： 的字串。如果這是目標系統的情況，您可能想要將 --release 設定為上次修改日期，並將 --date 設定為版本號碼。
[1.00] 設定 .TH 巨集的區段。標準區段編號慣例是將 1 用於使用者指令，2 用於系統呼叫，3 用於函式，4 用於裝置，5 用於檔案格式，6 用於遊戲，7 用於其他資訊，8 用於管理員指令。不過，這裡有許多變化；某些系統（例如 Solaris）將 4 用於檔案格式，5 用於其他資訊，7 用於裝置。其他系統則使用 1m 代替 8，或兩者混合使用。唯一可靠一致的區段號碼大約是 1、2 和 3。
預設情況下，將使用區段 1，除非檔案以 .pm 結尾，這種情況下將選取區段 3。
[2.1.3] 預設情況下，如果在 POD 輸入中偵測到任何錯誤，pod2man 會中斷。如果給定 --stderr 且沒有 --errors 旗標，錯誤會傳送到標準錯誤輸出，但 pod2man 不會中止。這等於 --errors=stderr，並支援向後相容性。
[2.1.0] 這個選項用於告訴 pod2man 產生 UTF-8 輸出。由於這現在是 5.00 版的預設值，因此它會被忽略且不執行任何動作。
[1.11] 在產生每個輸出檔案時列印其名稱。
只要所有處理的文件都產生一些輸出，即使該輸出包含勘誤表（使用 --errors=pod 產生的 POD ERRORS 區段），pod2man 都會結束並傳回狀態 0。如果任何處理的文件沒有產生輸出文件，pod2man 會結束並傳回狀態 1。如果在處理的 POD 文件中出現語法錯誤，且錯誤處理樣式設定為預設的 die，pod2man 會立即中止並傳回結束狀態 255。
如果 pod2man 執行失敗並出現錯誤，請參閱 Pod::Man 和 Pod::Simple，以取得有關這些錯誤可能代表的意義的資訊。
pod2man program > program.1
pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
pod2man --section=7 note.pod > note.7如果您想要連續列印大量說明頁面，您可能會想要設定 C 和 D 暫存器，以設定連續頁碼編號和奇偶頁面編號，至少在某些版本的 man(7) 中是如此。
troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...若要在 STDERR 上取得索引項目，請開啟 F 暫存器，如下所示
troff -man -rF1 perl.1索引僅透過 .tm 輸出每個主要頁面、章節、小節、項目和任何 X<> 指令的訊息。
Russ Allbery <rra@cpan.org>，根據 Larry Wall 和 Tom Christiansen 的原始 pod2man。
Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery <rra@cpan.org>
此程式是免費軟體；您可以在與 Perl 相同的條款下重新散布或修改它。
Pod::Man、Pod::Simple、man(1)、nroff(1)、perlpod(1)、podchecker(1)、perlpodstyle(1)、troff(1)、man(7)
記錄 an 巨集集的說明頁面在您的系統上可能是 man(5) 而不是 man(7)。
此指令碼的目前版本隨時可在其網站 https://www.eyrie.org/~eagle/software/podlators/ 取得。它也是 Perl 核心發行的一部分，版本為 5.6.0。