=encoding euc-jp =for comment This document is in Pod format. To read this, use a Pod formatter, like "perldoc perlpod". =head1 NAME X X =begin original perlpod - the Plain Old Documentation format =end original perlpod - Plain Old Documentation フォーマット =head1 DESCRIPTION =begin original Pod is a simple-to-use markup language used for writing documentation for Perl, Perl programs, and Perl modules. =end original Pod は、 Perl、 Perl プログラム、Perl モジュールのための ドキュメントを書くための簡単に使えるマークアップ言語です。 =begin original Translators are available for converting Pod to various formats like plain text, HTML, man pages, and more. =end original Pod からプレーンテキスト、HTML、man ページなどのさまざまなフォーマットに 変換するためのトランスレータがあります。 =begin original Pod markup consists of three basic kinds of paragraphs: L, L, and L. =end original Pod マークアップは 3 種類の段落から構成されます: L, L, L です。 =head2 Ordinary Paragraph X (普通の段落) =begin original Most paragraphs in your documentation will be ordinary blocks of text, like this one. You can simply type in your text without any markup whatsoever, and with just a blank line before and after. When it gets formatted, it will undergo minimal formatting, like being rewrapped, probably put into a proportionally spaced font, and maybe even justified. =end original あなたのドキュメントの段落のほとんどは(これと同じように) 普通のテキストのブロックです。 単に何のマークアップも使わずにテキストを書き、前後に空行を 置きます。 フォーマッティングされるとき、最小限のフォーマッティングが行われます。 再ラッピングや、プロポーショナルフォントでの表示や、 均等割り付けといったことです。 =begin original You can use formatting codes in ordinary paragraphs, for B, I, C, L, and more. Such codes are explained in the "L" section, below. =end original 普通の段落に B<強調> I<イタリック> C<コードスタイル> L<ハイパーリンク|perlfaq> などのフォーマッティングコードを使うことも出来ます。 これらのコードは以下の "L" の 項目で説明します。 =head2 Verbatim Paragraph X X (そのままの段落) =begin original Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped. =end original そのままの段落は、コードブロックや、特別なパースやフォーマッティングが 不要で、ラッピングするべきではないテキストを表現するために用いられます。 =begin original A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else. =end original そのままの段落は空白かタブで始まっているということによって認識されます。 (簡単に言うと、この全ての行は空白かタブで始まっています。) タブは8カラムごとと仮定されてそのまま出力されます。 特殊なフォーマットコードは ありませんから、イタリックにするといったことはできません。\は\で、 その他の意味はありません。 =head2 Command Paragraph X (コマンド段落) =begin original A command paragraph is used for special treatment of whole chunks of text, usually as headings or parts of lists. =end original コマンド段落はテキストの塊全体を特別な扱いをするために用いられます。 普通は見出しやリストとして用いられます。 =begin original All command paragraphs (which are typically only one line long) start with "=", followed by an identifier, followed by arbitrary text that the command can use however it pleases. Currently recognized commands are =end original すべてのコマンド段落(典型的には一行だけからなります)は“=”で始まって その後に識別子が続き、 さらにコマンドをが必要とするテキストが続きます。 現在使えるコマンドは以下の通りです。 =pod =head1 Heading Text =head2 Heading Text =head3 Heading Text =head4 Heading Text =over indentlevel =item stuff =back =begin format =end format =for format text... =encoding type =cut =begin original To explain them each in detail: =end original 以下に詳細を説明します: =over =item C<=head1 I> X<=head1> X<=head2> X<=head3> X<=head4> X X X X =item C<=head2 I> =item C<=head3 I> =item C<=head4 I> =begin original Head1 through head4 produce headings, head1 being the highest level. The text in the rest of this paragraph is the content of the heading. For example: =end original head1 から head4 は見出しを生成します。head1 が最上位です。 この段落の残りのテキストは見出しの内容です。例: =head2 Object Attributes =begin original The text "Object Attributes" comprises the heading there. (Note that head3 and head4 are recent additions, not supported in older Pod translators.) The text in these heading commands can use formatting codes, as seen here: =end original "Object Attributes"というテキストがここでの見出しとなります。 (head3 と head4 は最近追加されたので、古い Pod トランスレータは 対応していません。) これらの見出しコマンドのテキストでは以下のようにフォーマッティング コードを使えます: =head2 Possible Values for C<$/> =begin original Such commands are explained in the "L" section, below. =end original これらのコマンドは以下の "L" で 説明されています。 =item C<=over I> X<=over> X<=item> X<=back> X X X =item C<=item I> =item C<=back> =begin original 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 I 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 I option, it defaults to four. (And some formatters may just ignore whatever I you provide.) In the I in C<=item I>, you may use formatting codes, as seen here: =end original item, over, back はもう少し説明が必要です: "=over" は "=item" を使ったリスト生成や、普通のパラグラフ(の組)を インデントするためのリージョンを開始します。 リストの最後では、それを示すために "=back" を使います。 "=over" の I オプションはどれくらいインデントするかを 示し、一般的には単位は ems (1 em はドキュメントのベースフォントでの"M"の 幅です) か、だいたい同じぐらいの単位です; I オプションが ない場合、デフォルトは 4 です。 (何を I に指定しても無視するフォーマッタもあります。) C<=item I> の I の中では、 以下のようにフォーマッティングコードを使うことができます: =item Using C<$|> to Control Buffering =begin original Such commands are explained in the "L" section, below. =end original これらのコマンドは以下の "L" で 説明されています。 =begin original Note also that there are some basic rules to using "=over" ... "=back" regions: =end original "=over" ... "=back" リージョンを使うためのいくつかの 基本的なルールがあることに注意して下さい。 =over =item * =begin original Don't use "=item"s outside of an "=over" ... "=back" region. =end original "=over" ... "=back" リージョンの外では "=item" は使えません。 =item * =begin original 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. =end original "=over" ... "=back" リージョン内に "=item" が全く現れないのでない限り、 "=over" コマンドの後、最初に書かれるのは "=item" であるべきです。 =item * =begin original Don't put "=headI" commands inside an "=over" ... "=back" region. =end original "=over" ... "=back" リージョンの中で "=headI" は使えません。 =item * =begin original 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. =end original そしておそらくもっとも重要なこととして、item の一貫性を維持してください: 点を出力するためには全ての item に "=item *" を使ってください; 番号付きリストを出力するためには "=item 1.", "=item 2." などを使ってください。 点も番号も付けない場合は "=item foo", "=item bar" などを使ってください。 =begin original If you start with bullets or numbers, stick with them, as formatters use the first "=item" type to decide how to format the list. =end original 点か番号で始めたなら、ずっとそれを使ってください。 フォーマッタは最初の "=item" のタイプを見てリストのフォーマット 方法を決定します。 =back =item C<=cut> X<=cut> X =begin original 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.) =end original Pod ブロックを終了するためには、空行、"=cut"で始まる行、空行を書きます。 これにより Perl (と Pod フォーマッタ) はここから Perl コードが 再開することがわかります。 ("=cut" の前の空行は技術的には不要ですが、多くの古い Pod プロセッサはこれが必要です。) =item C<=pod> X<=pod> X =begin original 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 I 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: =end original "=pod" コマンドはそれ自身ではほとんど何もしませんが、 Perl (と Pod フォーマッタ)に Pod ブロックがここから始まることを示します。 Pod ブロックは I<いずれかの> コマンド段落で開始するので、 "=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 =item C<=begin I> X<=begin> X<=end> X<=for> X X X =item C<=end I> =item C<=for I I> =begin original 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. =end original for, begin, end は、通常の Pod テキストとして解釈されるのではなく、 直接特定のフォーマッタに渡されるべきテキスト/コード/データ、 あるいはその他の特別なものの領域を定義できます。 このフォーマットを使うフォーマットはこの領域を使い、 さもなければ完全に無視します。 =begin original A command "=begin I", some paragraphs, and a command "=end I", mean that the text/data in between is meant for formatters that understand the special format called I. For example, =end original "=begin I" コマンド, いくつかの段落, "=end I" コマンドは、はさまれたテキスト/データが I と呼ばれる特別なフォーマットを理解するフォーマッタ用で あることを意味します。例: =begin html

This is a raw HTML paragraph

=end html =begin original The command "=for I I" specifies that the remainder of just this paragraph (starting right after I) is in that special format. =end original "=for I I" コマンドは、 この段落の残り(I の直後から)が特別なフォーマットであることを 指定します。 =for html

This is a raw HTML paragraph

=begin original This means the same thing as the above "=begin html" ... "=end html" region. =end original これは上記の "=begin html" ... "=end html" リージョンと同じ意味です。 =begin original 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 inbetween. (Note that there still must be a blank line after the "=begin" command and a blank line before the "=end" command. =end original これは、"=for" では 1 段落のテキストのみを指定できます (つまり "=foo targetname text...")が、 "=begin targetname" ... "=end targetname" ではその間に好きな量のテキストを 指定できます。 ("=begin" コマンドの直後と "=end" コマンドの直前に空行が必要であることに 注意してください。) =begin original Here are some examples of how to use these: =end original これを使った例を幾つか挙げましょう。 =begin html
Figure 1.

=end html =begin text --------------- | foo | | bar | --------------- ^^^^ Figure 1. ^^^^ =end text =begin original 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.) =end original 現在使うことのできるフォーマット名は"roff", "man", "latex", "tex", "text", "html"です(一部のフォーマッタは他のものの別名と して扱われます)。 =begin original 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: =end original フォーマット名"comment" は(おそらくはあなた自身のための)単なるメモで、 フォーマッティングした Pod ドキュメントには現れるべきでない場合に 用いられる一般的な名称です。 =for comment Make sure that all the available options are documented! =begin original Some I will require a leading colon (as in C<"=for :formatname">, or C<"=begin :formatname" ... "=end :formatname">), to signal that the text is not raw data, but instead I 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). =end original フォーマッタの中には、 テキストが生のデータでないけれども、Pod テキストではある (つまりフォマッティングコードを含むことがある)ことを知らせるために C<"=for :formatname"> や C<"=begin :formatname" ... "=end :formatname">) の ように I の先頭にコロンが必要な場合もあります (通常の段落ではなく、脚注としてフォーマットするものなどです)。 =item C<=encoding I> X<=encoding> X =begin original 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 or Latin-1, then put a C<=encoding I> command early in the document so that pod formatters will know how to decode the document. For I, use a name recognized by the L module. Examples: =end original このコマンドはドキュメントのエンコーディングを決定するのに使われます。 ほとんどのユーザーには不要なものです; しかしもしエンコーディングが US-ASCII か Latin-1 でない場合、 C<=encoding I> コマンドをドキュメントの始めの方に 置いておくことで、pod フォーマッタがドキュメントをどのように デコードすればよいかを知ることができます。 I に関しては、L で認識される 名前を使ってください。例: =encoding utf8 =encoding koi8-r =encoding ShiftJIS =encoding big5 =back =begin original C<=encoding> affects the whole document, and must occur only once. =end original C<=encoding> は文書全体に影響を与え、一度だけしか使えません。 =begin original And don't forget, when using any other command, that the command lasts up until the end of its I, not its line. So in the examples below, you can see that every command needs the blank line after it, to end its paragraph. =end original そして忘れないで欲しいことは、これらのコマンドを使った場合、その コマンドが影響するのはコマンドが置かれた行ではなく、 コマンドがあるI<段落>の終端までだということです。ですから先の例には、 各コマンドの後ろに段落を終了させるために空行があるのです。 =begin original Some examples of lists include: =end original 幾つか例を挙げましょう: =over =item * First item =item * Second item =back =over =item Foo() Description of Foo function =item Bar() Description of Bar function =back =head2 Formatting Codes X X X X (フォーマッティングコード) =begin original In ordinary paragraphs and in some command paragraphs, various formatting codes (a.k.a. "interior sequences") can be used: =end original 普通の段落と、いくつかのコマンド段落では、さまざまな フォーマッティングコード(またの名を"内部シーケンス")を使うことができます: =for comment "interior sequences" is such an opaque term. Prefer "formatting codes" instead. =over =item CtextE> -- italic text X X<< IZ<><> >> X X =begin original Used for emphasis ("Ccareful!E>") and parameters ("CLABELE>") =end original 強調 ("Ccareful!E>") とパラメータ ("CLABELE>") のために使います。 =item CtextE> -- bold text X X<< BZ<><> >> X X =begin original Used for switches ("C-nE switch>"), programs ("CchfnE for that>"), emphasis ("Ccareful!E>"), and so on ("CautovivificationE>"). =end original スイッチ("C-nE switch>"), プログラム("CchfnE for that>"), 強調 ("Ccareful!E>"), その他 ("CautovivificationE>")の ために使います。 =item CcodeE> -- code text X X<< CZ<><> >> X X =begin original Renders code in a typewriter font, or gives some other indication that this represents program text ("Cgmtime($^T)E>") or some other form of computerese ("Cdrwxr-xr-xE>"). =end original コードをタイプライタフォントや、 あるいはプログラムテキスト("Cgmtime($^T)E>")や その他のコンピュータ用語("Cdrwxr-xr-xE>") を 表現していることを示すその他の形でレンダリングされます。 =item CnameE> -- a hyperlink X X<< LZ<><> >> X X =begin original There are various syntaxes, listed below. In the syntaxes given, C, C, and C
cannot contain the characters '/' and '|'; and any '<' or '>' should be matched. =end original 以下のようにさまざまな文法があります。 文法の中で、C, C, C
に '/' と '|' を含むことはできません。 また、'<' や '>' は対応しなければなりません。 =over =item * =begin original CnameE> =end original CnameE> =begin original Link to a Perl manual page (e.g., CNet::PingE>). Note that C should not contain spaces. This syntax is also occasionally used for references to Unix man pages, as in Ccrontab(5)E>. =end original Perl マニュアルページへのリンクを設定します(e.g., CNet::PingE>)。 C に空白を含むことができないことに注意してください。 この文法は Ccrontab(5)E> の形で Unix man ページへの リファレンスのために使われることもあります。 =item * =begin original Cname/"sec"E> or Cname/secE> =end original Cname/"sec"E> または Cname/secE> =begin original Link to a section in other manual page. E.g., Cperlsyn/"For Loops"E> =end original 他のマニュアルページへのある項目へのリンクを設定します。 例: Cperlsyn/"For Loops"E> =item * =begin original C/"sec"E> or C/secE> =end original C/"sec"E> または C/secE> =begin original Link to a section in this manual page. E.g., C/"Object Methods"E> =end original このマニュアルページへのある項目へのリンクを設定します。 例: C/"Object Methods"E> =back =begin original A section is started by the named heading or item. For example, Cperlvar/$.E> or Cperlvar/"$."E> both link to the section started by "C<=item $.>" in perlvar. And Cperlsyn/For LoopsE> or Cperlsyn/"For Loops"E> both link to the section started by "C<=head2 For Loops>" in perlsyn. =end original セクションは名前付きの見出しか item で始まります。 たとえば、Cperlvar/$.E> と Cperlvar/"$."E> は 両方とも perlvar の "C<=item $.>" で始まるセクションへリンクします。 Cperlsyn/For LoopsE> と Cperlsyn/"For Loops"E> は 両方とも perlsyn の "C<=head2 For Loops>" で始まるセクションにリンクします。 =begin original To control what text is used for display, you use "Ctext|...E>", as in: =end original どんなテキストが表示に用いられるかを制御するためには、 "Ctext|...E>" を使ってください。つまり: =over =item * =begin original Ctext|nameE> =end original Ctext|nameE> =begin original Link this text to that manual page. E.g., CPerl Error Messages|perldiagE> =end original このテキストに指定したマニュアルページへのリンクを設定します。 例: CPerl Error Messages|perldiagE> =item * =begin original Ctext|name/"sec"E> or Ctext|name/secE> =end original Ctext|name/"sec"E> または Ctext|name/secE> =begin original Link this text to that section in that manual page. E.g., Cpostfix "if"|perlsyn/"Statement Modifiers"E> =end original このテキストに指定したマニュアルページのある項目へのリンクを設定します。 例: Cpostfix "if"|perlsyn/"Statement Modifiers"E> =item * =begin original Ctext|/"sec"E> or Ctext|/secE> or Ctext|"sec"E> =end original Ctext|/"sec"E> または Ctext|/secE> または Ctext|"sec"E> =begin original Link this text to that section in this manual page. E.g., Cthe various attributes|/"Member Data"E> =end original このテキストにこのマニュアルページのある項目へのリンクを設定します。 例: Cthe various attributes|/"Member Data"E> =back =begin original Or you can link to a web page: =end original web ページにリンクを設定することもできます。 =over =item * Cscheme:...E> Ctext|scheme:...E> =begin original Links to an absolute URL. For example, Chttp://www.perl.org/E> or CThe Perl Home Page|http://www.perl.org/E>. =end original 絶対 URL へのリンクです。 例えば、Chttp://www.perl.org/E> や CThe Perl Home Page|http://www.perl.org/E>。 =back =item CescapeE> -- a character escape X X<< EZ<><> >> X X =begin original Very similar to HTML/XML C<&I;> "entity references": =end original HTML/XML C<&I;> "実体参照"ととても似ています。 =over =item * =begin original CltE> -- a literal E (less than) =end original CltE> -- リテラルの E (less than) =item * =begin original CgtE> -- a literal E (greater than) =end original CgtE> -- リテラルの E (greater than) =item * =begin original CverbarE> -- a literal | (Itical I) =end original CverbarE> -- リテラルの | (Itical I) =item * =begin original CsolE> = a literal / (Iidus) =end original CsolE> = リテラルの / (Iidus) =begin original The above four are optional except in other formatting codes, notably C...E>, and when preceded by a capital letter. =end original 上記の 4 つは他のフォーマッティングコードの中 (特に C...E>)と、大文字が前につけられた場合を除いて オプションです。 =item * =begin original ChtmlnameE> =end original ChtmlnameE> =begin original Some non-numeric HTML entity name, such as CeacuteE>, meaning the same thing as C<é> in HTML -- i.e., a lowercase e with an acute (/-shaped) accent. =end original いくつかの数値でない HTML エンティティ名(CeacuteE> のようなもの)は HTML での C<é> と同じ意味です -- つまり、 acute (/-の形の) アクサン付きの小文字の e です。 =item * =begin original CnumberE> =end original CnumberE> =begin original The ASCII/Latin-1/Unicode character with that number. A leading "0x" means that I is hex, as in C0x201EE>. A leading "0" means that I is octal, as in C075E>. Otherwise I is interpreted as being in decimal, as in C181E>. =end original この番号の ASCII/Latin-1/Unicode 文字です。 C0x201EE> のように先頭に "0x" があると I は 16 進数です。 C075E> のように先頭に "0" があると I は 8 進数です。 C181E> のようにそれ以外では I は 10 進数と解釈されます。 =begin original 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 characters, like rendering CeacuteE> as just a plain "e".) =end original 古い Pod フォーマッタは 8 進数や 16 進数のエスケープを認識しない 可能性があり、また多くのフォーマッタは 255 以上の文字を 正しくレンダリングできるかわからないことに注意してください。 (Latin-1 文字ですら正しくレンダリングできないフォーマッタもあります。 例えば CeacuteE> を普通の "e" にレンダリングします。) =back =item CfilenameE> -- used for filenames X X<< FZ<><> >> X X =begin original Typically displayed in italics. Example: "C.cshrcE>" =end original 典型的にはイタリックで表示されます。例: "C.cshrcE>" =item CtextE> -- text contains non-breaking spaces X X<< SZ<><> >> X X =begin original This means that the words in I should not be broken across lines. Example: S$x ? $y : $zE>>. =end original これは I の内容が行をまたがないことを意味します。 例: $x ? $y : $zE>> =item Ctopic nameE> -- an index entry X X<< XZ<><> >> X X =begin original This is ignored by most formatters, but some may use it for building indexes. It always renders as empty-string. Example: Cabsolutizing relative URLsE> =end original これは多くのフォーマッタでは無視されますが、 インデックスを作成するのに使われることもあります。 常に空文字列としてレンダリングされます。 例: Cabsolutizing relative URLsE> =item CE> -- a null (zero-effect) formatting code X X<< ZZ<><> >> X X =begin original This is rarely used. It's one way to get around using an EE...E code sometimes. For example, instead of "CltE3>" (for "NE3") you could write "CEE3>" (the "ZEE" breaks up the "N" and the "E" so they can't be considered the part of a (fictitious) "NE...E" code. =end original これはまれに用いられます。 ときどき EE...E コードを使う方法の一つです。 例えば、("NE3" のために) "CltE3>" の代わりに "CEE3>" と書けます。 (the "ZEE" は "N" と "E" を分解するので "NE...E" の一部と(間違って)解釈されることはありません。) =for comment This was formerly explained as a "zero-width character". But it in most parser models, it parses to nothing at all, as opposed to parsing as if it were a E or E, which are REAL zero-width characters. So "width" and "character" are exactly the wrong words. =back =begin original Most of the time, you will need only a single set of angle brackets to delimit the beginning and end of formatting codes. However, sometimes you will want to put a real right angle bracket (a greater-than sign, '>') inside of a formatting code. This is particularly common when using a formatting code 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 code: =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 single ">" to be escaped. With the Pod formatters that are standard starting with perl5.5.660 (circa 2000), doubled angle brackets ("<<" and ">>") may be used I For example, the following will do the trick: X =end original より読みやすく、そしておそらくより"明白な"方法は、別のデリミタを 使って、単独の">"をエスケープしなくてもいいようにする方法です。 Perl5.5.660 (2000 年頃) 以降の Pod フォーマッタでは、2 個の山括弧 ("<<" and ">>")が使えます。 但し、I<開始デリミタの直後と終了デリミタの直前に空白があるときだけ>です! 例えば、以下はそのトリックを使っています: X 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. (The whitespace is ignored.) So the following will also work: X =end original 実際のところ、開始デリミタと終了デリミタの数さえ合っており、 開始デリミタの最後の '<' の直後と 終了デリミタの最初の '>' の 直前に空白が入っていれば、 山括弧の数はいくつでもかまいません。 (空白は無視されます。) 従って、以下のものも正しく動作します: X C<<< $a <=> $b >>> C<<<< $a <=> $b >>>> =begin original And they all mean exactly the same as this: =end original そしてこれらは全て以下と全く同じ意味です: C<$a E=E $b> =begin original The multiple-bracket form does not affect the interpretation of the contents of the formatting code, only how it must end. That means that the examples above are also exactly the same as this: =end original 複数山かっこ形式はフォーマッティングコードの中身の解釈には影響せず、 どのように終わらなければならないかにのみ影響を与えます。 これは、上述の例は以下と正確に同じということです: C<< $a E=E $b >> =begin original As a further example, this means that if you wanted to put these bits of code in C (code) style: =end original さらなる例として、C (コード) スタイルのコードの断片を書きたいとすると: open(X, ">>thing.dat") || die $! $foo->bar(); =begin original you could do it like so: =end original 以下のように書くことができます: C<<< open(X, ">>thing.dat") || die $! >>> C<< $foo->bar(); >> =begin original which is presumably easier to read than the old way: =end original これはおそらく以下のような古い書き方より読みやすいです: CEthing.dat") || die $!> C<$foo-Ebar();> =begin original This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), and any other pod2xxx or Pod::Xxxx translators that use Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later. =end original これは現在のところ pod2text (Pod::Text), pod2man (Pod::Man), および Pod::Parser 1.093 以降、Pod::Tree 1.02 以降を使用しているその他の pod2xxx と Pod::Xxxx が対応しています。 =head2 The Intent X (目的) =begin original The intent is simplicity of use, not power of expression. Paragraphs look like paragraphs (block format), so that they stand out visually, and so that I could run them through C easily to reformat them (that's F7 in my version of B, or Esc Q in my version of B). I wanted the translator to always leave the C<'> and C<`> and C<"> quotes alone, in verbatim mode, so I could slurp in a working program, shift it over four spaces, and have it print out, er, verbatim. And presumably in a monospace font. =end original 表現力ではなく簡単に使えるものを目指しています。 段落は段落らしく(矩形に)見えて欲しいので、見た目に目立ち、 C で簡単に再整形できるようになっています (私の B では F7 に、B では Esc Q になっています)。 私が求めていたのは、verbatim モードでは C<'> や C<`> や C<"> のクォートを そのままにしておいて欲しかったのです。そうすれば、作りかけの プログラムを放り込んで、4 カラムずらして、 それをそのまま印刷すればいいのです。たぶん、固定幅のフォントで。 =begin original The Pod format is not necessarily sufficient for writing a book. Pod is just meant to be an idiot-proof common source for nroff, HTML, TeX, and other markup languages, as used for online documentation. Translators exist for B, B, B (that's for nroff(1) and troff(1)), B, and B. Various others are available in CPAN. =end original Pod フォーマットは本を作るのに十分である必要はありません。 Pod はただ、オンラインドキュメントに使うnroff やTeXといったマークアップ言語の ための、誰にでも使える共通のソースを提供しています。 現在あるトランスレータには B, B, B (nroff(1) や troff(1)用), B, Bがあります。 他にもさまざまなものが CPAN にあります。 =head2 Embedding Pods in Perl Modules X (Perl モジュールへの pod の埋め込み) =begin original You can embed Pod documentation in your Perl modules and scripts. Start your documentation with an empty line, a "=head1" command at the beginning, and end it with a "=cut" command and an empty line. Perl will ignore the Pod text. See any of the supplied library modules for examples. If you're going to put your Pod at the end of the file, and you're using an __END__ or __DATA__ cut mark, make sure to put an empty line there before the first Pod command. =end original Perl モジュールとスクリプトに Pod ドキュメントを埋め込むことができます。 ドキュメントを空行および“=head1”コマンドで始め、“=cut”と空行で終えます。 Perl はこのような Pod テキストを無視します。 実例はあなたの使っているライブラリモジュールにあります。 もし Pod テキストをファイルの末尾に置きたいというのであれば、 __END__ や __DATA__ というカットマークを置き、 さらに最初に現れる Pod コマンドの前に空行を置くことで行うことができます。 __END__ =head1 NAME Time::Local - efficiently compute time from local and GMT time =begin original Without that empty line before the "=head1", many translators wouldn't have recognized the "=head1" as starting a Pod block. =end original "=head1" の前に空行がない場合、多くのトランスレータは"=head1"が Pod ブロックの開始と認識しません。 =head2 Hints for Writing Pod (Pod を書くためのヒント) =over =item * X X =begin original The B 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. =end original B コマンドは Pod の文法に関するエラーと警告を チェックするために提供されています。 例えば、Pod の分割に完全な空行が使われているかや、 不明なコマンドやフォーマットコードなどをチェックします。 それでも一つまたは複数のトランスレータに通して結果をチェックするか、 結果を印刷してそれをチェックすることをお勧めします。 発見した問題の中には、回避しようと思ったり思わなかったりするような トランスレータのバグもあるでしょう。 =item * =begin original 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 L module, (available in CPAN), and looking at the resulting code. The experimental L module in CPAN might also be useful. =end original もしあなたが Pod を書くことより HTML を書くことに慣れているなら、 単純な HTML でドキュメントを書き、実験的な L モジュール (CPAN にあります)を使って Pod に変換することを試すこともできます。 CPAN にある 実験的な L も有用です。 =item * =begin original 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: =end original 多くの古い Pod トランスレータは全ての Pod コマンド("=cut" を含みます!)の 前後に空行が必要です。以下のように書くと: # - - - - - - - - - - - - =item $firecracker->boom() This noisily detonates the firecracker object. =cut sub boom { ... =begin original ...will make such Pod translators completely fail to see the Pod block at all. =end original そのような Pod トランスレータは Pod ブロックの発見に完全に 失敗するでしょう。 =begin original Instead, have it like this: =end original 代わりに、以下のように書いてください: # - - - - - - - - - - - - =item $firecracker->boom() This noisily detonates the firecracker object. =cut sub boom { ... =item * =begin original Some older Pod translators require paragraphs (including command paragraphs like "=head2 Functions") to be separated by I 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. =end original 古い Pod トランスレータには、段落("=head2 Functions" のような コマンド段落も含みます)の分割にI<完全な>空行を必要とするものもあります。 空白の入った見た目空行のようなものを入れると、 セパレータとして扱われずに出力がおかしくなるかもしれません。 =item * =begin original Older translators might add wording around an LEE link, so that CFoo::BarE> may become "the Foo::Bar manpage", for example. So you shouldn't write things like CfooE documentation>, if you want the translated document to read sensibly. Instead, write CFoo::Bar|Foo::BarE documentation> or Cthe Foo::Bar documentation|Foo::BarE>, to control how the link comes out. =end original 古いトランスレータは LEE リンクに語の追加を行う場合があります。 このため、たとえば CFoo::BarE> は“the Foo::Bar manpage”と なります(詳しくはBを参照)。 したがって、あなたは変換されたドキュメントを読みやすいものにするために、 CfooE documentation>という書き方はすべきではありません。 代わりに CFoo::Bar|Foo::BarE documentation> と 書くか、どのようにリンクが出来るかを制御するために Cthe Foo::Bar documentation|Foo::BarE> としてください。 =item * =begin original Going past the 70th column in a verbatim block might be ungracefully wrapped by some formatters. =end original そのままのブロックで 70 文字を越えると、フォーマッタによっては 見苦しいラッピングが行われるかもしれません。 =back =head1 SEE ALSO L, L, L, L, L, L, L. =head1 AUTHOR Larry Wall, Sean M. Burke =cut =begin meta Translate: 吉村 寿人 Update: SHIRAKATA Kentaro Status: completed =end meta