跳轉到內容

標記語言/POD 和 Wikitext/示例/Wikitext

Add links
來自 Wikibooks，開放世界中的開放書籍


名稱

[編輯 | 編輯原始碼]

perlpod - Plain Old Documentation 格式

描述

[編輯 | 編輯原始碼]

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

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

Pod 標記包含三種基本型別的段落


普通段落

[編輯 | 編輯原始碼]

文件中的大多數段落將是普通的文字塊，就像這段一樣。您可以簡單地輸入文字，而無需任何標記，只需要在前後留空行即可。當它被格式化時，它將進行最少的格式化，例如重新換行，可能被放在一個比例字型中，甚至可能被對齊。

您可以在普通段落中使用格式化程式碼，以實現粗體、斜體、程式碼樣式、超連結等等。這些程式碼在下面的格式化程式碼部分進行了解釋。

逐欄位落

[編輯 | 編輯原始碼]

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

逐欄位落以其第一個字元是空格或製表符為特徵。（並且通常，它的所有行都以空格和/或製表符開頭。）它應該被精確地複製，製表符假定在 8 列邊界上。沒有特殊的格式化程式碼，因此您無法使用斜體或類似的格式。\ 代表 \，沒有其他含義。


命令段落

[編輯 | 編輯原始碼]

命令段落用於對整個文字塊進行特殊處理，通常作為標題或列表的一部分。

所有命令段落（通常只有一行長）都以“=”開頭，後跟一個識別符號，再後跟命令可以隨意使用的任意文字。當前識別的命令是

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

詳細解釋它們

=head1 標題文字
=head2 標題文字
=head3 標題文字
=head4 標題文字

Head1 到 head4 生成標題，head1 是最高級別。此段落中其餘文字是標題的內容。例如

=head2 物件屬性

文字“物件屬性”構成了標題。 （請注意，head3 和 head4 是最近的新增，在舊的 Pod 轉換器中不受支援。）這些標題命令中的文字可以使用格式化程式碼，如下所示

=head2 C<$/> 的可能值

此類命令在下面的格式化程式碼部分進行了解釋。

=over indentlevel
=item 內容...
=back

Item、over 和 back 需要更多解釋：“=over”開始一個專門用於生成使用“=item”命令的列表或縮排（組）普通段落的區域。在列表結束時，使用“=back”來結束它。 "=over" 命令的 I<indentlevel> 選項指示縮排的距離，通常以 em 為單位（其中一個 em 是文件基本字型中“M”的寬度）或大致等效的單位；如果不存在 I<indentlevel> 選項，則預設為 4。 （並且一些格式化程式可能會忽略您提供的任何 <indentlevel>。）在 C<=item I<stuff...>> 中的 I<stuff> 中，您可以使用格式化程式碼，如下所示

=item 使用 $| 控制緩衝

此類命令在下面的“L<Formatting Codes|/"Formatting Codes">”部分進行了解釋。

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

  • 不要在 "=over" ... "=back" 區域之外使用 "=item"。
  • "=over" 命令後的第一個東西應該是一個 "=item"，除非在這個 "=over" ... "=back" 區域中沒有專案。
  • 不要將 "=headI<n>" 命令放在 "=over" ... "=back" 區域內。
  • 也許最重要的是，保持專案的一致性：要麼對所有專案使用 "=item *"，以生成專案符號；要麼使用 "=item 1."，"=item 2." 等等，以生成編號列表；要麼使用 "=item foo"，"=item bar" 等等——也就是說，看起來不像專案符號或數字的東西。
如果您以專案符號或數字開頭，請繼續使用它們，因為格式化程式會使用第一個 "=item" 型別來決定如何格式化列表。
=cut

要結束一個 Pod 塊，請使用空行，然後是一行以“=cut”開頭，然後是空行。這使 Perl（和 Pod 格式化程式）知道 Perl 程式碼從這裡恢復。（"=cut" 前面的空行在技術上不是必需的，但許多舊的 Pod 處理器需要它。）

=pod

"=pod" 命令本身並沒有做太多事情，但它向 Perl（和 Pod 格式化程式）發出訊號，表明 Pod 塊從這裡開始。Pod 塊以 I<any> 命令段落開頭，因此“=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 formatname
  • =end formatname
  • =for formatname text...

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

命令 "=begin I<formatname>"、一些段落和命令 "=end I<formatname>" 意味著它們之間的文字/資料是為理解名為 I<formatname> 的特殊格式的格式化程式準備的。例如，

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

命令 "=for I<formatname> I<text...>" 指定僅此段落的其餘部分（從 I<formatname> 之後開始）採用這種特殊格式。

=for html

<img src="thang.png">

這是一個原始 HTML 段落

這與上面的 "=begin html" ... "=end html" 區域相同。

也就是說，使用 "=for"，您只能擁有一個段落長度的文字（即，"=foo targetname text..." 中的文字），但使用 "=begin targetname" ... "=end targetname"，您可以在它們之間擁有任意數量的內容。 （請注意，在“=begin”命令之後仍然必須有一個空行，並且在“=end”命令之前必須有一個空行。）

以下是一些使用它們的示例

 =begin html

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


 =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!

一些 I<formatnames> 將需要一個冒號開頭（如 C<"=for :formatname">，或 C<"=begin :formatname" ... "=end :formatname">），以指示文字不是原始資料，而是 I<is> Pod 文字（即，可能包含格式化程式碼），只是不適用於普通格式化（例如，可能不是普通用途的段落，但可能是用於作為腳註格式化的）。

  • =encoding encodingname

此命令用於宣告文件的編碼。大多數使用者不需要此命令；但是，如果您的編碼不是 US-ASCII 或 Latin-1，則在文件開頭放置一個 C<=encoding I<encodingname>> 命令，以便 pod 格式化程式知道如何解碼文件。對於 I<encodingname>，請使用 L<Encode::Supported> 模組識別的名稱。示例

 =encoding utf8

 =encoding koi8-r

 =encoding ShiftJIS

 =encoding big5

不要忘記，使用任何命令時，該命令一直持續到其 I<paragraph> 結束，而不是其行結束。因此，在下面的示例中，您可以看到每個命令都需要在其之後留空行來結束其段落。一些列表示例包括

 
  =over 
  =item * 
  First item 
  =item * 
  Second item 
  =back 
  =over 
  =item Foo() 
  Description of Foo function 
  =item Bar() 
  Description of Bar function 
  =back

格式化程式碼

[編輯 | 編輯原始碼]

在普通段落和某些命令段落中，可以使用各種格式化程式碼（也稱為“內部序列”）


I<text>
斜體文字
用於強調（“C<be I<careful!>>”）和引數（“C<redo I<LABELE>>”）
B<text>
粗體文字
用於開關（“C<perl's B<-n> switch>”）、程式（“C<some systems provide a B<chfn> for that>”）、強調（“C<be B<careful!>>”）等等（“C<and that feature is known as B<autovivification>>”）。
C<code>
程式碼文字
以打字機字型渲染程式碼，或以其他方式指示程式碼文字，例如 "C<gmtime($^T)>" 或其他形式的計算機語言 "C<drwxr-xr-x>"。
L<name>
一個超連結
有多種語法，如下所示。在給定的語法中，given、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<"sec">
連結到本手冊頁中的一個節。例如，
L</"Object Methods">

一個節以命名的標題或專案開始。例如，C<L<perlvar/$.>> 或 C<L<perlvar/"$.">> 都連結到 perlvar 中以 "C<=item $.>" 開始的節。並且 C<L<perlsyn/For Loops>> 或 C<L<perlsyn/"For Loops">> 都連結到 perlsyn 中以 "C<=head2 For Loops>" 開始的節。

要控制用於顯示的文字，可以使用 "C<L<text|...>>"，例如

  • L<text|name>

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

=item *

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

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

=item *

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

將此文字連結到本手冊頁中的該節。例如，C<L<the various attributes|/"Member Data">>

=back

或者你可以連結到一個網頁

=over

=item *

C<L<scheme:...>>

連結到一個絕對 URL。例如，C<L<http://www.perl.org/>>。但請注意，出於多種原因，沒有相應的 C<L<text|scheme:...>> 語法。

=back

=item C<E<escape>> -- 一個字元轉義 X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>

非常類似於 HTML/XML 中的 C<&I<foo>;> "實體引用"

=over

=item *

C<<> -- 一個文字 <（小於）

=item *

C<>> -- 一個文字 >（大於）

=item *

C<E<verbar>> -- 一個文字 |（I<ver>tical I<bar>）

=item *

C<E<sol>> = 一個文字 / （I<sol>idus）

以上四個是可選的，除了在其他格式化程式碼中，特別是 C<L<...>>，以及在以大寫字母開頭的情況下。

=item *

C<E<htmlname>>

一些非數字 HTML 實體名稱，例如 C<E<eacute>>，意思與 HTML 中的 C<é> 相同 - 也就是說，一個小寫 e 帶有銳音（/- 形）重音。

=item *

C<E<number>>

具有該數字的 ASCII/Latin-1/Unicode 字元。一個前導 "0x" 表示 I<number> 是十六進位制，如 C<E<0x201E>>。一個前導 "0" 表示 I<number> 是八進位制，如 C<E<075>>。否則，I<number> 被解釋為十進位制，如 C<E<181>>。

請注意，較舊的 Pod 格式化程式可能無法識別八進位制或十六進位制數字轉義，並且許多格式化程式無法可靠地呈現超過 255 的字元。（一些格式化程式甚至可能不得不使用妥協的 Latin-1 字元渲染，例如將 C<E<eacute>> 渲染為簡單的 "e"。）

=back

=item C<F<filename>> -- 用於檔名

X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>

通常以斜體顯示。示例："C<F<.cshrc>>"

=item C<S<text>> -- 文字包含不間斷空格

X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space> 
X<non-breaking space>

這意味著 I<text> 中的單詞不應該斷開跨行。示例：S<C<S<$x ? $y : $z>>>。

=item C<X<topic name>> -- 一個索引條目 X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>

大多數格式化程式會忽略它，但有些可能會用它來構建索引。它始終呈現為空字串。示例：C<X<absolutizing relative URLs>>

=item C<Z<>> -- 一個空（零效果）格式化程式碼 X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>

這很少使用。它是在某些情況下繞過使用 E<...> 程式碼的一種方法。例如，而不是 "C<N<3>"（對於 "N<3"），你可以寫 "C<NZ<><3>"（"Z<>" 將 "N" 和 "<" 分開，因此它們不能被視為（虛構的）"N<...>" 程式碼的一部分。

=for comment

This was formerly explained as a "zero-width character".  But it in
most parser models, it parses to nothing at all, as opposed to parsing
as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters.
So "width" and "character" are exactly the wrong words.

=back

大多數情況下，你只需要一對尖括號來分隔格式化程式碼的開頭和結尾。但是，有時你可能想要在格式化程式碼中放入一個真正的右尖括號（大於號，'>'）。這在使用格式化程式碼為程式碼片段提供不同的字型型別時尤其常見。與 Perl 中的所有事物一樣，有多種方法可以做到這一點。一種方法是簡單地使用 C<E> 程式碼轉義結束括號

   C<$a <=> $b>

這將產生："C<$a <=> $b>"

一種更易讀，可能更 "簡單" 的方法是使用不需轉義單個 ">" 的備用分隔符。對於從 perl5.5.660 開始成為標準的 Pod 格式化程式，可以使用雙尖括號 ("<<" 和 ">>") I<如果且僅當在開啟分隔符後緊跟空格，並且在關閉分隔符之前緊跟空格！>。例如，以下將起作用：X<POD, formatting code, escaping with multiple brackets>

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

事實上，你可以使用任意多個重複的尖括號，只要你在開啟和關閉分隔符中使用相同數量的尖括號，並確保在開啟分隔符的最後一個 '<' 後緊跟空格，並且在關閉分隔符的第一個 '>' 之前緊跟空格。（空格會被忽略。）因此，以下也會起作用：X<POD, formatting code, escaping with multiple brackets>

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

它們都與以下完全相同

   C<$a <=> $b>

作為另一個示例，這意味著如果你想要將這些程式碼片段放入 C<C>（程式碼）樣式中

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

你可以像這樣進行

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

這可能比舊方法更易讀

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

這目前受 pod2text (Pod::Text)、pod2man (Pod::Man) 以及任何其他使用 Pod::Parser 1.093 或更高版本，或 Pod::Tree 1.02 或更高版本的 pod2xxx 或 Pod::Xxxx 翻譯器支援。

意圖

[edit | edit source]

X<POD, intent of>

意圖是使用簡單，而不是表達能力強。段落看起來像段落（塊格式），以便它們在視覺上突出，這樣我就可以輕鬆地將它們透過 C<fmt> 執行來重新格式化（在我的 B<vi> 版本中是 F7，或者在我的 B<emacs> 版本中是 Esc Q）。我希望翻譯器始終將 C<'> 和 C<`> 以及 C<"> 引號保留在原樣，以逐字模式，這樣我就可以將一個正在工作的程式吸入，向右移四個空格，並讓它打印出來，呃，逐字。並且可能以等寬字型。

Pod 格式不一定足以編寫一本書。Pod 只是為了成為 nroff、HTML、TeX 和其他標記語言（用於線上文件）的傻瓜式通用原始碼。存在 B<pod2text>、B<pod2html>、B<pod2man>（這是針對 nroff(1) 和 troff(1) 的）、B<pod2latex> 和 B<pod2fm> 的翻譯器。CPAN 中還有其他各種翻譯器可用。


在 Perl 模組中嵌入 Pods

[edit | edit source]

你可以在你的 Perl 模組和指令碼中嵌入 Pod 文件。從一個空行開始你的文件，在開頭使用 "=head1" 命令，並在結尾使用 "=cut" 命令和一個空行。Perl 會忽略 Pod 文字。檢視任何提供的庫模組以獲取示例。如果你要將你的 Pod 放在檔案末尾，並且你正在使用 __END__ 或 __DATA__ 剪下標記，請確保在第一個 Pod 命令之前放置一個空行。

 __END__

 =head1 NAME

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

如果沒有在 "=head1" 之前的那一行空行，許多翻譯器將無法識別 "=head1" 是 Pod 塊的開始。

編寫 Pod 的提示

[edit | edit source]

=over

=item *

提供 B<podchecker> 命令來檢查 Pod 語法是否有錯誤和警告。例如，它會檢查 Pod 塊中完全為空的行以及未知的命令和格式化程式碼。你仍然應該將你的文件透過一個或多個翻譯器，並校對結果，或者列印結果並校對它。發現的一些問題可能是翻譯器中的錯誤，你可能願意或不願意解決這些錯誤。

=item *

如果你更熟悉使用 HTML 而不是 Pod 編寫，你可以嘗試使用簡單的 HTML 編寫文件，並使用實驗性的 L<Pod::HTML2Pod|Pod::HTML2Pod> 模組（在 CPAN 中可用）將其轉換為 Pod，並檢視生成的程式碼。CPAN 中的實驗性 L<Pod::PXML|Pod::PXML> 模組也可能有用。

=item *

許多較舊的 Pod 翻譯器要求每個 Pod 命令之前和之後的行（包括 "=cut"！）都是一個空行。如果像這樣

# - - - - - - - - - - - -
=item $firecracker->boom()

This noisily detonates the firecracker object.
=cut
sub boom {
...

... 將使這些 Pod 翻譯器完全無法識別 Pod 塊。

相反，應該像這樣

# - - - - - - - - - - - -
  • $firecracker->boom()
    • 這會發出噪音，引爆 firecracker 物件。
 
 sub boom {
 ...
  • 一些較舊的 Pod 翻譯器要求段落（包括像 "=head2 Functions" 這樣的命令段落）用 I<完全> 空行隔開。如果你有一個明顯為空的行，但上面有一些空格，對於這些翻譯器來說，這可能不算作分隔符，這會導致奇特的格式。
  • 較舊的翻譯器可能會在 L<> 連結周圍新增文字，因此 C<L<Foo::Bar>> 可能變成 "the Foo::Bar manpage"，例如。所以你不應該寫類似 C<the L<foo> documentation> 的東西，如果你想要翻譯後的文件讀起來通順 - 相反，寫 C<the L<Foo::Bar|Foo::Bar> documentation> 或 C<L<the Foo::Bar documentation|Foo::Bar>>，來控制連結的顯示方式。
  • 在逐字塊中超過第 70 列可能會被一些格式化程式粗暴地換行。

另請參閱

[edit | edit source]

L<perlpodspec>、L<perlsyn/"PODs: Embedded Documentation">、L<perlnewmod>、L<perldoc>、L<pod2html>、L<pod2man>、L<podchecker>。

作者

[edit | edit source]

Larry Wall、Sean M. Burke

=cut

檢索自 "https://wikibook.tw/w/index.php?title=Markup_Languages/POD_and_Wikitext/Exmaple/Wikitext&oldid=4412982"
華夏公益教科書