NAME ¶

perlpod - Plain Old Documentation フォーマット

説明¶

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
    =head5 Heading Text
    =head6 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

=head5 Heading Text

=head6 Heading Text

Head1 through head6 produce headings, head1 being the highest level. The text in the rest of this paragraph is the content of the heading. For example:

head1 から head4 は見出しを生成します; head1 が最上位です。 この段落の残りのテキストは見出しの内容です。 例:

  =head2 Object Attributes

The text "Object Attributes" comprises the heading there. The text in these heading commands can use formatting codes, as seen here:

"Object Attributes"というテキストがここでの見出しとなります。 これらの見出しコマンドのテキストでは以下のようにフォーマッティング コードを使えます:

  =head2 Possible Values for C<$/>

Such commands are explained in the "Formatting Codes" section, below.

これらのコマンドは以下の "Formatting Codes" で 説明されています。

Note that head5 and head6 were introduced in 2020 and in Pod::Simple 3.41, released in October 2020, so they might not be supported on the Pod parser you use.

head5 と head6 は 2020 年に導入され、2020 年 10 月にリリースされた Pod::Simple 3.41 で対応されたので、あなたがお使いの Pod パーサは 対応していないかもしれないことに注意してください。

=over indentlevel

=item stuff...

=back

Item, over, and back require a little more explanation: "=over" starts a region specifically for the generation of a list using "=item" commands, or for indenting (groups of) normal paragraphs. At the end of your list, use "=back" to end it. The indentlevel option to "=over" indicates how far over to indent, generally in ems (where one em is the width of an "M" in the document's base font) or roughly comparable units; if there is no indentlevel option, it defaults to four. (And some formatters may just ignore whatever indentlevel you provide.) In the stuff in =item stuff..., you may use formatting codes, as seen here:

item, over, back はもう少し説明が必要です: "=over" は "=item" を使ったリスト生成や、普通の段落(の組)を インデントするためのリージョンを開始します。 リストの最後では、それを示すために "=back" を使います。 "=over" の indentlevel オプションはどれくらいインデントするかを 示し、一般的には単位は ems (1 em はドキュメントのベースフォントでの"M"の 幅です) か、だいたい同じぐらいの単位です; indentlevel オプションが ない場合、デフォルトは 4 です。 (何を indentlevel に指定しても無視するフォーマッタもあります。) =item stuff... の stuff の中では、 以下のようにフォーマッティングコードを使うことができます:

  =item Using C<$|> to Control Buffering

Such commands are explained in the "Formatting Codes" section, below.

これらのコマンドは以下の "Formatting Codes" で 説明されています。

Note also that there are some basic rules to using "=over" ... "=back" regions:

"=over" ... "=back" リージョンを使うためのいくつかの 基本的なルールがあることに注意して下さい。

• Don't use "=item"s outside of an "=over" ... "=back" region.

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

• The first thing after the "=over" command should be an "=item", unless there aren't going to be any items at all in this "=over" ... "=back" region.

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

• Don't put "=headn" commands inside an "=over" ... "=back" region.

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

• 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.--namely, things that look nothing like bullets or numbers. (If you have a list that contains both: 1) things that don't look like bullets nor numbers, plus 2) things that do, you should preface the bullet- or number-like items with Z<>. See Z<> below for an example.)

  そしておそらくもっとも重要なこととして、item の一貫性を維持してください: 点を出力するためには全ての item に "=item *" を使ってください; 番号付きリストを出力するためには "=item 1.", "=item 2." などを使ってください; 点も番号も付けない場合は "=item foo", "=item bar" などを使ってください。 ( 1) 点にも数値にも見えないようなもの、2) そのように見えるもの、の両方を 含んでいるリストの場合、 Z<> で点または数値のように見えるものを前置するべきです。 例については後述する Z<> を 参照してください。)

  If you start with bullets or numbers, stick with them, as formatters use the first "=item" type to decide how to format the list.

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

=cut

To end a Pod block, use a blank line, then a line beginning with "=cut", and a blank line after it. This lets Perl (and the Pod formatter) know that this is where Perl code is resuming. (The blank line before the "=cut" is not technically necessary, but many older Pod processors require it.)

Pod ブロックを終了するためには、空行、"=cut"で始まる行、空行を書きます。 これにより Perl (と Pod フォーマッタ) はここから Perl コードが 再開することがわかります。 ("=cut" の前の空行は技術的には不要ですが、多くの古い Pod プロセッサはこれが必要です。)

=pod

The "=pod" command by itself doesn't do much of anything, but it signals to Perl (and Pod formatters) that a Pod block starts here. A Pod block starts with any command paragraph, so a "=pod" command is usually used just when you want to start a Pod block with an ordinary paragraph or a verbatim paragraph. For example:

"=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, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.

for, begin, end は、通常の Pod テキストとして解釈されるのではなく、 直接特定のフォーマッタに渡されるべきテキスト/コード/データ、 あるいはその他の特別なものの領域を定義できます。 このフォーマットを使うフォーマットはこの領域を使い、 さもなければ完全に無視します。

A command "=begin formatname", some paragraphs, and a command "=end formatname", mean that the text/data in between is meant for formatters that understand the special format called formatname. For example,

"=begin formatname" コマンド, いくつかの段落, "=end formatname" コマンドは、はさまれたテキスト/データが formatname と呼ばれる特別なフォーマットを理解するフォーマッタ用で あることを意味します。例:

  =begin html

  <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>

  =end html

The command "=for formatname text..." specifies that the remainder of just this paragraph (starting right after formatname) is in that special format.

"=for formatname text..." コマンドは、 この段落の残り(formatname の直後から)が特別なフォーマットであることを 指定します。

  =for html <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>

This means the same thing as the above "=begin html" ... "=end html" region.

これは上記の "=begin html" ... "=end html" リージョンと同じ意味です。

That is, with "=for", you can have only one paragraph's worth of text (i.e., the text in "=foo targetname text..."), but with "=begin targetname" ... "=end targetname", you can have any amount of stuff in between. (Note that there still must be a blank line after the "=begin" command and a blank line before the "=end" command.)

これは、"=for" では 1 段落のテキストのみを指定できます (つまり "=foo targetname text...")が、 "=begin targetname" ... "=end targetname" ではその間に好きな量のテキストを 指定できます。 ("=begin" コマンドの直後と "=end" コマンドの直前に空行が必要であることに 注意してください。)

Here are some examples of how to use these:

これを使った例を幾つか挙げましょう。

  =begin html

  <br>Figure 1.<br><IMG SRC="figure1.png"><br>

  =end html

  =begin text

    ---------------
    |  foo        |
    |        bar  |
    ---------------

  ^^^^ Figure 1. ^^^^

  =end text

Some format names that formatters currently are known to accept include "roff", "man", "latex", "tex", "text", and "html". (Some formatters will treat some of these as synonyms.)

現在使うことのできるフォーマット名は"roff", "man", "latex", "tex", "text", "html"です。 (一部のフォーマッタは他のものの別名として扱われます。)

A format name of "comment" is common for just making notes (presumably to yourself) that won't appear in any formatted version of the Pod document:

フォーマット名"comment" は(おそらくはあなた自身のための)単なるメモで、 フォーマッティングした Pod ドキュメントには現れるべきでない場合に 用いられる一般的な名称です。

  =for comment
  Make sure that all the available options are documented!

Some formatnames will require a leading colon (as in "=for :formatname", or "=begin :formatname" ... "=end :formatname"), to signal that the text is not raw data, but instead is Pod text (i.e., possibly containing formatting codes) that's just not for normal formatting (e.g., may not be a normal-use paragraph, but might be for formatting as a footnote).

フォーマッタの中には、 テキストが生のデータでないけれども、Pod テキストではある (つまりフォーマッティングコードを含むことがある)ことを知らせるために "=for :formatname" や "=begin :formatname" ... "=end :formatname") の ように formatnames の先頭にコロンが必要な場合もあります (通常の段落ではなく、脚注としてフォーマットするものなどです)。

=encoding encodingname

This command is used for declaring the encoding of a document. Most users won't need this; but if your encoding isn't US-ASCII, then put a =encoding encodingname command very early in the document so that pod formatters will know how to decode the document. For encodingname, use a name recognized by the Encode::Supported module. Some pod formatters may try to guess between a Latin-1 or CP-1252 versus UTF-8 encoding, but they may guess wrong. It's best to be explicit if you use anything besides strict ASCII. Examples:

このコマンドはドキュメントのエンコーディングを決定するのに使われます。 ほとんどのユーザーには不要なものです; しかしもしエンコーディングが US-ASCII でない場合、 =encoding encodingname コマンドをドキュメントのかなり始めの方に 置いておくことで、pod フォーマッタがドキュメントをどのように デコードすればよいかを知ることができます。 encodingname に関しては、Encode::Supported で認識される 名前を使ってください。 pod フォーマッタによっては Latin-1 や CP-1252 と UTF-8 エンコーディングを 推測しようとするかもしれませんが、推測は間違うかもしれません。 厳密な ASCII 以外のものを使う場合は、明示するのが最良です。 例:

  =encoding latin1

  =encoding utf8

  =encoding koi8-r

  =encoding ShiftJIS

  =encoding big5

=encoding affects the whole document, and must occur only once.

=encoding は文書全体に影響を与え、一度だけしか使えません。

そして忘れないで欲しいことは、=encoding 以外の全てのコマンドは、その コマンドが置かれた行ではなく、コマンドがある 段落 の終端までコマンドが 影響するということです。 ですから先の例には、 各コマンドの後ろに段落を終了させるために空行があるのです。 (そして一部の古い Pod トランスレータは、省略しても正当である =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

Used for emphasis ("be I<careful!>") and parameters ("redo I<LABEL>")

強調 ("be I<careful!>") とパラメータ ("redo I<LABEL>") のために使います。

B<text> -- bold text

Used for switches ("perl's B<-n> switch"), programs ("some systems provide a B<chfn> for that"), emphasis ("be B<careful!>"), and so on ("and that feature is known as B<autovivification>").

スイッチ("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

Renders code in a typewriter font, or gives some other indication that this represents program text ("C<gmtime($^T)>") or some other form of computerese ("C<drwxr-xr-x>").

コードをタイプライタフォントや、 あるいはプログラムテキスト("C<gmtime($^T)>")や その他のコンピュータ用語("C<drwxr-xr-x>") を 表現していることを示すその他の形でレンダリングされます。

L<name> -- a hyperlink

There are various syntaxes, listed below. In the syntaxes given, text, name, and section cannot contain the characters '/' and '|'; and any '<' or '>' should be matched.

以下のようにさまざまな文法があります。 文法の中で、text, name, section に '/' と '|' を含むことはできません; また、'<' や '>' は対応しなければなりません。

• L<name>

  L<name>

  Link to a Perl manual page (e.g., L<Net::Ping>). Note that name should not contain spaces. This syntax is also occasionally used for references to Unix man pages, as in L<crontab(5)>.

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

• L<name/"sec"> or L<name/sec>

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

  Link to a section in other manual page. E.g., L<perlsyn/"For Loops">

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

• L</"sec"> or L</sec>

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

  Link to a section in this manual page. E.g., L</"Object Methods">

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

A section is started by the named heading or item. For example, L<perlvar/$.> or L<perlvar/"$."> both link to the section started by "=item $." in perlvar. And L<perlsyn/For Loops> or L<perlsyn/"For Loops"> both link to the section started by "=head2 For Loops" in perlsyn.

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

To control what text is used for display, you use "L<text|...>", as in:

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

• L<text|name>

  L<text|name>

  Link this text to that manual page. E.g., L<Perl Error Messages|perldiag>

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

• L<text|name/"sec"> or L<text|name/sec>

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

  Link this text to that section in that manual page. E.g., L<postfix "if"|perlsyn/"Statement Modifiers">

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

• L<text|/"sec"> or L<text|/sec> or L<text|"sec">

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

  Link this text to that section in this manual page. E.g., L<the various attributes|/"Member Data">

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

Or you can link to a web page:

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

• L<scheme:...>

  L<text|scheme:...>

  Links to an absolute URL. For example, L<http://www.perl.org/> or L<The Perl Home Page|http://www.perl.org/>.

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

E<escape> -- a character escape

Very similar to HTML/XML &foo; "entity references":

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

• E<lt> -- a literal < (less than)

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

• E<gt> -- a literal > (greater than)

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

• E<verbar> -- a literal | (vertical bar)

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

• E<sol> -- a literal / (solidus)

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

  The above four are optional except in other formatting codes, notably L<...>, and when preceded by a capital letter.

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

• E<htmlname>

  E<htmlname>

  Some non-numeric HTML entity name, such as E<eacute>, meaning the same thing as é in HTML -- i.e., a lowercase e with an acute (/-shaped) accent.

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

• E<number>

  E<number>

  The ASCII/Latin-1/Unicode character with that number. A leading "0x" means that number is hex, as in E<0x201E>. A leading "0" means that number is octal, as in E<075>. Otherwise number is interpreted as being in decimal, as in E<181>.

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

  Note that older Pod formatters might not recognize octal or hex numeric escapes, and that many formatters cannot reliably render characters above 255. (Some formatters may even have to use compromised renderings of Latin-1/CP-1252 characters, like rendering E<eacute> as just a plain "e".)

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

F<filename> -- used for filenames

Typically displayed in italics. Example: "F<.cshrc>"

典型的にはイタリックで表示されます。例: "F<.cshrc>"

S<text> -- text contains non-breaking spaces

This means that the words in text should not be broken across lines. Example: S<$x ? $y : $z>.

これは text の内容が行をまたがないことを意味します。 例: <S<$x ? $y : $z>>

X<topic name> -- an index entry

This is ignored by most formatters, but some may use it for building indexes. It always renders as empty-string. Example: X<absolutizing relative URLs>

これは多くのフォーマッタでは無視されますが、 インデックスを作成するのに使われることもあります。 常に空文字列としてレンダリングされます。 例: X<absolutizing relative URLs>

Z<> -- a null (zero-effect) formatting code

This is rarely used. It's one way to get around using an E<...> code sometimes. For example, instead of "NE<lt>3" (for "N<3") you could write "NZ<><3" (the "Z<>" breaks up the "N" and the "<" so they can't be considered the part of a (fictitious) "N<...>" code).

これはまれに用いられます。 ときどき E<...> コードを使う方法の一つです。 例えば、("N<3" のために) "NE<lt>3" の代わりに "NZ<><3" と書けます ("Z<>" は "N" と "<" を分解するので "N<...>" の一部と(間違って)解釈されることはありません)。

Another use is to indicate that stuff in =item Z<>stuff... is not to be considered to be a bullet or number. For example, without the Z<>, the line

もう一つの使用法は、=item Z<>stuff... の stuff が点や数字と認識されないようにするためです。 例えば、Z<> なしの場合、次のような行

 =item Z<>500 Server error

could possibly be parsed as an item in a numbered list when it isn't meant to be.

は、意図せずに数値リストのアイテムとしてパースされるかもしれません。

Still another use is to maintain visual space between =item lines. If you specify

もう一つの使用法は、=item 行の間の目に見えるスペースを保守することです。 次のように指定すると:

 =item foo

 =item bar

it will typically get rendered as

典型的には次のようにレンダリングされます:

 foo
 bar

That may be what you want, but if what you really want is

これがあなたの望むものかもしれませんが、本当に望んでいるのが次の場合:

 foo

 bar

you can use Z<> to accomplish that

それを成し遂げるために Z<> を使えます:

 =item foo

 Z<>

 =item bar

たいていの場合、コードフォーマッティングの最初と最後のデリミタとして 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 文は、perl が文の開始を想定している場所には置けますが、文の途中には 置けません; その場合はエラーになります。 実例はあなたの使っているライブラリモジュールにあります。

もし Pod テキストをファイルの末尾に置きたいというのであれば、 __END__ や __DATA__ というカットマークを置き、 さらに最初に現れる Pod コマンドの前に空行を置くことで行うことができます。

  __END__

  =head1 NAME

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

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

Pod を書くためのヒント¶

• The podchecker command is provided for checking Pod syntax for errors and warnings. For example, it checks for completely blank lines in Pod blocks and for unknown commands and formatting codes. You should still also pass your document 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 の分割に完全な空行が使われているかや、 不明なコマンドやフォーマットコードなどをチェックします。 それでも一つまたは複数のトランスレータに通して結果をチェックするか、 結果を印刷してそれをチェックすることをお勧めします。 発見した問題の中には、回避しようと思ったり思わなかったりするような トランスレータのバグもあるでしょう。

• If you're more familiar with writing in HTML than with writing in Pod, you can try your hand at writing documentation in simple HTML, and converting it to Pod with the experimental Pod::HTML2Pod module, (available in CPAN), and looking at the resulting code. The experimental Pod::PXML module in CPAN might also be useful.

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

• Many older Pod translators require the lines before every Pod command and after every Pod command (including "=cut"!) to be a blank line. Having something like this:

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

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

  ...will make such Pod translators completely fail to see the Pod block at all.

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

  Instead, have it like this:

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

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

• Some older Pod translators require paragraphs (including command paragraphs like "=head2 Functions") to be separated by completely empty lines. If you have an apparently empty line with some spaces on it, this might not count as a separator for those translators, and that could cause odd formatting.

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

• Older translators might add wording around an L<> link, so that L<Foo::Bar> may become "the Foo::Bar manpage", for example. So you shouldn't write things like the L<foo> documentation, if you want the translated document to read sensibly. Instead, write the L<Foo::Bar|Foo::Bar> documentation or L<the Foo::Bar documentation|Foo::Bar>, to control how the link comes out.

  古いトランスレータは 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> としてください。

• Going past the 70th column in a verbatim block might be ungracefully wrapped by some formatters.

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

SEE ALSO¶

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

作者¶

Larry Wall, Sean M. Burke