[pod] [xml]

NAME

perlpod - the Plain Old Documentation format

DESCRIPTION

Pod は、 Perl、 Perl プログラム、Perl モジュールのための ドキュメントを書くための簡単に使えるマークアップ言語です。

Pod からプレーンテキスト、HTML、man ページなどのさまざまなフォーマットに 変換するためのトランスレータがあります。

Pod マークアップは 3 種類の段落から構成されます: ordinary, verbatim, command です。

Ordinary Paragraph

(普通の段落)

あなたのドキュメントの段落のほとんどは(これと同じように) 普通のテキストのブロックです。 単に何のマークアップも使わずにテキストを書き、前後に空行を 置きます。 フォーマッティングされるとき、最小限のフォーマッティングが行われます。 再ラッピングや、プロポーショナルフォントでの表示や、 均等割り付けといったことです。

普通の段落に 強調 イタリック コードスタイル ハイパーリンク などのフォーマッティングコードを使うことも出来ます。 これらのコードは以下の "Formatting Codes" の 項目で説明します。

Verbatim Paragraph

(そのままの段落)

そのままの段落は、コードブロックや、特別なパースやフォーマッティングが 不要で、ラッピングするべきではないテキストを表現するために用いられます。

そのままの段落は空白かタブで始まっているということによって認識されます。 (簡単に言うと、この全ての行は空白かタブで始まっています。) タブは8カラムごとと仮定されてそのまま出力されます。 特殊なフォーマットコードは ありませんから、イタリックにするといったことはできません。\は\で、 その他の意味はありません。

Command Paragraph

(コマンド段落)

コマンド段落はテキストの塊全体を特別な扱いをするために用いられます。 普通は見出しやリストとして用いられます。

すべてのコマンド段落(典型的には一行だけからなります)は“=”で始まって その後に識別子が続き、 さらにコマンドをが必要とするテキストが続きます。 現在使えるコマンドは以下の通りです。

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

以下に詳細を説明します:

そして忘れないで欲しいことは、これらのコマンドを使った場合、その コマンドが影響するのはコマンドが置かれた行ではなく、 コマンドがある段落の終端までだということです。ですから先の例には、 各コマンドの後ろに段落を終了させるために空行があるのです。

幾つか例を挙げましょう:

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

Formatting Codes

(フォーマッティングコード)

普通の段落と、いくつかのコマンド段落では、さまざまな フォーマッティングコード(またの名を"内部シーケンス")を使うことができます:

たいていの場合、コードフォーマッティングの最初と最後のデリミタとして 1 組の山括弧のみが必要です。 しかし、時々フォーマッティングコードの中に右山括弧(または大なり記号'>')を 入れたい場合があります。これはコードの断片の中で違うフォントタイプを 使いたいときによくあります。 Perl に関する他のことと同様に、やりかたはひとつではありません。 ひとつの方法は単純に閉じ括弧を E コードを使って エスケープする方法です:

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

これは "$a <=> $b" となります。

より読みやすく、そしておそらくより"明白な"方法は、別のデリミタを 使って、単独の">"をエスケープしなくてもいいようにする方法です。 Perl5.5.660 以降の Pod フォーマッタでは、2 個の山括弧 ("<<" and ">>")が使えます。 但し、開始デリミタの直後と終了デリミタの直前に空白があるときだけです! 例えば、以下はそのトリックを使っています:

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

実際のところ、開始デリミタと終了デリミタの数さえ合っており、 開始デリミタの最後の '<' の直後と 終了デリミタの最初の '>' の 直前に空白が入っていれば、 山括弧の数はいくつでもかまいません。 (空白は無視されます。) 従って、以下のものも正しく動作します:

    C<<< $a <=> $b >>>
    C<<<<  $a <=> $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 が対応しています。

The Intent

(目的)

表現力ではなく簡単に使えるものを目指しています。 段落は段落らしく(矩形に)見えて欲しいので、見た目に目立ち、 fmt で簡単に再整形できるようになっています (私の vi では F7 に、emacs では Esc Q になっています)。 私が求めていたのは、verbatim モードでは ' や ` や " のクォートを そのままにしておいて欲しかったのです。そうすれば、作りかけの プログラムを放り込んで、4 カラムずらして、 それをそのまま印刷すればいいのです。たぶん、固定幅のフォントで。

Pod フォーマットは本を作るのに十分である必要はありません。 Pod はただ、オンラインドキュメントに使うnroff やTeXといったマークアップ言語の ための、誰にでも使える共通のソースを提供しています。 現在あるトランスレータには pod2text, pod2html, pod2man (nroff(1) や troff(1)用), pod2latex, pod2fmがあります。 他にもさまざまなものが CPAN にあります。

Embedding Pods in Perl Modules

(Perlモジュールへのpodの埋め込み)

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 ブロックの開始と認識しません。

Hints for Writing Pod

(Pod を書くためのヒント)

SEE ALSO

perlpodspec, perlsyn/"PODs: Embedded Documentation", perlnewmod, perldoc, pod2html, pod2man, podchecker.

AUTHOR

Larry Wall, Sean M. Burke