NAME

perlpod - plain old documentation

DESCRIPTION

podから何かへのトランスレータはpodファイルを段落毎に読み込み、それを適切な出力フォーマットへと変換します。段落には verbatim, command, ordinary text の三種類があります。

Verbatim Paragraph

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

Command Paragraph

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

    =head1 heading
    =head2 heading
    =item text
    =over N
    =back
    =cut
    =pod
    =for X
    =begin X
    =end X

=pod
=cut
“=pod”ディレクティブは、次の“=cunt”までコードの解析を中断し、なにもしないことをコンパイラーに指示します。これはコードとpodを混ぜたい場合にドキュメントに別の段落を付加えるのに便利です。
=head1
=head2
head1とhead2はそれぞれ第一レベル、第二レベルのヘッダーを、そのディレクティブと同じ段落にあるテキストを使って生成します。
=over
=back
=item
item, over, backにはもうちょっと説明が必要です。“=over”は“=item” コマンドを使ってリストを生成するためのセクションを開始します。リストの末尾では、セクションを終わらせるために“=back”コマンドを使います。一部のフォーマッターがインデントに使用している“4”を “=over”に対する数として与えたくなるでしょう。インデントの数はオプションです。数が指定されなかった場合、フォーマットシステムが適用する自然なインデントが用いられます。 =itemを使うに当たり幾つかの基本的なルールがあることに注意してください。=over/=backブロックの外側で使ってはいけません。=over/=backブロックの中に最低一つ=itemがあること。リストが単にドキュメントをrun offするだけなら=backを含める必要はありません。そして、これが多分最も重要なことですが、アイテムに一貫性を持たせることです。 “=item *”をつかってbulletsを使うか、 “=item 1.”、“=item 2.”…として数字を使うか、あるいは“=item foo”、“=item bar”のようにどちらでもないものを使うにしろ、すべてのアイテムに対して同種のものを使ってください。 bullet なり数字を最初に使ったら、多くのフォーマッターが最初の“=item” タイプをリスト全体に使うようにそれを使いつづけてください。
=for
=begin
=end
for, begin, endはpodテキストとして解釈されることのないセクションを取り込みます。しかし、これは特定のフォーマッターに直接渡されます。フォーマッターはそのようなフォーマットのセクションを利用することができます。あるいは完全に無視することもあるでしょう。“=for” ディレクティブは、それに続く段落全体を“=for”の直後にある単語によって指定されるフォーマットであることを指定します。例を挙げましょう。
```
 =for html 
 This is a raw HTML paragraph 
```
組となっているコマンド“=begin”と“=end”は“=for”と非常に良く似ています。しかし、一つの段落に対してのみ適用されるのではなく、 “=begin”と“=end”の間にある段落を、特定のフォーマットであるように取り扱います。

これを使った例を幾つか挙げましょう。
```
 =begin html
```
```
 Figure 1.<IMG SRC="figure1.png"> 
```
```
 =end html
```
```
 =begin text
```
```
 ---------------
 | foo |
 | bar |
 ---------------
```
```
 ^^^^ Figure 1. ^^^^
```
```
 =end text
```
現在使うことのできるフォーマッターの名前は"roff", "man", "latex", "tex", "text", "html"です(一部のフォーマッターは他のものの別名として扱われます)。

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

幾つか例を挙げましょう:
```
 =over 4
```
```
 =item *
```
```
 最初のアイテム
```
```
 =item *
```
```
 二番目のアイテム
```
```
 =back
```
```
 =over 4
```
```
 =item Foo()
```
```
 関数 Fooの説明
```
```
 =item Bar()
```
```
 関数 Barの説明
```
```
 =back
```

Ordinary Block of Text

(通常のテキストブロック)

詰め込みが行われ、おそらくは均等割り付け(justified)も行われます。内側のシーケンスの幾つかはコマンド中でも認識されます:

    I<text>     テキストをイタリックにします。強調や変数に使います
    B<text>     テキストをボールドにします。スイッチやプログラムに使います
    S<text>     分割不可能なスペースを含むテキスト
    C<code>     コードをタイプライタフォント、または
                その他のプログラムテキストを表現する手法で描画します
    L<name>     nameに対するリンク(クロスリファレンス)
		    L<name>		マニュアルページ
		    L<name/ident>	マニュアルぺージ中のアイテム
		    L<name/"sec">	他のマニュアルページにあるセクション
		    L<"sec">		同じマニュアルページのセクション
					(クォートは省略可能)
		    L</"sec">		同上
		上のものと同じだが 'text' だけが出力に使われる
		(テキストには '/' も '>'も含めることはできません。同時に
		'<'と'>'のバランスがとれていなければなりません)
		    L<text|name>
		    L<text|name/ident>
		    L<text|name/"sec">
		    L<text|"sec">
		    L<text|/"sec">

    F<file>	ファイル名に使います
    X<index>	索引のエントリ
    Z<>		幅ゼロのキャラクター
    E<escape>   名前付きのキャラクター(HTMLのエスケープに酷似)
		    E<lt>		リテラルの <
		    E<gt>		リテラルの >
		    E<sol>		リテラルの /
		    E<verbar>		リテラルの |
		    (これらは、他の内側のシーケンスであったり大文字が
		    先行している場合でなければ省略可能)
		    E<n>		キャラクター番号 n (おそらくASCII)
    	    	    E<html>		E<Agrave>のような、非数値のHTMLエンティティ

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

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

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

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

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

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

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

これは現在のところ pod2text (Pod::Text), pod2man (Pod::Man), および Pod::Parser 1.093 以降を使用しているその他の pod2xxx と Pod::Xxxx が対応しています。

The Intent

(目的)

これだけです。強力なものではなく簡単なものを目指しています。段落は段落らしく(矩形に)見えて欲しいので、見た目に目立ち、 fmt で簡単に再整形できるようになっています (私の vi では F7 になっています)。私が求めていたのは、埋め込まれるテキストの中の " や ' が左のクォートか、右のクォートかを (私の代わりに) 気遣ってくれるトランスレータで、verbatim モードではクォートをそのままにしておいて欲しかったのです。そうすれば、作りかけのプログラムを放り込んで、 4 カラムずらして、それをそのまま印刷すればいいのです。たぶん、固定幅のフォントで。

特に、以下のようなものは、テキスト中にそのままにしておくことができます:

    Perl
    FILEHANDLE
    $variable
    function()
    manpage(3r)

いずれ、別のコマンドやシーケンスを付け足さなければならなくなることは疑いようのないことですが、これまでのところ私は意外にもこれだけでやってきたのです。

これが本を作るのに十分だ、などと言うつもりは全くありません。私はただ、オンラインドキュメントに使うnroff やTeXといったマークアップ言語のための、誰にでも使える共通のソースを作ろうとしているのです。現在あるトランスレータにはpod2man (nroff(1) や troff(1)用), pod2text, pod2html, pod2latex, pod2fmがあります。

Embedding Pods in Perl Modules

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

Perlスクリプトにpodドキュメントを埋め込むことができます。ドキュメントを“=head1”コマンドで始め、“=cut”で終えます。 Perlはこのようなpodテキストを無視します。実例はあなたの使っているライブラリモジュールにあります。もしpodテキストをファイルの末尾に置きたいというのであれば、 __END__や__DATA__というカットマークを置き、さらに最初に現れるpodディレクティブの前に空行を置くことで行うことができます。

    __END__

    =head1 NAME

    modern - I am a modern module

空行を置かなかった場合、トランスレータはpodテキストを見失ってしまうでしょう。

Common Pod Pitfalls

podトランスレータは、通常は段落の分割に完全な空行を必要とします。空白の入った見た目空行のようなものを入れると、出力がおかしくなるかもしれません。
トランスレータはほとんどの場合 L<> リンクに語の追加を行います。このため、たとえば L<foo(1)> は“the foo(1) manpage”となります(詳しくはpod2manを参照)。したがって、あなたは変換されたドキュメントを読みやすいものにするために、 the L<foo> manpageという書き方はすべきではないのです。

あなたがテキストの制御全てを必要としているなら、出力リンクのためには L<show this text|foo>を使いましょう。
podchecker コマンドは pod の文法に関するエラーと警告をチェックするために提供されています。例えば、pod の分割に完全な空行が使われているかや、不明なエスケープシーケンスなどをチェックします。それでも一つまたは複数のトランスレータに通して結果をチェックするか、結果を印刷してそれをチェックすることをお勧めします。発見した問題の中には、回避しようと思ったり思わなかったりするようなトランスレータのバグもあるでしょう。

AUTHOR

Larry Wall