5.6.1

Other versions:
5.40.0
5.38.0
5.36.0
5.34.0
5.32.0
5.30.0
5.28.0
5.26.1
5.24.1
5.22.1
5.20.1
5.18.1
5.16.1
5.14.1
5.12.1
5.10.1
5.10.0
5.8.4

編集

変更履歴

誤訳の報告

原文を表示/隠す

名前
説明
SEE ALSO
作者

名前¶

perlpod - plain old documentation

説明¶

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, 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.

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 <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"です(一部のフォーマッターは他のものの別名として扱われます)。

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

幾つか例を挙げましょう:

 =over 4

 =item *

 最初のアイテム

 =item *

 二番目のアイテム

 =back

 =over 4

 =item Foo()

 関数 Fooの説明

 =item Bar()

 関数 Barの説明

 =back

通常のテキストブロック¶

It will be filled, and maybe even justified. Certain interior sequences are recognized both here and in commands:

詰め込みが行われ、おそらくは均等割り付け(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エンティティ

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 E sequence:

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

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

This will produce: "$a <=> $b"

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

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 if and only if there is whitespace immediately following the opening delimiter and immediately preceding the closing delimiter! For example, the following will do the trick:

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

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

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:

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

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

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.

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

目的¶

これだけです。強力なものではなく簡単なものを目指しています。段落は段落らしく(矩形に)見えて欲しいので、見た目に目立ち、 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テキストを見失ってしまうでしょう。

Common Pod Pitfalls¶

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.

podトランスレータは、通常は段落の分割に完全な空行を必要とします。空白の入った見た目空行のようなものを入れると、出力がおかしくなるかもしれません。
Translators will mostly add wording around a L<> link, so that L<foo(1)> becomes "the foo(1) manpage", for example (see pod2man for details). Thus, you shouldn't write things like the L<foo> manpage, if you want the translated document to read sensibly.

トランスレータはほとんどの場合 L<> リンクに語の追加を行います。このため、たとえば L<foo(1)> は“the foo(1) manpage”となります(詳しくはpod2manを参照)。したがって、あなたは変換されたドキュメントを読みやすいものにするために、 the L<foo> manpageという書き方はすべきではないのです。

If you need total control of the text used for a link in the output use the form L<show this text|foo> instead.

あなたがテキストの制御全てを必要としているなら、出力リンクのためには L<show this text|foo>を使いましょう。
The podchecker 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.

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

作者¶

Larry Wall

名前¶

説明¶

Verbatim Paragraph¶

Command Paragraph¶

通常のテキストブロック¶

目的¶

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

Common Pod Pitfalls¶

SEE ALSO¶

作者¶