argra****@users*****
argra****@users*****
2012年 2月 17日 (金) 05:51:19 JST
Index: docs/perl/5.12.1/perlpodspec.pod
diff -u docs/perl/5.12.1/perlpodspec.pod:1.8 docs/perl/5.12.1/perlpodspec.pod:1.9
--- docs/perl/5.12.1/perlpodspec.pod:1.8 Mon Sep 5 06:03:27 2011
+++ docs/perl/5.12.1/perlpodspec.pod Fri Feb 17 05:51:18 2012
@@ -303,13 +303,10 @@
=end original
言い換えると、"head1" の Pod 処理ハンドラは、
-apply the
-same processing to "Did You Remember to CE<lt>use strict;>?" that it
-would to an ordinary paragraph (i.e., formatting codes like
-"CE<lt>...>") are parsed and presumably formatted appropriately, and
-whitespace in the form of literal spaces and/or tabs is not
-significant.
-(TBT)
+"Did You Remember to CE<lt>use strict;>?" を、通常の段落
+(つまり、"CE<lt>...>" のようなフォーマッティングコード) が
+パースされ、おそらくは適切にフォーマットされ、リテラルのスペースや
+タブといった形の空白は無視されるというのと同じ処理を適用します。
=item *
@@ -357,12 +354,10 @@
=end original
B<通常の段落> (ordinary paragraph)。
-A paragraph is an ordinary paragraph
-if its first line matches neither C<m/\A=[a-zA-Z]/> nor
-C<m/\A[ \t]/>, I<and> if it's not inside a "=begin I<identifier>",
-... "=end I<identifier>" sequence unless "I<identifier>" begins with
-a colon (":").
-(TBT)
+最初の行が C<m/\A=[a-zA-Z]/> にも C<m/\A[ \t]/> にもマッチングせず、
+I<かつ>、コロン (":") 以外で始まる "I<identifier>" に対する
+"=begin I<identifier>" ... "=end I<identifier>" シーケンスの内側で
+ない段落は、通常の段落です。
=item *
@@ -433,13 +428,12 @@
=end original
-The "=begin I<identifier>" ... "=end I<identifier>" commands stop
-paragraphs that they surround from being parsed as ordinary or verbatim
-paragraphs, if I<identifier> doesn't begin with a colon.
+"=begin I<identifier>" ... "=end I<identifier>" コマンドは、
+I<identifier> がコロンで始まっていないなら、その内部の段落を、
+通常の段落やそのままの段落として解釈するのを停止させます。
これは
L</About Data Paragraphs and "=beginE<sol>=end" Regions> の章で
詳細に議論されています。
-(TBT)
=head1 Pod Commands
@@ -510,10 +504,10 @@
=end original
-This command indicates that this line is the end of this previously
-started Pod block. If there is any text after "=cut" on the line, it must be
-ignored. Examples:
-(TBT)
+このコマンドは、この行が Pod ブロックの終わりであることを示します。
+この行の "=cut" の後にテキストがあれば、これは
+無視しなければなりません(must)。
+例:
=cut
@@ -548,8 +542,8 @@
=end original
-This command indicates that this is the start of a list/indent
-region. If there is any text following the "=over", it must consist
+このコマンドは、これがリスト/インデント領域の開始であることを示します。
+If there is any text following the "=over", it must consist
of only a nonzero positive numeral. The semantics of this numeral is
explained in the L</"About =over...=back Regions"> section, further
below. Formatting codes are not expanded. Examples:
@@ -573,7 +567,8 @@
=end original
-This command indicates that an item in a list begins here. Formatting
+このコマンドは、ここからリストの中のアイテムが始まることを示します。
+Formatting
codes are processed. The semantics of the (optional) text in the
remainder of this paragraph are
explained in the L</"About =over...=back Regions"> section, further
@@ -731,15 +726,14 @@
=end original
-This command, which should occur early in the document (at least
-before any non-US-ASCII data!), declares that this document is
-encoded in the encoding I<encodingname>, which must be
-an encoding name that L<Encode> recognizes. (Encode's list
-of supported encodings, in L<Encode::Supported>, is useful here.)
-If the Pod parser cannot decode the declared encoding, it
-should emit a warning and may abort parsing the document
-altogether.
-(TBT)
+このコマンドは(文書の最初の方に(少なくとも非 US-ASCII データが出てくる
+前に!)書くべきです(should))、この文書がエンコーディング I<encodingname> で
+エンコードされていることを宣言します; これは L<Encode> が認識する
+エンコーディングでなければなりません(must)。
+(L<Encode::Supported> にある、Encode が対応するエンコーディングの一覧が
+便利です。)
+Pod パーサが宣言されたエンコーディングでデコードできない場合は、
+警告を出力するべき(should)で、文書のパースを中断してもかまいません(may)。
=begin original
@@ -1083,7 +1077,6 @@
L<perlpod/"Formatting Codes"> と、
L</Notes on Implementing Pod Processors> にあるいくつかのポイントを
参照してください。
-(TBT)
=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
@@ -1340,13 +1333,13 @@
=end original
-Since Perl recognizes a Unicode Byte Order Mark at the start of files
-as signaling that the file is Unicode encoded as in UTF-16 (whether
-big-endian or little-endian) or UTF-8, Pod parsers should do the
-same. Otherwise, the character encoding should be understood as
-being UTF-8 if the first highbit byte sequence in the file seems
-valid as a UTF-8 sequence, or otherwise as Latin-1.
-(TBT)
+Perl は、ファイルの先頭に付けることでファイルが UTF-16
+(ビッグエンディアンかリトルエンディアンか)あるいは UTF-8 かを
+示すためにファイルの先頭に付けるバイト順マーク(Byte Order Mark)を
+認識するので、Pod パーサも同様であるべきです(should)。
+さもなければ、ファイル中の最初の最上位ビットの立ったバイトシーケンスが
+UTF-8 シーケンスとして有効であるように見える場合は文字エンコーディング
+UTF-8 と、そうでなければ Latin-1 と認識するべきです(should)。
=begin original
@@ -1378,7 +1371,8 @@
=end original
-The well known Unicode Byte Order Marks are as follows: if the
+よく知られているバイト順マークには以下のものがあります:
+if the
file begins with the two literal byte values 0xFE 0xFF, this is
the BOM for big-endian UTF-16. If the file begins with the two
literal byte value 0xFF 0xFE, this is the BOM for little-endian
@@ -1546,9 +1540,10 @@
=end original
-Pod parsers I<may> emit warnings or error messages ("Unknown E code
-EE<lt>zslig>!") to STDERR (whether through printing to STDERR, or
-C<warn>ing/C<carp>ing, or C<die>ing/C<croak>ing), but I<must> allow
+Pod パーサは警告やエラーメッセージ ("Unknown E code EE<lt>zslig>!") を
+(STDERR に print するか C<warn> や C<carp> を使うか C<die> や C<croak> を
+使うかに関わらず) STDERR に出力しても I<かまいません> (may) が、
+but I<must> allow
suppressing all such STDERR output, and instead allow an option for
reporting errors/warnings
in some other way, whether by triggering a callback, or noting errors
@@ -1593,10 +1588,11 @@
=end original
-In paragraphs where formatting codes (like EE<lt>...>, BE<lt>...>)
-are understood (i.e., I<not> verbatim paragraphs, but I<including>
-ordinary paragraphs, and command paragraphs that produce renderable
-text, like "=head1"), literal whitespace should generally be considered
+(EE<lt>...>, BE<lt>...> のような)フォーマッティングコードを理解する
+段落 (つまり、そのままの段落は I<含みません> が、通常の段落および
+"=head1" のようなレンダリングされるテキストを出力するコマンド段落を
+I<含みます>)、
+literal whitespace should generally be considered
"insignificant", in that one literal space has the same meaning as any
(nonzero) number of literal spaces, literal newlines, and literal tabs
(as long as this produces no blank lines, since those would terminate
@@ -1621,14 +1617,14 @@
=end original
-Pod parsers should not, by default, try to coerce apostrophe (') and
-quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to
-turn backtick (`) into anything else but a single backtick character
-(distinct from an open quote character!), nor "--" into anything but
-two minus signs. They I<must never> do any of those things to text
-in CE<lt>...> formatting codes, and never I<ever> to text in verbatim
-paragraphs.
-(TBT)
+Pod パーサはデフォルトでは、アポストロフィ (') とクォート (") を
+スマートクォート (小さい 9's, 66's, 99's, など)にしようとしたり、
+逆クォート (`) を(開きクォート文字と区別するために!)単一の
+逆クォート文字以外に変えようとしたり、"--" を二つのマイナス記号以外に
+変えようとするべきではありません(should not)。
+これらを CE<lt>...> 中のテキストには I<決して> 行っては
+いけません(must not)し、そのままの段落のテキストには I<決して決して>
+行ってはいけません(must not)。
=item *
@@ -1643,14 +1639,12 @@
=end original
-When rendering Pod to a format that has two kinds of hyphens (-), one
-that's a non-breaking hyphen, and another that's a breakable hyphen
-(as in "object-oriented", which can be split across lines as
-"object-", newline, "oriented"),
+Pod を、改行なしのハイフン (-) と改行可能なハイフン
+("object-oriented" のようなときに、"object-"、改行、"oriented" と
+分割できるもの) の 2 種類があるフォーマットにレンダリングするときは、
フォーマッタは一般的に "-" を改行なしのハイフンに変換することが
推奨されますが、これらの一部を改行するハイフンに変換するための
発見的手法を適用してもかまいません(may)。
-(TBT)
=item *
@@ -1841,10 +1835,9 @@
=end original
-Characters in Pod documents may be conveyed either as literals, or by
-number in EE<lt>n> codes, or by an equivalent mnemonic, as in
-EE<lt>eacute> which is exactly equivalent to EE<lt>233>.
-(TBT)
+Pod 文書中の文字は、リテラル、EE<lt>n> コード、(EE<lt>233> と等価な
+EE<lt>eacute> のように) 等価なニーモニック、のいずれで伝達しても
+かまいません(may)。
=begin original
@@ -1888,11 +1881,9 @@
=end original
-Be warned
-that some formatters cannot reliably render characters outside 32-126;
-and many are able to handle 32-126 and 160-255, but nothing above
-255.
-(TBT)
+一部のフォーマッタは 32-126 の範囲外の文字を確実にレンダリングすることが
+出来ず、多くのフォーマッタは 32-126 と 160-255 は扱えるものの、
+255 を超える文字は扱えないことを警告しておきます。
=item *
@@ -1999,16 +1990,17 @@
=end original
-Note that in all cases of "EE<lt>whatever>", I<whatever> (whether
-an htmlname, or a number in any base) must consist only of
-alphanumeric characters -- that is, I<whatever> must watch
-C<m/\A\w+\z/>. So "EE<lt> 0 1 2 3 >" is invalid, because
-it contains spaces, which aren't alphanumeric characters. This
-presumably does not I<need> special treatment by a Pod processor;
-" 0 1 2 3 " doesn't look like a number in any base, so it would
-presumably be looked up in the table of HTML-like names. Since
-there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ",
-this will be treated as an error. However, Pod processors may
+"EE<lt>whatever>" 形式の全ての場合において、I<whatever> (html 名でも
+どの基数の数値でも) は英数字のみから構成されていなければなりません(must) --
+つまり、I<whatever> は C<m/\A\w+\z/> にマッチングしなければなりません。
+つまり、"EE<lt> 0 1 2 3 >" は不正です; これには空白が含まれていて、
+空白は英数字ではないからです。
+これはおそらく Pod プロセッサによる特別扱いは I<必要ありません>;
+" 0 1 2 3 " はどの基数でも数値のようには見えないので、おそらく HTML 風の
+名前のテーブルを探します。
+" 0 1 2 3 " と呼ばれる HTML 風の実体はない(そしてあり得ない)ので、
+これはエラーとして扱われます。
+However, Pod processors may
treat "EE<lt> 0 1 2 3 >" or "EE<lt>e-acute>" as I<syntactically>
invalid, potentially earning a different error message than the
error message (or warning, or event) generated by a merely unknown
@@ -2028,11 +2020,11 @@
=end original
-Note that EE<lt>number> I<must not> be interpreted as simply
-"codepoint I<number> in the current/native character set". It always
-means only "the character represented by codepoint I<number> in
-Unicode." (This is identical to the semantics of &#I<number>; in XML.)
-(TBT)
+EE<lt>number> は単に「現在の/ネイティブな文字集合における符号位置
+I<number>」と I<扱ってはいけない> (must not) ことに注意してください。
+これは常に「Unicode で符号位置 I<number> として表現される文字」という
+意味しかありません。
+(これは XML での &#I<number>; の意味論と同じです。)
=begin original
@@ -2213,7 +2205,7 @@
=end original
-は、以下のようにレンダリングされます:
+は、以下のようにレンダリングされるでしょう:
"magic is enabled if you set C<$Currency> to 'I<?>'" または
"magic is enabled if you set C<$Currency> to 'B<[euro]>'" または
"magic is enabled if you set C<$Currency> to '[x20AC]' など。
@@ -2240,11 +2232,11 @@
=end original
-EE<lt>...> may freely appear in any formatting code (other than
-in another EE<lt>...> or in an ZE<lt>>). That is, "XE<lt>The
-EE<lt>euro>1,000,000 Solution>" is valid, as is "LE<lt>The
-EE<lt>euro>1,000,000 Solution|Million::Euros>".
-(TBT)
+EE<lt>...> は (他の EE<lt>...> および ZE<lt>> の中を除く) 任意の
+フォーマッティングコードの中に自由に現れることができます(may)。
+つまり、"XE<lt>The EE<lt>euro>1,000,000 Solution>" は、
+"LE<lt>The EE<lt>euro>1,000,000 Solution|Million::Euros>" と同様
+有効ということです。
=item *
@@ -2268,14 +2260,14 @@
=end original
-Some Pod formatters output to formats that implement non-breaking
-spaces as an individual character (which I'll call "NBSP"), and
-others output to formats that implement non-breaking spaces just as
-spaces wrapped in a "don't break this across lines" code. Note that
-at the level of Pod, both sorts of codes can occur: Pod can contain a
-NBSP character (whether as a literal, or as a "EE<lt>160>" or
-"EE<lt>nbsp>" code); and Pod can contain "SE<lt>foo
-IE<lt>barE<gt> baz>" codes, where "mere spaces" (character 32) in
+Pod フォーマッタによっては、改行なし空白を独立した文字 (ここでは
+"NBSP" と呼ぶことにします) として実装しているフォーマットへ出力したり、
+改行なし空白を「この線の場所で改行しない」コードでラップしている
+フォーマットに出力したりします。
+Pod のレベルでは、どちらのコードもあり得ます: Pod は
+(リテラル、"EE<lt>160>"、"EE<lt>nbsp>"という形で) NBSP 文字を
+含めることもできます; そして Pod は "SE<lt>foo IE<lt>barE<gt> baz>" という
+コードを含むことができます; where "mere spaces" (character 32) in
such codes are taken to represent non-breaking spaces. Pod
parsers should consider supporting the optional parsing of "SE<lt>foo
IE<lt>barE<gt> baz>" as if it were
@@ -2397,7 +2389,7 @@
=end original
-For example:
+例えば:
(TBT)
sigE<shy>action
@@ -2470,9 +2462,10 @@
=end original
-Throughout this document, "Pod" has been the preferred spelling for
-the name of the documentation format. One may also use "POD" or
-"pod". For the documentation that is (typically) in the Pod
+この文書を通じて、"Pod" は文書フォーマットの名前として使われている
+綴りです。
+"POD" や "pod" を使う人もいるかもしれません。
+For the documentation that is (typically) in the Pod
format, you may use "pod", or "Pod", or "POD". Understanding these
distinctions is useful; but obsessing over how to spell them, usually
is not.
@@ -2482,6 +2475,8 @@
=head1 About LE<lt>...E<gt> Codes
+(LE<lt>...E<gt> コードについて)
+
=begin original
As you can tell from a glance at L<perlpod|perlpod>, the LE<lt>...>
@@ -2491,11 +2486,10 @@
=end original
-As you can tell from a glance at L<perlpod|perlpod>, the LE<lt>...>
-code is the most complex of the Pod formatting codes. The points below
-will hopefully clarify what it means and how processors should deal
-with it.
-(TBT)
+L<perlpod|perlpod> をちらっと見るだけでわかることは、LE<lt>...> コードは
+Pod フォーマッティングコードの中で最も複雑であると言うことです。
+以下に示すポイントは、これが何を意味し、プロセッサがこれを
+どのように扱うべきかをできれば明確化しようとするものです。
=over
@@ -2508,14 +2502,15 @@
=end original
-In parsing an LE<lt>...> code, Pod parsers must distinguish at least
-four attributes:
-(TBT)
+LE<lt>...> コードをパースするときに、Pod パーサは少なくとも四つの
+属性を区別しなければなりません(must):
=over
=item First:
+(第一:)
+
=begin original
The link-text. If there is none, this must be undef. (E.g., in
@@ -2525,7 +2520,9 @@
=end original
-The link-text. If there is none, this must be undef. (E.g., in
+リンクテキスト。
+もしなければ、undef でなければなりません(must)。
+(E.g., in
"LE<lt>Perl Functions|perlfunc>", the link-text is "Perl Functions".
In "LE<lt>Time::HiRes>" and even "LE<lt>|Time::HiRes>", there is no
link text. Note that link text may contain formatting.)
@@ -2533,6 +2530,8 @@
=item Second:
+(第二:)
+
=begin original
The possibly inferred link-text; i.e., if there was no real link
@@ -2541,13 +2540,16 @@
=end original
-The possibly inferred link-text; i.e., if there was no real link
+リンクテキストと推論されるもの; つまり、もし実際のリンクテキストが
+なければ、これはリンクテキストと推論されたものです。
text, then this is the text that we'll infer in its place. (E.g., for
"LE<lt>Getopt::Std>", the inferred link text is "Getopt::Std".)
(TBT)
=item Third:
+(第三:)
+
=begin original
The name or URL, or undef if none. (E.g., in "LE<lt>Perl
@@ -2556,13 +2558,16 @@
=end original
-The name or URL, or undef if none. (E.g., in "LE<lt>Perl
+名前または URL (なければ undef)。
+(E.g., in "LE<lt>Perl
Functions|perlfunc>", the name (also sometimes called the page)
is "perlfunc". In "LE<lt>/CAVEATS>", the name is undef.)
(TBT)
=item Fourth:
+(第四:)
+
=begin original
The section (AKA "item" in older perlpods), or undef if none. E.g.,
@@ -2573,7 +2578,8 @@
=end original
-The section (AKA "item" in older perlpods), or undef if none. E.g.,
+章 (古い perlpod では「アイテム」)(なければ undef)。
+E.g.,
in "LE<lt>Getopt::Std/DESCRIPTIONE<gt>", "DESCRIPTION" is the section. (Note
that this is not the same as a manpage section like the "5" in "man 5
crontab". "Section Foo" in the Pod sense means the part of the text
@@ -2588,13 +2594,14 @@
=end original
-Pod parsers may also note additional attributes including:
-(TBT)
+また、Pod パーサは以下のような追加の属性に留意してもかまいません(may):
=over
=item Fifth:
+(第五:)
+
=begin original
A flag for whether item 3 (if present) is a URL (like
@@ -2612,6 +2619,8 @@
=item Sixth:
+(第六:)
+
=begin original
The raw original LE<lt>...> content, before text is split on
@@ -2619,9 +2628,8 @@
=end original
-The raw original LE<lt>...> content, before text is split on
-"|", "/", etc, and before EE<lt>...> codes are expanded.
-(TBT)
+"|", "/" などで分割したり EE<lt>...> コードを展開したりする前の生の
+LE<lt>...> の内容。
=back
@@ -2632,9 +2640,8 @@
=end original
-(The above were numbered only for concise reference below. It is not
-a requirement that these be passed as an actual list or array.)
-(TBT)
+(上述の番号付けは以下での参照のためだけのものです。
+これらが実際のリストや配列として渡されることは必須ではありません。)
=begin original
@@ -2642,8 +2649,7 @@
=end original
-For example:
-(TBT)
+例えば:
L<Foo::Bar>
=> undef, # link text
@@ -3088,13 +3094,12 @@
=end original
-Authors of Pod formatters are reminded that "=over" ... "=back" may
-map to several different constructs in your output format. For
-example, in converting Pod to (X)HTML, it can map to any of
-<ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or
-<blockquote>...</blockquote>. Similarly, "=item" can map to <li> or
-<dt>.
-(TBT)
+Pod フォーマッタの作者は、"=over" ... "=back" は出力フォーマットによっては
+複数の異なった構造に割り当てられるかもしれない(may)ことに留意してください。
+例えば、Pod を (X)HTML に変換する場合、<ul>...</ul>, <ol>...</ol>,
+<dl>...</dl>, <blockquote>...</blockquote> のいずれかに
+割り当てられるかもしれません。
+同様に、"=item" は <li> または <dt> に割り当てられるかもしれません。
=item *
@@ -3194,9 +3199,9 @@
=end original
-"=item [text]" 段落は、
-C<m/\A=item\s+\d+\.?\s*\z/>, C<m/\A=item\s+\*\s*\z/>,
-match just C<m/\A=item\s*\z/> にマッチングするべきではありません。
+"=item [text]" 段落は、C<m/\A=item\s+\d+\.?\s*\z/>,
+C<m/\A=item\s+\*\s*\z/> にマッチングしたり、単に
+C<m/\A=item\s*\z/> にマッチングしたりするべきではありません(should not)。
=item *
@@ -3381,8 +3386,9 @@
=end original
-is semantically ambiguous, in a way that makes formatting decisions
-a bit difficult. On the one hand, it could be mention of an item
+というのは意味論としてはあいまいで、フォーマッティング方法の決定は
+少し難しいです。
+On the one hand, it could be mention of an item
"Neque", mention of another item "Porro", and mention of another
item "Quisquam Est", with just the last one requiring the explanatory
paragraph "Qui dolorem ipsum quia dolor..."; and then an item
@@ -3432,10 +3438,9 @@
=end original
-But (for the foreseeable future), Pod does not provide any way for Pod
-authors to distinguish which grouping is meant by the above
-"=item"-cluster structure. So formatters should format it like so:
-(TBT)
+しかし(予測可能な未来において)、Pod は Pod 作者に上述の "=item" の
+塊の構造を意味するようなグルーピングを区別する方法を提供しません。
+従ってフォーマッタは以下のようにフォーマットするべきです(should):
Neque
@@ -3474,8 +3479,6 @@
=back
-
-
=head1 About Data Paragraphs and "=begin/=end" Regions
(データ段落と "=begin/=end" 領域について)
@@ -3488,10 +3491,9 @@
=end original
-データ段落は典型的には used for inlining non-Pod data that is
-to be used (typically passed through) when rendering the document to
-a specific format:
-(TBT)
+データ段落は典型的には文書を特定のフォーマットでレンダリングするときに
+使われる(典型的にはそのまま渡される)非 Pod データを含ませるために
+使います:
=begin rtf
@@ -3569,7 +3571,7 @@
=end original
-As a further example: At time of writing, no "biblio" identifier is
+さらなる例: At time of writing, no "biblio" identifier is
supported, but suppose some processor were written to recognize it as
a way of (say) denoting a bibliographic reference (necessarily
containing formatting codes in ordinary paragraphs). The fact that
@@ -3669,7 +3671,8 @@
Note, however, a "=begin I<identifier>"..."=end I<identifier>"
region where I<identifier> does I<not> begin with a colon, should not
directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back",
-nor "=item". For example, this may be considered invalid:
+nor "=item".
+例えば、以下のものは不正となります:
(TBT)
=begin somedata