目錄

• 名稱
• 說明
  • 一般段落
  • 逐字段落
  • 指令段落
  • 格式化代碼
  • 意圖
  • 將 Pod 嵌入 Perl 模組
  • 撰寫 Pod 的提示
• 另請參閱
• 作者

#名稱

perlpod - 傳統文件格式

#說明

Pod 是一種易於使用的標記語言，用於撰寫 Perl、Perl 程式和 Perl 模組的文件。

有轉譯器可將 Pod 轉換為各種格式，例如純文字、HTML、手冊頁等。

Pod 標記包含三種類型的基本段落：一般、逐字和指令。

#一般段落

文件中大部分段落將會是像這樣的一般文字區塊。你可以直接輸入文字，不需要任何標記，只要前後各留一行空白即可。當它被格式化後，它將會經過最少的格式化，例如重新換行、可能使用等寬字體，甚至可能對齊。

你可以在一般段落中使用格式化代碼，例如 粗體、斜體、程式碼樣式、超連結 等。這些代碼在下面的「格式化代碼」章節中說明。

#逐字段落

逐字段落通常用於呈現程式碼區塊或其他不需要任何特殊解析或格式化的文字，且不應換行。

逐字段落的第一個字元為空格或 tab，即可區分出來。（通常，它的所有行都以空格和/或 tab 開頭。）它應該被原樣複製，假設 tab 位於 8 個欄位邊界上。沒有特殊的格式化代碼，所以你不能使用斜體或類似的方式。\ 表示 \，沒有其他意思。

#指令段落

指令段落用於對整段文字進行特殊處理，通常作為標題或清單的一部分。

所有指令段落（通常只有一行長）都以「=」開頭，後接一個識別碼，再接指令可以自由使用的任意文字。目前識別的指令有

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=head5 Heading Text
=head6 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

詳細說明每個指令

#=head1 標題文字

#=head2 標題文字

#=head3 標題文字

#=head4 標題文字

#=head5 標題文字

#=head6 標題文字

head1 到 head6 會產生標題，其中 head1 是最高層級。此段落中其餘文字是標題的內容。例如

=head2 Object Attributes

文字「物件屬性」組成那裡的標題。這些標題指令中的文字可以使用格式化代碼，如下所示

=head2 Possible Values for C<$/>

這些指令在下面的「格式化代碼」章節中說明。

請注意，head5 和 head6 是在 2020 年和 Pod::Simple 3.41 中引入的，於 2020 年 10 月發布，因此你使用的 Pod 解析器可能不支援它們。

#=over 縮排層級

#=item stuff...

#=back

項目、結束和返回需要更多說明："=over" 會開始一個區域，特別用於產生清單，使用 "=item" 指令，或用於縮排（群組）一般段落。在清單結束時，使用 "=back" 來結束它。=item stuff... 中的 縮排層級 選項表示要縮排多遠，通常以 ems 為單位（其中一個 em 是文件基本字型中 "M" 的寬度）或大約相當的單位；如果沒有 縮排層級 選項，它預設為四。（有些格式化程式可能會忽略您提供的任何 縮排層級。）在 =item stuff... 中的 內容 中，您可以使用格式化程式碼，如下所示

=item Using C<$|> to Control Buffering

這些指令在下面的「格式化代碼」章節中說明。

另請注意，使用 "=over" ... "=back" 區域有一些基本規則

• 請勿在 "=over" ... "=back" 區域外使用 "=item"

• 在 "=over" 指令之後的第一個項目應該是 "=item"，除非這個 "=over" ... "=back" 區域中根本沒有任何項目。

• 請勿在 "=over" ... "=back" 區域中放置 "=headn" 指令。

• 或許最重要的是，保持項目一致：對所有項目使用 "=item *" 以產生項目符號；或使用 "=item 1.", "=item 2." 等來產生編號清單；或使用 "=item foo", "=item bar" 等——也就是說，看起來不像項目符號或數字的東西。（如果您有一個清單包含：1) 看起來不像項目符號或數字的東西，加上 2) 看起來像項目符號或數字的東西，您應該在項目符號或數字狀項目之前加上 Z<>。請參閱下方的 Z<> 以取得範例。）

  如果您從項目符號或數字開始，請堅持使用它們，因為格式化程式會使用第一個 "=item" 類型來決定如何格式化清單。

#=cut

若要結束 Pod 區塊，請使用空白行，然後使用以 "=cut" 開頭的行，然後再使用空白行。這讓 Perl（和 Pod 格式化程式）知道 Perl 程式碼從這裡繼續。（在 "=cut" 之前的空白行在技術上並非必要，但許多較舊的 Pod 處理器需要它。）

#=pod

=pod 指令本身並沒有做太多事情，但它會向 Perl（和 Pod 格式化程式）發出訊號，表示 Pod 區塊從這裡開始。Pod 區塊從任何指令段落開始，因此 =pod 指令通常僅在您想要以一般段落或逐字段落開始 Pod 區塊時使用。例如

=item stuff()

This function does stuff.

=cut

sub stuff {
  ...
}

=pod

Remember to check its return value, as in:

  stuff() || die "Couldn't do stuff!";

=cut

#=begin 格式化程式名稱

#=end 格式名稱

#=for 格式名稱 文字...

For、begin 和 end 會讓您擁有文字/程式碼/資料區域，這些區域通常不會被解釋為正常的 Pod 文字，而是直接傳遞給特定格式化程式，或以其他方式特別處理。可以使用該格式的格式化程式會使用該區域，否則會完全忽略該區域。

指令 "=begin 格式名稱"、一些段落和指令 "=end 格式名稱" 表示介於其間的文字/資料是提供給理解稱為 格式名稱 的特殊格式的格式化程式。例如，

=begin html

<hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

=end html

指令 "=for 格式名稱 文字..." 指定此段落 (緊接在 格式名稱 之後開始) 的其餘部分採用該特殊格式。

=for html <hr> <img src="thang.png">
<p> This is a raw HTML paragraph </p>

這表示與上述 "=begin html" ... "=end html" 區域相同。

也就是說，使用 "=for" 時，您只能擁有段落長度的文字 (亦即 "=foo 目標名稱 文字..." 中的文字)，但使用 "=begin 目標名稱" ... "=end 目標名稱" 時，您可以擁有任意數量的介於其間的內容。(請注意，在 "=begin" 指令之後和 "=end" 指令之前仍然必須有空白行。)

以下是使用這些指令的一些範例

=begin html

<br>Figure 1.<br><IMG SRC="figure1.png"><br>

=end html

=begin text

  ---------------
  |  foo        |
  |        bar  |
  ---------------

^^^^ Figure 1. ^^^^

=end text

格式化程式目前已知接受的一些格式名稱包括 "roff"、"man"、"latex"、"tex"、"text" 和 "html"。(有些格式化程式會將其中一些視為同義詞。)

格式名稱 "comment" 通常僅用於製作筆記 (可能是給您自己)，這些筆記不會出現在 Pod 文件的任何格式化版本中

=for comment
Make sure that all the available options are documented!

有些 格式名稱 會需要一個前導冒號 (如 "=for :格式名稱" 或 "=begin :格式名稱" ... "=end :格式名稱")，以表示文字不是原始資料，而是 是 Pod 文字 (亦即，可能包含格式化程式碼)，但不是用於一般格式化 (例如，可能不是一般用途的段落，但可能是用於格式化為腳註)。

#=encoding 編碼名稱

此指令用於宣告文件的編碼。大多數使用者不需要這個；但如果您的編碼不是 US-ASCII，請在文件的最前面放置 =encoding 編碼名稱 指令，以便 pod 格式化程式知道如何解碼文件。對於 編碼名稱，請使用 Encode::Supported 模組識別的名稱。有些 pod 格式化程式可能會嘗試猜測 Latin-1 或 CP-1252 與 UTF-8 編碼之間的差異，但它們可能會猜錯。如果您使用除了嚴格的 ASCII 以外的任何東西，最好明確說明。範例

=encoding latin1

=encoding utf8

=encoding koi8-r

=encoding ShiftJIS

=encoding big5

=encoding 會影響整個文件，而且只能出現一次。

而且別忘了，所有指令除了 =encoding 會持續到其 段落 結束，而不是其行。因此在以下範例中，你可以看到每個指令都需要其後的空白行，以結束其段落。（而且一些較舊的 Pod 翻譯器可能需要 =encoding 行也有一個後續空白行，即使省略應該是合法的。）

清單的一些範例包括

=over

=item *

First item

=item *

Second item

=back

=over

=item Foo()

Description of Foo function

=item Bar()

Description of Bar function

=back

#格式化代碼

在一般段落和一些指令段落中，可以使用各種格式化代碼（又稱「內部序列」）

#I<text> -- 斜體文字

用於強調（「be I<careful!>」）和參數（「redo I<LABEL>」）

#B<text> -- 粗體文字

用於開關（「perl's B<-n> switch」）、程式（「some systems provide a B<chfn> for that」）、強調（「be B<careful!>」）等等（「and that feature is known as B<autovivification>」）。

#C<code> -- 程式碼文字

以打字機字型呈現程式碼，或給出一些其他指示，表示這代表程式碼文字（「C<gmtime($^T)>」）或其他形式的電腦語言（「C<drwxr-xr-x>」）。

#L<name> -- 超連結

有各種語法，如下所列。在給定的語法中，text、name 和 section 不能包含字元「/」和「|」；而且任何「<」或「>」都應該匹配。

• L<name>

  連結到 Perl 手冊頁面（例如，L<Net::Ping>）。請注意，name 不應包含空格。此語法偶爾也用於 Unix 手冊頁面的參考，例如 L<crontab(5)>。

• L<name/"sec"> 或 L<name/sec>

  連結到其他手冊頁面的區段。例如，L<perlsyn/"For Loops">

• L</"sec"> 或 L</sec>

  連結到此手冊頁面的區段。例如，L</"Object Methods">

區段是由命名標題或項目開始。例如，L<perlvar/$.> 或 L<perlvar/"$."> 都連結到 perlvar 中由「=item $.」開始的區段。而且 L<perlsyn/For Loops> 或 L<perlsyn/"For Loops"> 都連結到 perlsyn 中由「=head2 For Loops」開始的區段。

若要控制用於顯示的文字，請使用「L<text|...>」，例如

• L<text|name>

  將此文字連結到該手冊頁面。例如，L<Perl Error Messages|perldiag>

• L<text|name/"sec"> 或 L<text|name/sec>

  將此文字連結到該手冊頁面的該區段。例如，L<postfix "if"|perlsyn/"Statement Modifiers">

• L<text|/"sec"> 或 L<text|/sec> 或 L<text|"sec">

  將此文字連結到此手冊頁面中的該區段。例如：L<各種屬性|/"成員資料">

或者，您可以連結到網頁

• L<scheme:...>

  L<文字|scheme:...>

  連結到絕對 URL。例如，L<http://www.perl.org/> 或 L<Perl 主頁|http://www.perl.org/>。

#E<escape> -- 字元跳脫

與 HTML/XML 中的 &foo;「實體參考」非常類似

• E<lt> -- 文字 < (小於)

• E<gt> -- 文字 > (大於)

• E<verbar> -- 文字 | (直線 棒)

• E<sol> -- 文字 / (斜線)

  上述四個都是選用的，但其他格式化代碼中除外，特別是 L<...>，以及在前面有加上大寫字母時。

• E<htmlname>

  一些非數字的 HTML 實體名稱，例如 E<eacute>，其意義與 HTML 中的 é 相同，也就是帶有銳音符號 (/- 形狀) 的小寫 e。

• E<number>

  具有該數字的 ASCII/Latin-1/Unicode 字元。開頭的「0x」表示 數字 是十六進位，例如 E<0x201E>。開頭的「0」表示 數字 是八進位，例如 E<075>。否則，數字 會被解釋為十進位，例如 E<181>。

  請注意，較舊的 Pod 格式化程式可能無法辨識八進位或十六進位數字跳脫，而且許多格式化程式無法可靠地呈現超過 255 的字元。（有些格式化程式甚至必須使用折衷的呈現方式來呈現 Latin-1/CP-1252 字元，例如將 E<eacute> 僅呈現為一個純粹的「e」）

#F<filename> -- 用於檔案名稱

通常以斜體顯示。範例：「F<.cshrc>」

#S<text> -- 文字包含不換行空白

這表示 文字 中的字詞不應跨行中斷。範例：S<$x ? $y : $z>。

#X<topic name> -- 索引項目

大多數格式化程式會忽略這個，但有些可能會使用它來建立索引。它總是呈現為空字串。範例：X<將相對 URL 絕對化>

#Z<> -- 一個空值 (零效果) 格式化代碼

這很少使用。有時這是使用 E<...> 代碼的替代方法。例如，代替「NE<<>3」（代表「N<3」），您可以寫成「NZ<><3」（「Z<>」將「N」和「<」分開，因此它們不會被視為（虛構的）「N<...>」代碼的一部分）。

另一個用途是表示 =item Z<>stuff... 中的內容不應視為項目符號或數字。例如，沒有 Z<>，這一行

=item Z<>500 Server error

可能會被解析為編號清單中的項目，儘管它並非如此。

另一個用途是在 =item 行之間保持視覺間距。如果您指定

=item foo

=item bar

通常會被渲染為

foo
bar

這可能是您想要的，但如果您真正想要的是

foo

bar

您可以使用 Z<> 來實現

=item foo

Z<>

=item bar

大多數情況下，您只需要一組尖括號來界定格式化代碼的開頭和結尾。但是，有時您會希望在格式化代碼中放入一個真正的右尖括號（大於號，'>'）。在使用格式化代碼為程式碼片段提供不同字型時，這尤其常見。與 Perl 中的所有事物一樣，有多種方法可以做到這一點。一種方法是使用 E 代碼轉義結束括號

C<$a E<lt>=E<gt> $b>

這將產生：「$a <=> $b」

一種更具可讀性，也許更「簡單」的方法是使用不需要轉義單個「>」的備用分隔符號集。雙尖括號（「<<」和「>>」）可用於當且僅當在開啟分隔符號後有空白，在關閉分隔符號前有空白！例如，以下方法將奏效

C<< $a <=> $b >>

事實上，您可以使用任意數量的重複尖括號，只要在開啟分隔符號和關閉分隔符號中使用相同的數量，並確保空白緊接在開啟分隔符號的最後一個「<」之後，並緊接在關閉分隔符號的第一個「>」之前。（空白將被忽略。）因此，以下方法也將有效

C<<< $a <=> $b >>>
C<<<<  $a <=> $b     >>>>

它們都與以下內容完全相同

C<$a E<lt>=E<gt> $b>

多括號形式不影響格式化代碼內容的解釋，只影響它的結束方式。這表示上面的範例也與以下內容完全相同

C<< $a E<lt>=E<gt> $b >>

作為進一步的範例，這表示如果您想將這些程式碼片段放入 C（程式碼）樣式

open(X, ">>thing.dat") || die $!
$foo->bar();

你可以這樣做

C<<< open(X, ">>thing.dat") || die $! >>>
C<< $foo->bar(); >>

這應該比舊方法容易閱讀

C<open(X, "E<gt>E<gt>thing.dat") || die $!>
C<$foo-E<gt>bar();>

目前由 pod2text (Pod::Text)、pod2man (Pod::Man) 和任何其他使用 Pod::Parser 1.093 或更新版本，或 Pod::Tree 1.02 或更新版本的 pod2xxx 或 Pod::Xxxx 轉譯器支援。

#意圖

意圖是使用簡單，而非表達能力強大。段落看起來像段落（區塊格式），以便在視覺上突出顯示，而且我可以輕鬆地透過 fmt 執行它們以重新格式化（在我的 vi 版本中為 F7，在我的 emacs 版本中為 Esc Q）。我希望轉譯器始終以逐字模式保留 ' 和 ` 和 " 引號，這樣我就可以吸入一個工作中的程式，將它移四個空格，並讓它列印出來，嗯，逐字。而且應該是用等寬字型。

Pod 格式不一定足夠用於寫書。Pod 只是用於為 nroff、HTML、TeX 和其他標記語言提供一個防呆的共用來源，就像用於線上文件一樣。轉譯器存在於 pod2text、pod2html、pod2man（這是用於 nroff(1) 和 troff(1)）、pod2latex 和 pod2fm 中。CPAN 中有各種其他可用的轉譯器。

#將 Pod 嵌入 Perl 模組

你可以將 Pod 文件嵌入你的 Perl 模組和指令碼中。從空行開始你的文件，在開頭有一個 "=head1" 命令，並以 "=cut" 命令和空行結束。perl 可執行檔將忽略 Pod 文字。你可以將 Pod 陳述式放在 perl 預期新陳述式開始的地方，但不能放在陳述式內，因為這將導致錯誤。請參閱任何提供的函式庫模組以取得範例。

如果你要將你的 Pod 放在檔案的結尾，而且你正在使用 __END__ 或 __DATA__ 切割標記，請務必在第一個 Pod 命令之前在那裡放置一個空行。

__END__

=head1 NAME

Time::Local - efficiently compute time from local and GMT time

在 "=head1" 之前沒有那個空行，許多轉譯器將無法辨識 "=head1" 為 Pod 區塊的開頭。

#撰寫 Pod 的提示

• podchecker 命令用於檢查 Pod 語法是否有錯誤和警告。例如，它會檢查 Pod 區塊中是否完全空白行，以及未知的命令和格式化代碼。你仍然應該將你的文件傳遞給一個或多個轉譯器並校對結果，或列印結果並校對它。發現的一些問題可能是轉譯器中的錯誤，你可能希望解決或不希望解決這些問題。

• 如果您比較熟悉以 HTML 而非 Pod 編寫，您可以嘗試使用簡單的 HTML 編寫文件，並使用實驗性的 Pod::HTML2Pod 模組（可在 CPAN 中取得）將其轉換為 Pod，並檢視產生的程式碼。CPAN 中的實驗性 Pod::PXML 模組可能也有用。

• 許多較舊的 Pod 轉譯器需要在每個 Pod 指令之前和之後（包括 "=cut"！）有一行空白行。有類似以下內容

  # - - - - - - - - - - - -
  =item $firecracker->boom()
  
  This noisily detonates the firecracker object.
  =cut
  sub boom {
  ...

  ...會讓此類 Pod 轉譯器完全無法看到 Pod 區塊。

  改為像這樣

  # - - - - - - - - - - - -
  
  =item $firecracker->boom()
  
  This noisily detonates the firecracker object.
  
  =cut
  
  sub boom {
  ...

• 有些較舊的 Pod 轉譯器需要段落（包括指令段落，例如 "=head2 Functions"）以完全空白行分隔。如果您有一行明顯空白的行，上面有一些空格，這可能不會被這些轉譯器視為分隔符號，這可能會導致奇怪的格式。

• 較舊的轉譯器可能會在 L<> 連結周圍加入文字，例如 L<Foo::Bar> 可能會變成「Foo::Bar 手冊頁」。因此，如果您希望轉譯的文件可以合理閱讀，您不應該撰寫類似 the L<foo> documentation 的內容。改為撰寫 the L<Foo::Bar|Foo::Bar> documentation 或 L<the Foo::Bar documentation|Foo::Bar>，以控制連結的顯示方式。

• 在字面值區塊中超過第 70 行可能會被一些格式化程式不優雅地換行。

#另請參閱

perlpodspec、perlsyn 中的「PODs：嵌入式文件」、perlnewmod、perldoc、pod2html、pod2man、podchecker。

#作者

Larry Wall、Sean M. Burke

Perldoc 瀏覽器由 Dan Book (DBOOK) 維護。如有任何關於網站本身、搜尋或文件呈現的問題，請透過 GitHub 問題追蹤器 或 電子郵件 與他聯繫。

Perl 文件由 Perl 5 Porters 在 Perl 的開發中維護。如有任何關於文件內容或格式的問題，請透過 Perl 問題追蹤器、郵件清單或 IRC 與他們聯繫。