NAME

perlpodspec - Plain Old Documentation: フォーマット仕様とメモ

DESCRIPTION

この文書は、Pod マークアップ言語の詳細なメモです。 ほとんどの人にとっては、Pod の書き方を知るには perlpod だけを 読む必要がありますが、この文書は Pod のパースとレンダリングに関する 付随的な質問に答えているかも知れません。

この文書では、"must" / "must not", "should" / "should not", "may" は形式的な意味 (RFC 2119 参照) を持ちます: "X must do Y" は、もし X は Y していない場合、これは仕様に反しているので、 本当に修正されるべきということを意味します。 "X should do Y" は、推奨はしますが、もし適切な理由があるなら、 X が Y しないこともあることを意味します。 "X may do Y" は、単に X が自分の意志で Y できることを示しています (しかし、これは読者が 「そして、私はもし X が Y するなら すてきだ と思う」と、 「X が Y するかどうかは どうでもいい」という言外の意味を識別できるように するようにしています)(訳注: 原文がどの表現を用いているかは文末にかっこで 示します)。

特に、「パーサは Y するべきです(should)」と書いた場合、 呼び出し元のアプリケーションが明示的に Y しない ように指定した場合、 Y しないかもしれません。 これはしばしば、「パーサはデフォルトでは Y するべきです(should)」と 表現されます。 これはパーサが(そのままの段落でタブを展開するといった)機能 Y を オフにするかどうかのオプションを提供することを要求している わけではありませんが、 このようなオプションが提供されている かもしれない ことを示しています。

Pod の定義

Pod は他のファイル (典型的には Perl ソースファイル) に埋め込まれていますが、 Pod 以外のことは全く知らなくても Pod を書けます。

ファイルの 行 (line) は 0 個以上の改行でない文字で構成され、 改行かファイルの終わりで終端されます。

改行シーケンス (newline sequence) は普通プラットフォーム依存の 概念ですが、Pod パーサは CR (ASCII 13), LF (ASCII 10), CRLF (ASCII 13 の直後に ASCII 10) に加えて、その他の システム固有の意味ののどれでも認識するべきです(should)。 ファイルの最初の CR/CRLF/LF シーケンスを、ファイルの残りをパースするための 改行を識別するための基準として使ってもかまいません(may)。

空行 (blank line) は 0 個以上のスペース (ASCII 32) かタブ (ASCII 9) のみで 構成され、改行かファイルの終わりで終端されます。 非空行 (non-blank line) はスペースとタブ以外の文字 1 個以上を含みます (そして改行かファイルの終わりで終端されます)。

(注意: 古い Pod パーサの多くはスペースとタブで構成される行を 受け付けず、改行を空行として扱います。 これらのパーサは 何の文字も含まれていない 行だけを空行として 扱います。)

空白 (whitespace) は、この文書ではスペース、タブ、改行シーケンスを 総称する用語です。 (それ自体、この用語は普通リテラルな空白を参照します。 これは、Pod ソース中の空白文字の並びです; 一方 "E<32>" は 空白文字を 意味する フォーマッティングコードです。)

Pod パーサ (Pod parser) は Pod をパースするためのモジュールです (これはコールバックを呼び出すかパース木を構築するか直接フォーマットするかに 関わりません)。 Pod フォーマッタ (Pod formatter) (または Pod トランスレータ (Pod translator)) は Pod を他の形式 (HTML, プレーンテキスト、Tex, PostScript, RTF) に変換するモジュールかプログラムです。 Pod プロセッサ (Pod processor) はフォーマッタあるいはトランスレータか、 あるいは Pod に何かの処理(単語を数える、インデックスをスキャンする、など)を 行うプログラムかも知れません。

Pod の内容は Pod ブロック (Pod blocks) に含まれています。 一つの Pod ブロックは m/\A=[a-zA-Z]/ にマッチングする行で開始し、 m/\A=cut/ にマッチングする次の行までか、もし m/\A=cut/ 行がなければファイルの最後まで続きます。

パーサーは、ヒヤドキュメントのように、pod のように見えるけれども クォート文字列の中にあるのを区別することを装丁していないことに 注意してください。

Pod ブロックの内部は、Pod 段落(Pod paragraphs) です。 一つの Pod 段落は、1 以上の空行で分割された非空行のテキストで構成されます。

Pod 処理のために、Pod ブロックには 4 種類の段落があります:

例えば: 以下の段落を考えます:

  # <- that's the 0th column

  =head1 Foo

  Stuff

    $foo->bar

  =cut

ここで、"=head1 Foo" と "=cut" は、それぞれ最初の行が m/\A=[a-zA-Z]/ に マッチングするのでコマンド段落です。 "[space][space]$foo->bar" は、最初の行がリテラルの空白文字で始まる (そして周りに "=begin"..."=end" 領域がない)のでそのままの段落です。

"=begin identifier" ... "=end identifier" コマンドは、 identifier がコロンで始まっていないなら、その内部の段落を、 通常の段落やそのままの段落として解釈するのを停止させます。 これは "About Data Paragraphs and "=begin/=end" Regions" の節で詳しく 議論しています。

Pod コマンド

この章は "Command Paragraph" in perlpod での議論を補完して明確化することを 目的にしています。 現在認識されている Pod コマンドは以下の通りです:

"=head1", "=head2", "=head3", "=head4"

このコマンドは、この段落の残りの文章が見出しであることを示します。 この文章にはフォーマッティングコードを含むことができます。 例:

  =head1 Object Attributes

  =head3 What B<Not> to Do!
"=pod"

このコマンドは、この段落から Pod ブロックが始まることを示します。 (すでに Pod ブロックの内部である場合は、このコマンドは何の効果も ありません。) もしこのコマンド段落の "=pod" の後に何らかの文章がある場合、 無視しなければなりません(must)。 例:

  =pod

  This is a plain Pod paragraph.

  =pod This text is ignored.
"=cut"

このコマンドは、この行が Pod ブロックの終わりであることを示します。 この行の "=cut" の後にテキストがあれば、これは 無視しなければなりません(must)。 例:

  =cut

  =cut The documentation ends here.

  =cut
  # This is the first line of program text.
  sub foo { # This is the second.

Pod ブロックを "=cut" コマンドで 開始 しようとするとエラーになります。 この場合、Pod プロセッサは入力ファイルのパースを中止しなければならず(must)、 デフォルトでは警告を出力しなければなりません(must)。

"=over"

このコマンドは、これがリスト/インデント領域の開始であることを示します。 "=over" に引き続いてなんらかのテキストがある場合は、それは非ゼロの 正数のみでなければなりません(must)。 この数値の意味論はかなり後ろの "About =over...=back Regions" の節に あります。 フォーマッティングコードは展開されません。 例:

  =over 3

  =over 3.5

  =over
"=item"

このコマンドは、ここからリストの中のアイテムが始まることを示します。 フォーマッティングコードは処理されます。 この段落の(オプションである)残りのテキストの意味論はかなり後ろの "About =over...=back Regions" の節にあります。 例:

  =item

  =item *

  =item      *    

  =item 14

  =item   3.

  =item C<< $thing->stuff(I<dodad>) >>

  =item For transporting us beyond seas to be tried for pretended
  offenses

  =item He is at this time transporting large armies of foreign
  mercenaries to complete the works of death, desolation and
  tyranny, already begun with circumstances of cruelty and perfidy
  scarcely paralleled in the most barbarous ages, and totally
  unworthy the head of a civilized nation.
"=back"

このコマンドは、ここがもっとも近い位置の "=over" コマンドで始まった領域の 終わりであることを示します。 "=back" コマンドの後にテキストを置くことは許されません。

"=begin formatname"
"=begin formatname parameter"

これは、引き続く段落 (マッチングする "=end formatname" まで) が なんらかの特殊な処理をするためのものであることを示します。 "formatname" がコロンで始まっていなければ、含まれている非コマンド段落は データ段落です。 しかし、もし "formatname" がコロンで 始まっている なら、非コマンド段落は 通常の段落かデータ段落です。 これは "About Data Paragraphs and "=begin/=end" Regions" の節で詳しく 議論しています。

formatname は正規表現 m/\A:?[-a-zA-Z0-9_]+\z/ にマッチングすることを 勧めます。 formatname の後ろの空白に引き続く全てのものは、フォーマッタがこの 領域を扱うときに使われるかも知れないパラメータです。 このパラメータは "=end" 段落では繰り返されてはいけません(must not)。 実装者は "=begin"/"=end"/"=for" の最初の引数の意味論と文法の将来の拡張に 備えるべきです(should)。

"=end formatname"

これはマッチングする "=begin formatname" 領域によって開かれた領域の 終わりを示します。 "formatname" が直近に開かれた "=begin formatname" 領域の formatname では ない場合、これはエラーであり、エラーメッセージを 生成しなければなりません(must)。 これは "About Data Paragraphs and "=begin/=end" Regions" の節で詳しく 議論しています。

"=for formatname text..."

これは以下と同等です:

     =begin formatname

     text...

     =end formatname

つまり、これは単一の段落からなる領域を作成します; この段落は、 "formatname" が ":" で始まっているなら通常の段落として扱われます; "formatname" がコロンで 始まっていない なら、"text..." は データ段落を構成します。 "text..." をそのままの段落として記述するために "=for formatname text..." を 使う方法はありません。

"=encoding encodingname"

このコマンドは(文書の最初の方に(少なくとも非 US-ASCII データが出てくる 前に!)書くべきです(should))、この文書がエンコーディング encodingname で エンコードされていることを宣言します; これは Encode が認識する エンコーディングでなければなりません(must)。 (Encode::Supported にある、Encode が対応するエンコーディングの一覧が 便利です。) Pod パーサが宣言されたエンコーディングでデコードできない場合は、 警告を出力するべき(should)で、文書のパースを中断してもかまいません(may)。

複数の "=encoding" 行を持つ文書はエラーとして扱われるべきです(should)。 Pod プロセッサは、最初以外の "=encoding" 行が最初のものと同じ場合 (例えば、"=encoding utf8" 行があって、その後また "=encoding utf8" 行が あった場合)は黙って許容してもかまいません(may)。 しかし Pod プロセッサは、同じ文書に矛盾する "=encoding" 行がある場合 (例えば、文書の最初の方に "=encoding utf8" があって、その後 "=encoding big5" 行があった場合) エラーにするべきです(should)。 BOM を認識する Pod プロセッサは、BOM と矛盾する "=encoding" 行がある場合 (例えば、文書が UTF-16LE BOM で始まっていて "=encoding shiftjis" 行がある 場合)、エラーにしてもかまいません(may)。

Pod プロセッサが上に示した以外のコマンド ("=head", "=haed1", "=stuff", "=cuttlefish", "=w123" など)に遭遇した場合、プロセッサはデフォルトでは エラーとして扱わなければなりません(must)。 このようなコマンドで始まる段落を処理してはならず(must not)、デフォルトでは エラーとして警告しなければならず(must)、パースを 中断してもかまいません(may)。 Pod パーサは、特定のアプリケーションのために、上述の既知のコマンドの一覧に 追加して、それぞれの追加コマンドに対して、フォーマッティングコードを 処理するかどうかを規定する方法を認めてもかまいません(may)。

この仕様の将来のバージョンでは追加のコマンドが追加されるかもしれません。

Pod フォーマッティングコード

(この文書の以前の草案と以前の perlpod では、フォーマッティングコードは 「内部シーケンス」(interior sequences) として参照されていて、 この用語は Pod パーサの文書や、Pod プロセッサのエラーメッセージに まだ残っていることに注意してください。)

フォーマッティングコードには二つの文法があります:

Pod をパースするときに特にトリッキーな部分は、(ネストしているかもしれない!) フォーマッティングコードを正しくパースすることです。 実装者は正しい実装の例として、Pod::Parsar の parse_text ルーチンの コードを参考にするべきです。

I<text> -- イタリック文字

"Formatting Codes" in perlpod にある簡潔な議論を参照してください。

B<text> -- ボールド文字

"Formatting Codes" in perlpod にある簡潔な議論を参照してください。

C<code> -- コード文字

"Formatting Codes" in perlpod にある簡潔な議論を参照してください。

F<filename> -- ファイル名用のスタイル

"Formatting Codes" in perlpod にある簡潔な議論を参照してください。

X<topic name> -- インデックスエントリ

"Formatting Codes" in perlpod にある簡潔な議論を参照してください。

このコードは特殊で、ほとんどのフォーマッタはこのコードとその内容は 完全に捨てられます。 その他のフォーマッタは現在の文書のインデックス構築に使える 見えないコードとしてレンダリングされます。

Z<> -- a null (zero-effect) formatting code

"Formatting Codes" in perlpod で簡潔に議論されています。

このコードは特殊で、内容はなしであるべきです(should)。 つまり、プロセッサが Z<potatoes> を見ると異常とみなしても かまいません(may)。 異常とみなすかどうかに関わらず、potatoes という文字は 無視されるべきです(should)。

L<name> -- ハイパーリンク

このコードの複雑な文法は "Formatting Codes" in perlpod で詳細に 議論されていて、実装の詳細は後述する "About L<...> Codes" に あります。 L<content> の内容のパースはトリッキーです。 特に、E<...> コードが解決される 前に 、 内容が URL のように見えるか、あるいは内容が "|" や "/" で 分割する必要があるか (右順序で!) などです。

E<escape> -- 文字エスケープ

"Formatting Codes" in perlpod と、 "Notes on Implementing Pod Processors" にあるいくつかのポイントを 参照してください。

S<text> -- ノーブレークスペースを含む文字列

このフォーマッティングコードは文法的には単純ですが、意味論的には複雑です。 これが意味することは、このコードの内容にあるそれぞれのスペースは ノーブレークスペースとして認識されるということです。

以下のものを考えます:

    C<$x ? $y    :  $z>

    S<C<$x ? $y     :  $z>>

どちらも "$x"、一つのスペース、"?"、一つのスペース、":"、一つのスペース、 "$z" からなる、固定幅 (コードスタイル) 文字列として認識されます。 違いは、S コードの付いている後者は、これらのスペースは「普通の」 スペースではなく、ノーブレークスペースであるということです。

Pod プロセッサが ("N<...>" や "Q<...>" のような) 上述のもの 以外のフォーマットコードに出会った場合、プロセッサはデフォルトでは エラーとして扱わなければなりません (must)。 Pod パーサは、特定のアプリケーションのために、上述の既知のフォーマッティング コードの一覧に追加する方法を認めてもかまいません(may); Pod パーサは追加されたコマンドそれぞれに対して、L<...> が しているように、特殊処理のためのある種の形式を要求するかどうかを 規定しているかもしれません。

この仕様の将来のバージョンでは追加のフォーマッティングコードが 追加されるかもしれません。

ヒストリカルノート: いくつかの古い Pod プロセッサは、"-" の直後にある ">" を、閉じ "C<" コードとして扱いません。 これにより、以下のようなものが:

    C<$foo->bar>

以下のものと等価として扱われ:

    C<$foo-E<gt>bar>

"$foo-" だけが含まれる "C" フォーマッティングコードの後 "C" フォーマッティングコード の外にある "bar>"、と等価にはなりません。 この問題は以下のような文法の追加によって解決されました:

    C<< $foo->bar >>

準拠しているパーサは "->" を特別扱いしてはいけません (must not)。

フォーマッティングコードは絶対に段落をまたげません。 もしコードがある段落で開き、その段落の終わりまでに閉じコードがない場合、 Pod パーサはフォーマッティングを閉じなければならず(must)、 また ("Unterminated I code in the paragraph starting at line 123: 'Time objects are not...'" のような) エラーを出力するべきです (should)。 従って、これら二つの段落は:

  I<I told you not to do this!

  Don't make me say it again!>

(I コードが一つ目の段落から始まって次の段落でも始まっているという形で) 二つの段落をイタリックとしてパース してはいけません(must not)。 代わりに、最初の段落は警告を生成するべきです(should)ですが、それを 置いておいて、上述のコードは以下のようであるかのように パースしなければなりません(must):

  I<I told you not to do this!>

  Don't make me say it again!E<gt>

(SGML 的な jargon で言うなら、全ての Pod コマンドはブロックレベル要素の ようなもので、一方全ての Pod フォーマッティングコードはインライン要素の ようなものです。)

Pod プロセッサの実装に関するメモ

以下は、Pod の処理を行うためのさまざまな要求と提案の長いリストです。

L<...> コードについて

perlpod をちらっと見るだけでわかることは、L<...> コードは Pod フォーマッティングコードの中で最も複雑であると言うことです。 以下に示すポイントは、これが何を意味し、プロセッサがこれを どのように扱うべきかをできれば明確化しようとするものです。

=over...=back 領域について

"=over"..."=back" 領域は、様々な種類のリスト風の構造に使われます。 (ここでは、「領域」という用語は単に "=over" からそれに対応する "=back" までの全てを含むものという意味使っています。)

データ段落と "=begin/=end" 領域について

データ段落は典型的には文書を特定のフォーマットでレンダリングするときに 使われる(典型的にはそのまま渡される)非 Pod データを含ませるために 使います:

  =begin rtf

  \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

  =end rtf

正確に同じ効果は、偶然ながら、単一の "=for" 段落でも達成できます:

  =for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

(これは形式的にはデータ段落ではありませんが、同じ意味を持ち、 Pod パーサは同じようにパースするでしょう。)

データ段落のもう一つの例です:

  =begin html

  I like <em>PIE</em>!

  <hr>Especially pecan pie!

  =end html

通常の段落の場合、Pod パーサは (最初の段落にある) "E</em>" を "E<lt>" や "E<eacute>" と同じように、 フォーマッティングコードとして展開しようとします。 しかし、これは "=begin identifier"..."=end identifier" 領域の 中にあり、かつ 識別子 "html" は ":" 接頭辞で始まっていないので、 この領域の内容は、通常の段落(あるいは、もしスペースやタブで 始まっている場合はそのままの段落)としてされるのではなく、データ段落として 保管されます。

さらなる例: これを書いている時点で、"biblio" 識別子には対応していませんが、 一部のプロセッサがこれを(例えば、必然的に通常の段落に フォーマッティングコードを含んでいる)参考文献を示すものとして認識する ように書かれているとします。 "biblio" 段落が通常通り処理されるということは、"biblio" 識別子にコロンが 付いていることで示されています:

  =begin :biblio

  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

  =end :biblio

これはパーサに、この begin...end 領域は普通の/そのままの段落として 通常通り扱われることを前提としていることを示します (一方 "biblio" 識別子を理解するプロセッサのみのためのものであるという 意味も持ちます)。 同じ効果は以下のようにしても得られます:

  =for :biblio
  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

これらの識別子の ":" は単に「結果が特別なターゲットのためのものであっても、 この内容を通常通り処理する」ことを意味します。 私はパーサ API が "biblio" をターゲット識別子として報告するだけでなく、 ":" 接頭辞があることも報告することを推奨します。 (そして同じように、上述の "html" では、"html" をターゲット識別子として、 また ":" 接頭辞が ない ことを報告します。)

identifier がコロンで始まっている "=begin identifier"..."=end identifier" 領域は、コマンドを含むことが できる ことに注意してください。 例えば:

  =begin :biblio

  Wirth's classic is available in several editions, including:

  =for comment
   hm, check abebooks.com for how much used copies cost.

  =over

  =item

  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
  Teubner, Stuttgart.  [Yes, it's in German.]

  =item

  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

  =back

  =end :biblio

しかし、"=begin identifier"..."=end identifier" 領域で identifier が コロンで始まって いない 場合、直接 "=head1" ... "=head4" コマンドや "=over", "=back","=item" を直接含むべきではありません(should not)。 例えば、以下のものは不正となります:

  =begin somedata

  This is a data paragraph.

  =head1 Don't do this!

  This is a data paragraph too.

  =end somedata

Pod プロセッサは上述のようなもの (特に "=head1" 段落) をエラーとして 扱ってもかまいません(may)。 しかし、以下のようなものをエラーとして扱う べきではない (should not) ことに注意してください。

  =begin somedata

  This is a data paragraph.

  =cut

  # Yup, this isn't Pod anymore.
  sub excl { (rand() > .5) ? "hoo!" : "hah!" }

  =pod

  This is a data paragraph too.

  =end somedata

そしてこれも正当です:

  =begin someformat

  This is a data paragraph.

    And this is a data paragraph.

  =begin someotherformat

  This is a data paragraph too.

    And this is a data paragraph too.

  =begin :yetanotherformat

  =head2 This is a command paragraph!

  This is an ordinary paragraph!

    And this is a verbatim paragraph!

  =end :yetanotherformat

  =end someotherformat

  Another data paragraph!

  =end someformat

上述の "=begin :yetanotherformat" ... "=end :yetanotherformat" 領域の 内容はデータ段落 ではありません; なぜなら 領域の識別子 (":yetanotherformat") がコロンで始まっているからです。 実際のところ、データ段落を含んでいる領域のほとんどはデータ段落 のみ を含んでいます; しかし、上述のようなネスティングは(稀で あるとしても)文法的にはPod として正当です。 しかし、"html" のような一部の形式のハンドラは、データ段落のみをつけつけ、 ネストした領域を受け付けません; また、ネストした領域や、 "=end", "=pod", and "=cut" 以外のコマンドを(ターゲットとしている中に) 発見すると、エラーとなるかもしれません。

また、以下の正当な構造を考えてみます:

  =begin :biblio

  Wirth's classic is available in several editions, including:

  =over

  =item

  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
  Teubner, Stuttgart.  [Yes, it's in German.]

  =item

  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

  =back

  Buy buy buy!

  =begin html

  <img src='wirth_spokesmodeling_book.png'>

  <hr>

  =end html

  Now now now!

  =end :biblio

ここで、"=begin html"..."=end html" 領域は、より大きい "=begin :biblio"..."=end :biblio" 領域の内側にネストしています。 "=begin html"..."=end html" 領域の内容はデータ段落です; なぜなら 直接含んでいる領域の識別子 ("html") はコロンで始まって いない からです。

Pod パーサは、(一つの領域に含まれた)連続したデータ段落を処理するときには、 たまたま空行を含んでいる一つの大きなデータ段落として考えるべきです(should)。 それで上述の "=begin html"..."=end html" の内容は二つのデータ段落 (一つは "<img src='wirth_spokesmodeling_book.png'>\n" で、もう一つは "<hr>\n") として保管しても かまいません が(may)、一つの大きな データ段落 ("<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n") として 保管される べき です(should)。

Pod プロセッサは 空の "=begin something"..."=end something" 領域、 空の "=begin :something"..."=end :something" 領域、中身のない "=for something" 段落と "=for :something" 段落を 許容するべきです(should)。 つまり、いかのようなものは許容されるべきです(should):

  =for html

  =begin html

  =end html

  =begin :biblio

  =end :biblio

ところで、コマンドのように見えるもので始まるデータ段落を記述する簡単な 方法はないことに注意してください。 以下を考えます:

  =begin stuff

  =shazbot

  =end stuff

ここで、"=shazbot" はデータ段落 "=shazbot\n" ではなく Pod コマンド "shazbot" としてパースされます。 しかし、"=shazbot\n" からなるデータ段落は以下のようにして記述できます:

  =for stuff =shazbot

これが必要な状況は、おそらくかなり稀です。

なお、=end コマンドは現在開いている =begin コマンドと 一致しなければならないことに注意してください。 これは、適切にネストしなければならないということです。 例えば、以下は正当です:

  =begin outer

  X

  =begin inner

  Y

  =end inner

  Z

  =end outer

一方、以下は不正です:

  =begin outer

  X

  =begin inner

  Y

  =end outer

  Z

  =end inner

"=end outer" コマンドが現れたとき、現在開いている領域のフォーマット名は "outer" ではなく "inner" なので、これは不適切です。 ("outer" はより高いレベルの領域のフォーマット名です。) これはエラーです。 プロセッサはデフォルトではこれをエラーと報告しなければならず(must)、 エラーを含む文書の処理を停止してもかまいません(may)。 ここから導かれる結論は、領域は「重複」できないということです。 つまり、上述の後者のブロックは X と Y を含む "outer" と呼ばれる領域と、 Y と Z を含む "inner" と呼ばれる重複した領域を表現しているわけではないと いうことです。 しかし、これは (明らかに重複している領域全てのように) 不正なので、 これは表現されなかったり、あるいはまったく表示されなかったりします。

同様に、以下のものも不正です:

  =begin thing

  =end hting

これは、領域が "thing" で開かれていて "=end" が "hting" (原文のまま) を 閉じようとしているので、エラーです。

また、以下のものも不正です:

  =begin thing

  =end

これは、全ての "=end" コマンドにはフォーマット名引数が必要なので、 不正です。

SEE ALSO

perlpod, "PODs: Embedded Documentation" in perlsyn, podchecker

AUTHOR

Sean M. Burke