=encoding euc-jp =head1 NAME perlpod - plain old documentation =head1 DESCRIPTION podから何かへのトランスレータはpodファイルを段落毎に読み 込み、それを適切な出力フォーマットへと変換します。段落には L, L, L の三種類があります。 =head2 Verbatim Paragraph そのままの段落。これはインデント(つまり、空白かタブで 始まっているということ)によって認識されます。タブは8カラムごとと 仮定されてそのまま出力されます。特殊なフォーマットエスケープは ありませんから、イタリックにするといったことはできません。\は\で、 その他の意味はありません。 =head2 Command Paragraph すべてのコマンド段落は“=”で始まってその後に識別子が続き、 さらにコマンドをが必要とするテキストが続きます。 現在使えるコマンドは以下の通りです。 =head1 heading =head2 heading =item text =over N =back =cut =pod =for X =begin X =end X =over 4 =item =pod =item =cut “=pod”ディレクティブは、次の“=cunt”までコードの解析を中断し、 なにもしないことをコンパイラーに指示します。これはコードとpodを 混ぜたい場合にドキュメントに別の段落を付加えるのに便利です。 =item =head1 =item =head2 head1とhead2はそれぞれ第一レベル、第二レベルのヘッダーを、 そのディレクティブと同じ段落にあるテキストを使って生成します。 =item =over =item =back =item =item =begin original Item, over, and back require a little more explanation: "=over" starts a section specifically for the generation of a list using "=item" commands. At the end of your list, use "=back" to end it. You will probably want to give "4" as the number to "=over", as some formatters will use this for indentation. The unit of indentation is optional. If the unit is not given the natural indentation of the formatting system applied will be used. Note also that there are some basic rules to using =item: don't use them outside of an =over/=back block, use at least one inside an =over/=back block, you don't _have_ to include the =back if the list just runs off the document, and perhaps most importantly, keep the items consistent: either use "=item *" for all of them, to produce bullets, or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets or numbers. If you start with bullets or numbers, stick with them, as many formatters use the first "=item" type to decide how to format the list. =end original 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” タイプをリスト全体に使うようにそれを使いつづけてください。 =item =for =item =begin =item =end for, begin, endはpodテキストとして解釈されることのないセクションを 取り込みます。しかし、これは特定のフォーマッターに直接渡されます。 フォーマッターはそのようなフォーマットのセクションを利用することができます。 あるいは完全に無視することもあるでしょう。“=for” ディレクティブは、それに続く段落全体を“=for”の直後にある 単語によって指定されるフォーマットであることを指定します。例を挙げましょう。 =for html

This is a raw HTML paragraph

組となっているコマンド“=begin”と“=end”は“=for”と非常に良く 似ています。しかし、一つの段落に対してのみ適用されるのではなく、 “=begin”と“=end”の間にある段落を、特定のフォーマットで あるように取り扱います。 これを使った例を幾つか挙げましょう。 =begin html
Figure 1.
=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 =back =head2 Ordinary Block of Text (通常のテキストブロック) =begin original It will be filled, and maybe even justified. Certain interior sequences are recognized both here and in commands: =end original 詰め込みが行われ、おそらくは均等割り付け(justified)も行われます。 内側のシーケンスの幾つかはコマンド中でも認識されます: I テキストをイタリックにします。強調や変数に使います B テキストをボールドにします。スイッチやプログラムに使います S 分割不可能なスペースを含むテキスト C コードをタイプライタフォント、または その他のプログラムテキストを表現する手法で描画します L nameに対するリンク(クロスリファレンス) L マニュアルページ L マニュアルぺージ中のアイテム L 他のマニュアルページにあるセクション L<"sec"> 同じマニュアルページのセクション (クォートは省略可能) L 同上 上のものと同じだが 'text' だけが出力に使われる (テキストには '/' も '>'も含めることはできません。同時に '<'と'>'のバランスがとれていなければなりません) L L L L L F ファイル名に使います X 索引のエントリ Z<> 幅ゼロのキャラクター E 名前付きのキャラクター(HTMLのエスケープに酷似) E リテラルの < E リテラルの > E リテラルの / E リテラルの | (これらは、他の内側のシーケンスであったり大文字が 先行している場合でなければ省略可能) E キャラクター番号 n (おそらくASCII) E Eのような、非数値のHTMLエンティティ =begin original Most of the time, you will only need a single set of angle brackets to delimit the beginning and end of interior sequences. However, sometimes you will want to put a right angle bracket (or greater-than sign '>') inside of a sequence. This is particularly common when using a sequence to provide a different font-type for a snippet of code. As with all things in Perl, there is more than one way to do it. One way is to simply escape the closing bracket using an C sequence: =end original たいていの場合、内部シーケンスの最初と最後のデリミタとして 1 組の山括弧のみが必要です。 しかし、時々シーケンスの中に右山括弧(または大なり記号'>')を 入れたい場合があります。これはコードの断片の中で違うフォントタイプを 使いたいときによくあります。 Perl に関する他のことと同様に、やりかたはひとつではありません。 ひとつの方法は単純に閉じ括弧を C シーケンスを使って エスケープする方法です: C<$a E=E $b> =begin original This will produce: "C<$a E=E $b>" =end original これは "C<$a E=E $b>" となります。 =begin original A more readable, and perhaps more "plain" way is to use an alternate set of delimiters that doesn't require a ">" to be escaped. As of perl5.5.660, doubled angle brackets ("<<" and ">>") may be used I For example, the following will do the trick: =end original より読みやすく、そしておそらくより"明白な"方法は、別のデリミタを 使って、">"をエスケープしなくてもいいようにする方法です。 Perl5.5.660 以降、2 個の山括弧 ("<<" and ">>")が使えます。 但し、I<開始デリミタの直後と終了デリミタの直前に空白があるときだけ>です! 例えば、以下はそのトリックを使っています: C<< $a <=> $b >> =begin original In fact, you can use as many repeated angle-brackets as you like so long as you have the same number of them in the opening and closing delimiters, and make sure that whitespace immediately follows the last '<' of the opening delimiter, and immediately precedes the first '>' of the closing delimiter. So the following will also work: =end original 実際のところ、開始デリミタと終了デリミタの数さえ合っており、 開始デリミタの最後の '<' の直後と 終了デリミタの最初の '>' の 直前に空白が入っていれば、 山括弧の数はいくつでもかまいません。 従って、以下のものも正しく動作します: C<<< $a <=> $b >>> C<<<< $a <=> $b >>>> =begin original This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser 1.093 or later. =end original これは現在のところ pod2text (Pod::Text), pod2man (Pod::Man), および Pod::Parser 1.093 以降を使用しているその他の pod2xxx と Pod::Xxxx が対応しています。 =head2 The Intent (目的) これだけです。強力なものではなく簡単なものを目指しています。 段落は段落らしく(矩形に)見えて欲しいので、見た目に目立ち、 fmt で簡単に再整形できるようになっています (私の vi では F7 になっています)。 私が求めていたのは、埋め込まれるテキストの中の " や ' が左のクォートか、 右のクォートかを (私の代わりに) 気遣ってくれる トランスレータで、verbatim モードではクォートをそのままにしておいて 欲しかったのです。そうすれば、作りかけのプログラムを放り込んで、 4 カラムずらして、それをそのまま印刷すればいいのです。たぶん、 固定幅のフォントで。 特に、以下のようなものは、テキスト中にそのままにしておくことができます: Perl FILEHANDLE $variable function() manpage(3r) いずれ、別のコマンドやシーケンスを付け足さなければならなくなることは 疑いようのないことですが、これまでのところ私は意外にもこれだけで やってきたのです。 これが本を作るのに十分だ、などと言うつもりは全くありません。 私はただ、オンラインドキュメントに使うnroff やTeXといったマークアップ言語の ための、誰にでも使える共通のソースを作ろうとしているのです。 現在あるトランスレータにはB (nroff(1) や troff(1)用), B, B, B, Bがあります。 =head2 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テキストを 見失ってしまうでしょう。 =head2 Common Pod Pitfalls =over 4 =item * =begin original Pod translators usually will require paragraphs to be separated by completely empty lines. If you have an apparently empty line with some spaces on it, this can cause odd formatting. =end original podトランスレータは、通常は段落の分割に完全な空行を必要とします。 空白の入った見た目空行のようなものを入れると、 出力がおかしくなるかもしれません。 =item * =begin original Translators will mostly add wording around a LEE link, so that Cfoo(1)E> becomes "the I(1) manpage", for example (see B for details). Thus, you shouldn't write things like CfooE manpage>, if you want the translated document to read sensibly. =end original トランスレータはほとんどの場合 LEE リンクに語の追加を行います。 このため、たとえば Cfoo(1)E> は“the I(1) manpage”と なります(詳しくはBを参照)。 したがって、あなたは変換されたドキュメントを読みやすいものにするために、 CfooE manpage>という書き方はすべきではないのです。 =begin original If you need total control of the text used for a link in the output use the form LEshow this text|fooE instead. =end original あなたがテキストの制御全てを必要としているなら、 出力リンクのためには LEshow this text|fooEを使いましょう。 =item * =begin original The B command is provided to check pod syntax for errors and warnings. For example, it checks for completely blank lines in pod segments and for unknown escape sequences. It is still advised to pass it through one or more translators and proofread the result, or print out the result and proofread that. Some of the problems found may be bugs in the translators, which you may or may not wish to work around. =end original B コマンドは pod の文法に関するエラーと警告を チェックするために提供されています。 例えば、pod の分割に完全な空行が使われているかや、 不明なエスケープシーケンスなどをチェックします。 それでも一つまたは複数のトランスレータに通して結果をチェックするか、 結果を印刷してそれをチェックすることをお勧めします。 発見した問題の中には、回避しようと思ったり思わなかったりするような トランスレータのバグもあるでしょう。 =back =head1 SEE ALSO L, L, L =head1 AUTHOR Larry Wall =begin meta Translate: 吉村 寿人 Update: Kentaro Shirakata License: GPL or Artistic =end meta