• NAME
• DESCRIPTION
  • 普通の段落
  • そのままの段落
  • コマンド段落
  • フォーマッティングコード
  • 目的
  • Perl モジュールへの pod の埋め込み
  • Pod を書くためのヒント
• SEE ALSO
• AUTHOR

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"というテキストがここでの見出しとなります。 (head3 と head4 は最近追加されたので、古い Pod トランスレータは 対応していません。) これらの見出しコマンドのテキストでは以下のようにフォーマッティング コードを使えます:

  =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" リージョンを使うためのいくつかの 基本的なルールがあることに注意して下さい。

• "=over" ... "=back" リージョンの外では "=item" は使えません。

• "=over" ... "=back" リージョン内に "=item" が全く現れないのでない限り、 "=over" コマンドの後、最初に書かれるのは "=item" であるべきです。

• "=over" ... "=back" リージョンの中で "=headn" は使えません。

• そしておそらくもっとも重要なこととして、item の一貫性を維持してください: 点を出力するためには全ての item に "=item *" を使ってください; 番号付きリストを出力するためには "=item 1.", "=item 2." などを使ってください。 点も番号も付けない場合は "=item foo", "=item bar" などを使ってください。

  点か番号で始めたなら、ずっとそれを使ってください。 フォーマッタは最初の "=item" のタイプを見てリストのフォーマット 方法を決定します。

=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 か Latin-1 でない場合、 =encoding encodingname コマンドをドキュメントの始めの方に 置いておくことで、pod フォーマッタがドキュメントをどのように デコードすればよいかを知ることができます。 encodingname に関しては、Encode::Supported で認識される 名前を使ってください。例:

  =encoding utf8

  =encoding koi8-r
  
  =encoding ShiftJIS
  
  =encoding big5

=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 に '/' と '|' を含むことはできません。 また、'<' や '>' は対応しなければなりません。

• L<name>

  Perl マニュアルページへのリンクを設定します(e.g., L<Net::Ping>)。 name に空白を含むことができないことに注意してください。 この文法は L<crontab(5)> の形で Unix man ページへの リファレンスのために使われることもあります。

• L<name/"sec"> または L<name/sec>

  他のマニュアルページへのある項目へのリンクを設定します。 例: L<perlsyn/"For Loops">

• L</"sec"> または L</sec>

  このマニュアルページへのある項目へのリンクを設定します。 例: L</"Object Methods">

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

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

• L<text|name>

  このテキストに指定したマニュアルページへのリンクを設定します。 例: L<Perl Error Messages|perldiag>

• L<text|name/"sec"> または L<text|name/sec>

  このテキストに指定したマニュアルページのある項目へのリンクを設定します。 例: L<postfix "if"|perlsyn/"Statement Modifiers">

• L<text|/"sec"> または L<text|/sec> または L<text|"sec">

  このテキストにこのマニュアルページのある項目へのリンクを設定します。 例: L<the various attributes|/"Member Data">

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

• L<scheme:...>

  L<text|scheme:...>

  絶対 URL へのリンクです。 例えば、L<http://www.perl.org/> や L<The Perl Home Page|http://www.perl.org/>。

E<escape> -- a character escape

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

• E<lt> -- リテラルの < (less than)

• E<gt> -- リテラルの > (greater than)

• E<verbar> -- リテラルの | (vertical bar)

• E<sol> -- リテラルの / (solidus)

  上記の 4 つは他のフォーマッティングコードの中 (特に L<...>)と、大文字が前につけられた場合を除いて オプションです。

• E<htmlname>

  いくつかの数値でない HTML エンティティ名(E<eacute> のようなもの)は HTML での é と同じ意味です -- つまり、 acute (/-の形の) アクサン付きの小文字の e です。

• E<number>

  この番号の ASCII/Latin-1/Unicode 文字です。 E<0x201E> のように先頭に "0x" があると number は 16 進数です。 E<075> のように先頭に "0" があると number は 8 進数です。 E<181> のようにそれ以外では number は 10 進数と解釈されます。

  古い Pod フォーマッタは 8 進数や 16 進数のエスケープを認識しない 可能性があり、また多くのフォーマッタは 255 以上の文字を 正しくレンダリングできるかわからないことに注意してください。 (Latin-1 文字ですら正しくレンダリングできないフォーマッタもあります。 例えば E<eacute> を普通の "e" にレンダリングします。)

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" と書けます。 (the "Z<>" は "N" と "<" を分解するので "N<...>" の一部と(間違って)解釈されることはありません。)

たいていの場合、コードフォーマッティングの最初と最後のデリミタとして 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 テキストをファイルの末尾に置きたいというのであれば、 __END__ や __DATA__ というカットマークを置き、 さらに最初に現れる Pod コマンドの前に空行を置くことで行うことができます。

  __END__

  =head1 NAME

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

"=head1" の前に空行がない場合、多くのトランスレータは"=head1"が Pod ブロックの開始と認識しません。

Pod を書くためのヒント

• podchecker コマンドは Pod の文法に関するエラーと警告を チェックするために提供されています。 例えば、Pod の分割に完全な空行が使われているかや、 不明なコマンドやフォーマットコードなどをチェックします。 それでも一つまたは複数のトランスレータに通して結果をチェックするか、 結果を印刷してそれをチェックすることをお勧めします。 発見した問題の中には、回避しようと思ったり思わなかったりするような トランスレータのバグもあるでしょう。

• もしあなたが Pod を書くことより HTML を書くことに慣れているなら、 単純な HTML でドキュメントを書き、実験的な Pod::HTML2Pod モジュール (CPAN にあります)を使って Pod に変換することを試すこともできます。 CPAN にある 実験的な Pod::PXML も有用です。

• 多くの古い Pod トランスレータは全ての Pod コマンド("=cut" を含みます!)の 前後に空行が必要です。以下のように書くと:

   # - - - - - - - - - - - -
   =item $firecracker->boom()
  
   This noisily detonates the firecracker object.
   =cut
   sub boom {
   ...

  そのような Pod トランスレータは Pod ブロックの発見に完全に 失敗するでしょう。

  代わりに、以下のように書いてください:

   # - - - - - - - - - - - -
  
   =item $firecracker->boom()
  
   This noisily detonates the firecracker object.
  
   =cut
  
   sub boom {
   ...

• 古い Pod トランスレータには、段落("=head2 Functions" のような コマンド段落も含みます)の分割に完全な空行を必要とするものもあります。 空白の入った見た目空行のようなものを入れると、 セパレータとして扱われずに出力がおかしくなるかもしれません。

• 古いトランスレータは L<> リンクに語の追加を行う場合があります。 このため、たとえば L<Foo::Bar> は“the Foo::Bar manpage”と なります(詳しくはpod2manを参照)。 したがって、あなたは変換されたドキュメントを読みやすいものにするために、 the L<foo> documentationという書き方はすべきではありません。 代わりに the L<Foo::Bar|Foo::Bar> documentation と 書くか、どのようにリンクが出来るかを制御するために L<the Foo::Bar documentation|Foo::Bar> としてください。

• そのままのブロックで 70 文字を越えると、フォーマッタによっては 見苦しいラッピングが行われるかもしれません。

SEE ALSO

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

AUTHOR

Larry Wall, Sean M. Burke