NAME

perlpod - Plain Old Documentation フォーマット

DESCRIPTION

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

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

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

普通の段落

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

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

そのままの段落

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

そのままの段落は空白かタブで始まっているということによって認識されます。 (簡単に言うと、この全ての行は空白かタブで始まっています。) タブは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 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text

head1 から head4 は見出しを生成します; head1 が最上位です。 この段落の残りのテキストは見出しの内容です。 例:

  =head2 Object Attributes

"Object Attributes"というテキストがここでの見出しとなります。 これらの見出しコマンドのテキストでは以下のようにフォーマッティング コードを使えます:

  =head2 Possible Values for C<$/>

これらのコマンドは以下の "Formatting Codes" で 説明されています。

=over indentlevel
=item stuff...
=back

item, over, back はもう少し説明が必要です: "=over" は "=item" を使ったリスト生成や、普通の段落(の組)を インデントするためのリージョンを開始します。 リストの最後では、それを示すために "=back" を使います。 "=over" の indentlevel オプションはどれくらいインデントするかを 示し、一般的には単位は ems (1 em はドキュメントのベースフォントでの"M"の 幅です) か、だいたい同じぐらいの単位です; indentlevel オプションが ない場合、デフォルトは 4 です。 (何を indentlevel に指定しても無視するフォーマッタもあります。) =item stuff... の stuff の中では、 以下のようにフォーマッティングコードを使うことができます:

  =item Using C<$|> to Control Buffering

これらのコマンドは以下の "Formatting Codes" で 説明されています。

"=over" ... "=back" リージョンを使うためのいくつかの 基本的なルールがあることに注意して下さい。

=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 formatname
=end formatname
=for formatname text...

for, begin, end は、通常の Pod テキストとして解釈されるのではなく、 直接特定のフォーマッタに渡されるべきテキスト/コード/データ、 あるいはその他の特別なものの領域を定義できます。 このフォーマットを使うフォーマットはこの領域を使い、 さもなければ完全に無視します。

"=begin formatname" コマンド, いくつかの段落, "=end formatname" コマンドは、はさまれたテキスト/データが formatname と呼ばれる特別なフォーマットを理解するフォーマッタ用で あることを意味します。例:

  =begin html

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

  =end html

"=for formatname text..." コマンドは、 この段落の残り(formatname の直後から)が特別なフォーマットであることを 指定します。

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

これは上記の "=begin html" ... "=end html" リージョンと同じ意味です。

これは、"=for" では 1 段落のテキストのみを指定できます (つまり "=foo targetname text...")が、 "=begin targetname" ... "=end targetname" ではその間に好きな量のテキストを 指定できます。 ("=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!

フォーマッタの中には、 テキストが生のデータでないけれども、Pod テキストではある (つまりフォーマッティングコードを含むことがある)ことを知らせるために "=for :formatname" や "=begin :formatname" ... "=end :formatname") の ように formatnames の先頭にコロンが必要な場合もあります (通常の段落ではなく、脚注としてフォーマットするものなどです)。

=encoding encodingname

このコマンドはドキュメントのエンコーディングを決定するのに使われます。 ほとんどのユーザーには不要なものです; しかしもしエンコーディングが US-ASCII でない場合、 =encoding encodingname コマンドをドキュメントのかなり始めの方に 置いておくことで、pod フォーマッタがドキュメントをどのように デコードすればよいかを知ることができます。 encodingname に関しては、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> -- italic text

強調 ("be I<careful!>") とパラメータ ("redo I<LABEL>") のために使います。

B<text> -- bold 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> -- code text

コードをタイプライタフォントや、 あるいはプログラムテキスト("C<gmtime($^T)>")や その他のコンピュータ用語("C<drwxr-xr-x>") を 表現していることを示すその他の形でレンダリングされます。

L<name> -- a hyperlink

以下のようにさまざまな文法があります。 文法の中で、text, name, section に '/' と '|' を含むことはできません; また、'<' や '>' は対応しなければなりません。

セクションは名前付きの見出しか item で始まります。 たとえば、L<perlvar/$.> と L<perlvar/"$."> は 両方とも perlvar の "=item $." で始まるセクションへリンクします。 L<perlsyn/For Loops> と L<perlsyn/"For Loops"> は 両方とも perlsyn の "=head2 For Loops" で始まるセクションにリンクします。

どんなテキストが表示に用いられるかを制御するためには、 "L<text|...>" を使ってください; つまり:

web ページにリンクを設定することもできます。

E<escape> -- a character escape

HTML/XML &foo; "実体参照"ととても似ています。

F<filename> -- used for filenames

典型的にはイタリックで表示されます。例: "F<.cshrc>"

S<text> -- text contains non-breaking spaces

これは text の内容が行をまたがないことを意味します。 例: <S<$x ? $y : $z>>

X<topic name> -- an index entry

これは多くのフォーマッタでは無視されますが、 インデックスを作成するのに使われることもあります。 常に空文字列としてレンダリングされます。 例: X<absolutizing relative URLs>

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

これはまれに用いられます。 ときどき E<...> コードを使う方法の一つです。 例えば、("N<3" のために) "NE<lt>3" の代わりに "NZ<><3" と書けます ("Z<>" は "N" と "<" を分解するので "N<...>" の一部と(間違って)解釈されることはありません)。

もう一つの使用法は、=item Z<>stuff... の stuff が点や数字と認識されないようにするためです。 例えば、Z<> なしの場合、次のような行

 =item Z<>500 Server error

は、意図せずに数値リストのアイテムとしてパースされるかもしれません。

もう一つの使用法は、=item 行の間の目に見えるスペースを保守することです。 次のように指定すると:

 =item foo

 =item bar

典型的には次のようにレンダリングされます:

 foo
 bar

これがあなたの望むものかもしれませんが、本当に望んでいるのが次の場合:

 foo

 bar

それを成し遂げるために Z<> を使えます:

 =item foo

 Z<>

 =item bar

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

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

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

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

    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 になっています)。 私が求めていたのは、verbatim モードでは ' や ` や " のクォートを そのままにしておいて欲しかったのです; そうすれば、作りかけのプログラムを 放り込んで、4 カラムずらして、それをそのまま印刷すればいいのです。 たぶん、固定幅のフォントで。

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

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

Perl モジュールとスクリプトに Pod ドキュメントを埋め込むことができます。 ドキュメントを空行および“=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 を書くためのヒント

SEE ALSO

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

AUTHOR

Larry Wall, Sean M. Burke