Plain Old Documentation

Plain Old Documentation（POD）は、Perl における単純でプラットフォームに依存しないドキュメンテーションツールである。

 特徴 
POD は必要十分な文法を持つ単純で明快な言語として設計された。書体、画像、色、表などの機構を意図的に排除し、必要な機能だけを持つようにしている。その目的は以下の通りである。
 構文解析が簡単である。
 他の言語（HTML や TeX）への変換が簡単である。
 サンプルコードを含めるのが簡単である。
 フォーマッタで整形しなくても（ソースコードのままで）読むのが簡単である。
 書くのが簡単である。さもなくばプログラマは文書を書きたがらない。

perlpod の筆者は「POD形式は本を書くのには不十分である」と書いているが、PODを拡張した書式で本が実際に書かれている。この拡張版PODには表や脚注の機能があり、オライリーメディアから出ているいくつかのPerlに関する本で使われた。例えば、ラリー・ウォール、ジョン・オーワント、トム・クリスチャンセンの Programming Perl（邦題は『プログラミング Perl』）が有名である。POD を若干拡張修正した版としてMOD があり、Mark Jason Dominus による Higher-Order Perl で使われた。

 利用 
POD は Perl 関連での文書作成に使われている。Perl 自身、ほとんど全ての公開されている Perl モジュール、多くのスクリプト言語、多くの設計文書、Perl.com などの Perl 関連 Webサイトにある多くの記事、Parrot仮想機械などで使われている。

POD形式のソースコードをそのまま読むことは少ないが、そのままでも読めるように設計されている。一般に、perldoc ツールを使って読んだり、manページ形式に変換したり、HTML形式に変換したりする。

純粋な POD ファイルの拡張子は .pod だが、POD は通常 Perl のソースコードに埋め込んで使われるため、拡張子は .pl または .pm であることが多い。Perl インタプリタの構文解析器はソースコード内の POD 部分を無視するよう設計されている。

 POD文書例 

これは文法的に正しい POD であり、節の題名についても規約に従っている。

POD文書ソース  HTML変換結果上段はHTML表示イメージ（ウィキペディアに適した形に修正しています）、下段はHTMLソース。実際には、ヘッダタグ、節の目次リスト（デフォルト）、フッタタグも出力される。<nowiki>
=head1 名前

podsample - POD文書のサンプル

=head1 概要

    $here->isa(Piece::Of::Code);
    print <<"END";
    このインデントされたブロックはフォーマットされた
    コードか指示のため、走査されずに、スペースは保持
    されるでしょう。
    END

=head1 記述

これは標準テキストです。これはB<ボールド>、I<イタリック>、
C<$リテラルコード>のテキスト書式を
内部に含んでいます。

=head2 例の一覧

=over 4

=item * これは正丸リストです。

=item * ここに別口があります。

=back

=begin html

<img src="Example.png" align="right" alt="範例" />
<p>
    ここに、何らかの埋め込まれたHTMLがあります。
    このブロックでは、画像を入れたり、
    <span style="color: green">スタイル</span>を
    適用するか、HTMLで記述しています。PODパーサは
    HTML出力中にそれを完全に無視することはありません。
</p>

=end html

=head1 参照

L<perlpod>, L<perldoc>, L<Pod::Parser>.

=head1 著作権

Copyright 2005 J. Random Hacker <jrh@cpan.org>.

Permission is granted to copy, distribute and/or modify this 
document under the terms of the GNU Free Documentation 
License, Version 1.2 or any later version published by the 
Free Software Foundation; with no Invariant Sections, with 
no Front-Cover Texts, and with no Back-Cover Texts.

=cut
</nowiki>
 ActivePerl 5.8.8に最初からインストールされている構文解析器のpod2htmlでは、U<アンダーライン>、C<$コード> には対応していません。
 変換ツールによってHTML変換の結果は変わってきます。名前
podsample - POD文書のサンプル

概要
    $here->isa(Piece::Of::Code);
    print <<"END";
    このインデントされたブロックはフォーマットされた
    コードか指示のため、走査されずに、スペースは保持
    されるでしょう。
    END

記述
これは標準テキストです。これはボールド、
イタリック、リテラルコードの
テキスト書式を内部に含んでいます。

例の一覧
<li>これは正丸リストです。
<li>ここに別口があります。
範例|right|thumb
    ここに、何らかの埋め込まれたHTMLがあります。 
    このブロックでは、画像を入れたり、
    スタイルを
    適用するか、HTMLで記述しています。PODパーサは
    HTML出力中にそれを完全に無視することはありません。

参照
perlpod, perldoc, the Pod::Parser manpage.

著作権
Copyright 2005 J. Random Hacker <jrh@cpan.org>.
Permission is granted to copy, distribute and/or modify this 
document under the terms of the GNU Free Documentation 
License, Version 1.2 or any later version published by the 
Free Software Foundation; with no Invariant Sections, with 
no Front-Cover Texts, and with no Back-Cover Texts.<nowiki><h1><span id="name">名前</span></h1></nowiki>
<nowiki><p>podsample - POD文書のサンプル</p></nowiki>
<nowiki><p></nowiki>
<nowiki></p></nowiki>
<nowiki><hr /></nowiki>
<nowiki><h1><span id="synopsis">概要</span></h1></nowiki>
<nowiki><pre></nowiki>
<nowiki>    $here->isa(Piece::Of::Code);</nowiki>
<nowiki>    print <<"END";</nowiki>
<nowiki>    このインデントされたブロックはフォーマットされた</nowiki>
<nowiki>    コードか指示のため、走査されずに、スペースは保持</nowiki>
<nowiki>    されるでしょう。</nowiki>
<nowiki>    END</pre></nowiki>
<nowiki><p></nowiki>
<nowiki></p></nowiki>
<nowiki><hr /></nowiki>
<nowiki><h1><span id="description">記述</span></h1></nowiki>
<nowiki><p>これは標準テキストです。これは<strong>ボールド</strong>、</nowiki>
<nowiki><em>イタリック</em>、<ins>アンダーライン</ins>、<code>リテラルコード</code>の</nowiki>
<nowiki>テキスト書式を内部に含んでいます。</p></nowiki>
<nowiki><p></nowiki>
<nowiki></p></nowiki>
<nowiki><h2><span id="an_example_list">例の一覧</span></h2></nowiki>
<nowiki><ul></nowiki>
<nowiki><li><strong><span id="item_this_is_a_bulleted_list_2e">これは正丸リストです。</span></strong></nowiki>

<nowiki><li><strong><span id="item_here_27s_another_item_2e">ここに別口があります。</span></strong></nowiki>

<nowiki></ul></nowiki>
<nowiki>[[ファイル:Example.png|範例|right|thumb]]</nowiki>
<nowiki><p></nowiki>
<nowiki>    ここに、何らかの埋め込まれたHTMLがあります。</nowiki>
<nowiki>    このブロックでは、画像を入れたり、</nowiki>
<nowiki>    <span style="color: green">スタイル</span>を</nowiki>
<nowiki>    適用するか、HTMLで記述しています。PODパーサは</nowiki>
<nowiki>    HTML出力中にそれを完全に無視することはありません。 </nowiki>
<nowiki></p><p></nowiki>
<nowiki></p></nowiki>
<nowiki><hr /></nowiki>
<nowiki><h1><span id="see_also">参照</span></h1></nowiki>
<nowiki><p><em>perlpod</em>, <em>perldoc</em>, <a href="/Pod/Parser.html">the Pod::Parser manpage</a></nowiki>
<nowiki><p></nowiki>
<nowiki></p></nowiki>
<nowiki><hr /></nowiki>
<nowiki><h1><span id="copyright">著作権</span></h1></nowiki>
<nowiki><p>Copyright 2005 J. Random Hacker <jrh@cpan.org>.</p></nowiki>
<nowiki><p>Permission is granted to copy, distribute and/or modify this </nowiki>
<nowiki>document under the terms of the GNU Free Documentation </nowiki>
<nowiki>License, Version 1.2 or any later version published by the </nowiki>
<nowiki>Free Software Foundation; with no Invariant Sections, with </nowiki>
<nowiki>no Front-Cover Texts, and with no Back-Cover Texts.</p></nowiki>

 POD における書式の詳細 
PODファイルは ASCII互換の文字符号化方式（例えば Latin-1 や UTF-8）で書かれる。POD の構文解析器はファイルの先頭から POD 形式であるとは見なさず、最初に POD のディレクティブが出て来るところまでは無視する。POD のディレクティブは行の先頭に書かれ、必ず先頭に等号(=)がつく。構文解析器はその後の行がPOD形式であると見なし、"=cut" ディレクティブが先頭にある行までをPOD形式として解釈する。その後、再び別のPODディレクティブが出現するまでは無視する。このため、実行可能なコードを解釈するインタプリタが POD 形式部分を無視するなら、POD 形式と実行可能コードを混在させることができる。

POD の内容は空行で段落分けされる。段落の先頭に空白文字（スペースやタブ）がある場合、その段落は "verbatim paragraphs" として解釈され、中身を整形しない。これはサンプルコードやアスキーアートに使われる。等号記号で始まる段落は "command paragraphs" である。等号の直後に続く文字列が POD ディレクティブとして解釈され、残りの部分はディレクティブに従って整形される。ディレクティブによってはその後の段落にも影響を与える。等号や空白以外で始まる段落は "ordinary paragraphs" として解釈される。

ordinary paragraphs や command paragraphs の中身の構文解析では書式に従って整形が行われる。POD による書式指定は非常に単純である。ボールド、イタリック、アンダーライン、等幅といった書式しかない。また、同一文書内の別の節や他のPOD文書へのリンクも可能である。書式符号には以下の形式がある。

 1文字の大文字の後に不等号(<)が続き、その後に整形すべき内容、さらにその後に不等号(>)が続く。例えば、B<bolded text> となる。
 1文字の大文字の後に2つ以上の不等号(<<)が続き、その後に整形すべき内容、さらにその後に同じ個数の不等号(>>)が続く。例えば、B<< bolded text >> となる。これは内容に不等号が含まれる場合に使われる。

POD 内のコマンド（ディレクティブ）には、4段階の節、番号なしと番号つきのリスト、他の言語の節などがある。他の言語の節は、その言語を解釈する構文解析器による特殊な整形を可能にする。

 参考文献 
 Wall, Larry; Christiansen, Tom; & Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 0-12-345678-9.

 脚注 

 関連項目 
Perl
ラリー・ウォール
コンピュータ言語
データ記述言語
マークアップ言語
軽量マークアップ言語

 外部リンク 


 氷魚.jp
 perlpod - Perlに標準インストールされているPODの書き方マニュアル（和訳）
 pod2html - POD→HTMLに変換するツールのマニュアル（和訳）
 index of /Pod - Perlに標準搭載されているPOD関連のモジュールマニュアル。Pod::××なので該当する配下モジュールをクリック。(Pod::)Htmlなどを参照。（和訳）
 The CPAN search site - Perlで一番信頼のおけるモジュール配布サイト。 (英語)
 perlpod - POD形式の文書を書く人向けの説明。
 perlpodspec - POD形式の構文解析器を書く人向けの説明。
 pod2html - POD→HTMLに変換するツールのマニュアル
 Pod::Html - POD→HTMLに変換する標準モジュールのマニュアル
 Getopt::Euclid module - 入力を POD タグに基づいて自動的に構文解析する。
 Index of /src/NWCLARK/perl-5.8.8/pod/ - Perl のマニュアルページの解釈前のPOD形式を公開。
 Index of /src/NWCLARK/perl-5.8.7/lib/ - ディレクトリにPOD書式が埋め込まれたモジュールが多数存在する。

Category:Perl
Category:軽量マークアップ言語