perlpod - plain old documentation
podから何かへのトランスレーターはpodファイルをパラグラフ毎に読み 込み、それを適切な出力フォーマットへと変換します。パラグラフには 以下の三種類あります。 <verbatim|/``Verbatim Paragraph''> command ordinary text
そのままのパラグラフ。これはインデント(つまり、スペースかタブで 始まっているということ)によって認識されます。タブは8カラムごとと 仮定されてそのまま出力されます。特殊なフォーマットエスケープはあ りませんから、イタリックにするといったことはできません。¥は¥で、 その他の意味はありません。
すべてのコマンドパラグラフは“=”で始まってその後に識 別子が続き、さらにコマンドをが必要とするテキストが続きます。現在 使えるコマンドは以下の通りです。
=head1 heading
=head2 heading
=item text
=over N
=back
=cut
=pod
=for X
=begin X
=end X
“=pod”ディレクティブは、次の“=cunt”までコードの解析を中断し、 なにもしないことをコンパイラーに指示します。これはコードとpodを 混ぜたい場合にドキュメントに別のパラグラフを付加えるのに便利です。
head1とhead2はそれぞれ第一レベル、第二レベルのヘッダーを、そのデ ィレクティブと同じパラグラフにあるテキストを使って生成します。
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”のようにどちらでもないものを使うにし ろ、すべてのアイテムに対して同種のものを使ってください。bulltes なり数字を最初に使ったら、多くのフォーマッターが最初の“=item” タイプをリスト全体に使うようにそれを使いつづけてください。
for, begin, endはpodテキストとして解釈されることのないセクション を取り込みます。しかし、これは特定のフォーマッターに直接渡されま す。フォーマッターはそのようなフォーマットのセクションを利用する ことができます。あるいは完全に無視することもあるでしょう。“=for” ディレクティブは、それに続くパラグラフ全体を“=for”の直後にある 単語によって指定されるフォーマットであることを指定します。例を挙 げましょう。
=for html <br> <p> This is a raw HTML paragraph </p>
組となっているコマンド“=begin”と“=end”は“=for”と非常に良く 似ています。しかし、一つのパラグラフに対してのみ適用されるのでは なく、“=begin”と“=end”の間にあるパラグラフを、特定のフォーマ ットであるように取り扱います。
これを使った例を幾つか挙げましょう。
=begin html
<br>Figure 1.<IMG SRC="figure1.png"><br>
=end html
=begin text
--------------- | foo | | bar | ---------------
^^^^ Figure 1. ^^^^
=end text
現在使うことのできるフォーマッターの名前は``roff'', ``man'', ``latex'', ``tex'', ``text'', ``html''です(一部のフォーマッターは他のものの別名と して扱われます)。
そして忘れないで欲しいことは、これらのコマンドを使った場合、その コマンドが影響するのはコマンドが置かれた行ではなく、コマンドがあ るB<パラグラフ>の終端までだということです。ですから先の例には、 各コマンドの後ろに空行があるのです。
幾つか例を挙げましょう:
=over 4
=item *
最初のアイテム
=item *
二番目のアイテム
=back
=over 4
=item Foo()
関数 Fooの説明
=item Bar()
関数 Barの説明
=back
テキストの通常ブロック
詰め込みが行われ、おそらくは均等割り付け(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エンティティ
これだけです。強力なものではなく簡単なものを目指しています。パラ グラフはパラグラフらしく(矩形に)見えて欲しいので、見た目に目立ち、 fmt で簡単に再整形できるようになっています (私の vi では F7 にな っています)。私が求めていたのは、埋め込まれるテキストの中の `` や ' が左のクォートか、右のクォートかを (私の代わりに) 気遣ってくれる トランスレータで、verbatim モードではクォートをそのままにしてお いて欲しかったのです。そうすれば、作りかけのプログラムを放り込ん で、4 カラムずらして、それをそのまま印刷すればいいのです。たぶん、 固定幅のフォントで。
特に、以下のようなものは、テキスト中にそのままにしておくことがで きます:
Perl
FILEHANDLE
$variable
function()
manpage(3r)
いずれ、別のコマンドやシーケンスを付け足さなければならなくなるこ とは疑いようのないことですが、これまでのところ私は意外にもこれだ けでやってきたのです。
これが本を作るのに十分だ、などと言うつもりは全くありません。私は
ただ、オンラインドキュメントに使うnroff やTeXといったマークアッ
プ言語のための、誰にでも使える共通のソースを作ろうとしているので
す。現在あるトランスレーターにはpod2man (nroff(1) や troff(1) 用),pod2text, pod2html, pod2latex, pod2fmがあります。
Perlモジュールへのpodの埋め込み
Perlスクリプトにpodドキュメントを埋め込むことができます。ドキュ メントを“=head1”コマンドで始め、“=cut”で終えます。Perlはこの ようなpodテキストを無視します。実例はあなたの使っているライブラ リモジュールにあります。もしpodテキストをファイルの末尾に置きた いというのであれば、__END__や__DATA__というカットマークを置き、 さらに最初に現れるpodディレクティブの前に空行を置くことで行うこ とができます。
__END__
=head1 NAME
modern - I am a modern module
空行を置かなかった場合、トランスレーターはpodテキストを 見失ってしまうでしょう。
podトランスレーターは、通常は空行によってパラグラフを分割します。 空行を入れると、出力がおかしくなるかもしれません。
トランスレーターはL<> リンクに語の追加を行います。このた め、たとえば L<foo(1)> は“the foo(1) manpage”と なります(詳しくはpod2manを参照 )。したがって、あなたは変換さ
れたドキュメントを読みやすいものにするために、the L<foo> manpage
という書き方はすべきではないのです。
あなたがテキストの制御全てを必要としていなかったり、全てを 制御しようというのでないのなら、出力リンクのためには <show this text|foo>を使いましょう。
Perlのソース配布パッケージにあるF<pod/checkpods.PL> というスクリ プトは、空行のように見えるけれども それだけではない行の簡単な チェックしてくれます。しかし、このスクリプトは誰かが Pod::Checker を書くまでのプレースホルダーとして存在しています。自分の作ったpod をチェックする最良の方法とは、一つ以上のトランスレーターに通して その結果を確かめたり、もしくはpodを印刷してそれを校正するというも のです。あなたが好むと好まざるにかかわらず、幾つかの問題がトラン スレーターのバグとして見つかるでしょう。
pod2man and perlsyn
Larry Wall