argra****@users*****
argra****@users*****
2012年 6月 27日 (水) 01:54:33 JST
Index: docs/perl/5.12.1/perlpodspec.pod
diff -u docs/perl/5.12.1/perlpodspec.pod:1.11 docs/perl/5.12.1/perlpodspec.pod:1.12
--- docs/perl/5.12.1/perlpodspec.pod:1.11 Tue May 22 02:22:48 2012
+++ docs/perl/5.12.1/perlpodspec.pod Wed Jun 27 01:54:33 2012
@@ -624,14 +624,14 @@
=end original
-This marks the following paragraphs (until the matching "=end
-formatname") as being for some special kind of processing. Unless
-"formatname" begins with a colon, the contained non-command
-paragraphs are data paragraphs. But if "formatname" I<does> begin
-with a colon, then non-command paragraphs are ordinary paragraphs
-or data paragraphs. This is discussed in detail in the section
-L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
-(TBT)
+これは、引き続く段落 (マッチングする "=end formatname" まで) が
+なんらかの特殊な処理をするためのものであることを示します。
+"formatname" がコロンで始まっていなければ、含まれている非コマンド段落は
+データ段落です。
+しかし、もし "formatname" がコロンで I<始まっている> なら、非コマンド段落は
+通常の段落かデータ段落です。
+これは、L</About Data Paragraphs and "=beginE<sol>=end" Regions> で詳しく
+議論します。
=begin original
@@ -644,13 +644,13 @@
=end original
-It is advised that formatnames match the regexp
-C<m/\A:?[?a?zA?Z0?9_]+\z/>. Everything following whitespace after the
-formatname is a parameter that may be used by the formatter when dealing
-with this region. This parameter must not be repeated in the "=end"
-paragraph. Implementors should anticipate future expansion in the
-semantics and syntax of the first parameter to "=begin"/"=end"/"=for".
-(TBT)
+formatname は正規表現 C<m/\A:?[?a?zA?Z0?9_]+\z/> にマッチングすることを
+勧めます。
+formatname の後ろの空白に引き続く全てのものは、フォーマッタがこの
+領域を扱うときに使われるかも知れないパラメータです。
+このパラメータは "=end" 段落では繰り返されてはいけません(must not)。
+実装者は "=begin"/"=end"/"=for" の最初の引数の意味論と文法の将来の拡張に
+備えるべきです(should)。
=item "=end formatname"
@@ -665,8 +665,9 @@
=end original
-This marks the end of the region opened by the matching
-"=begin formatname" region. If "formatname" is not the formatname
+これはマッチングする "=begin formatname" 領域によって開かれた領域の
+終わりを示します。
+If "formatname" is not the formatname
of the most recent open "=begin formatname" region, then this
is an error, and must generate an error message. This
is discussed in detail in the section
@@ -1397,15 +1398,15 @@
=end original
-A naive but sufficient heuristic for testing the first highbit
-byte-sequence in a BOM-less file (whether in code or in Pod!), to see
-whether that sequence is valid as UTF-8 (RFC 2279) is to check whether
-that the first byte in the sequence is in the range 0xC0 - 0xFD
-I<and> whether the next byte is in the range
-0x80 - 0xBF. If so, the parser may conclude that this file is in
-UTF-8, and all highbit sequences in the file should be assumed to
-be UTF-8. Otherwise the parser should treat the file as being
-in Latin-1. In the unlikely circumstance that the first highbit
+並びが有効な UTF-8 (RFC 2279) かどうかを見るための、
+BOM なしファイルの(コード内か POD内内かに関わらず)最初の最上位ビットが
+立ったバイト並びをテストするという単純だけれども十分な発見法は、
+並びの最初のバイトが 0xC0 - 0xFD の範囲 I<かつ> 次のバイトの範囲が
+0x80 - 0xBF であるかどうかを調べることです。
+もし層なら、パーサはこのファイルが UTF-8 で、そのファイルの全ての
+最上位ビットが立った並びが UTF-8 であると結論づけてもかまいません(may)。
+さもなければパーサはそのファイルを Latin-1 として扱うべきです (should)。
+In the unlikely circumstance that the first highbit
sequence in a truly non-UTF-8 file happens to appear to be UTF-8, one
can cater to our heuristic (as well as any more intelligent heuristic)
by prefacing that line with a comment line containing a highbit
@@ -1578,9 +1579,9 @@
(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
+I<含みます>)では、リテラルな空白は一般的に「重要でない」と
+考えられるべきです(should);
+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
the paragraph). Pod parsers should compact literal whitespace in each
@@ -1805,10 +1806,8 @@
Pod フォーマッタ/プロセッサの作者は、独自の Pod パーサを書くことを
避けるためにあらゆる努力を行うべきです(should)。
-There are already several in
-CPAN, with a wide range of interface styles -- and one of them,
-Pod::Parser, comes with modern versions of Perl.
-(TBT)
+既に様々なインターフェーススタイルを持ったものがいくつか CPAN にあり --
+その一つである Pod::Parser か最近のバージョンの Perl に同梱されています。
=item *
@@ -1835,13 +1834,13 @@
=end original
-Characters in the range 32-126 refer to those well known US-ASCII
-characters (also defined there by Unicode, with the same meaning),
-which all Pod formatters must render faithfully. Characters
-in the ranges 0-31 and 127-159 should not be used (neither as
-literals, nor as EE<lt>number> codes), except for the
-literal byte-sequences for newline (13, 13 10, or 10), and tab (9).
-(TBT)
+よく知られている US-ASCII で参照されている範囲 32-126 の文字
+(Unicode でも同じ意味で定義されいます) は、全ての Pod フォーマッタは
+充実にレンダリングしなければなりません(must)。
+0-31 と 127-159 の範囲の文字は、改行 (13, 13 10, 10 のいずれか)または
+タブ (9) のためのリテラルなバイト並びを除いて、(リテラルとしてと
+EE<lt>number> コードとしてとのどちらとしても)
+使われるべきではありません (should not)。
=begin original
@@ -1890,8 +1889,8 @@
小なりと大なりを表すよく知られた "EE<lt>lt>" と "EE<lt>gt>" の他に、
Pod パーサは "/" (スラッシュ) のための "EE<lt>sol>" と "|" (垂直バー、
パイプ) のための "EE<lt>verbar>" を理解しなければなりません(must)。
-Pod parsers should also understand "EE<lt>lchevron>" and
-"EE<lt>rchevron>" as legacy codes for characters 171 and 187, i.e.,
+Pod パーサはまた、"EE<lt>lchevron>" と "EE<lt>rchevron>" を
+文字 171 と 187 の古いコードとして理解するべきです(should); i.e.,
"left-pointing double angle quotation mark" = "left pointing
guillemet" and "right-pointing double angle quotation mark" = "right
pointing guillemet". (These look like little "<<" and ">>", and they
@@ -1924,8 +1923,7 @@
定義されている全ての "EE<lt>html>" コードを理解するべきです(should)。
Pod パーサは少なくとも範囲 160-255 (Latin-1) の文字を定義する
エンティティを理解しなければなりません(must)。
-Pod parsers,
-when faced with some unknown "EE<lt>I<identifier>>" code,
+Pod パーサは、不明な "EE<lt>I<identifier>>" コードに出会ったとき、
shouldn't simply replace it with nullstring (by default, at least),
but may pass it through as a string consisting of the literal characters
E, less-than, I<identifier>, greater-than. Or Pod parsers may offer the
@@ -1990,8 +1988,8 @@
invalid, potentially earning a different error message than the
error message (or warning, or event) generated by a merely unknown
(but theoretically valid) htmlname, as in "EE<lt>qacute>"
-[sic]. However, Pod parsers are not required to make this
-distinction.
+[sic].
+しかし、Pod パーサはこの区別をすることを要求はされません。
(TBT)
=item *
@@ -2032,17 +2030,20 @@
=end original
-This will likely require many formatters to have tables mapping from
-treatable Unicode codepoints (such as the "\xE9" for the e-acute
-character) to the escape sequences or codes necessary for conveying
-such sequences in the target output format. A converter to *roff
-would, for example know that "\xE9" (whether conveyed literally, or via
-a EE<lt>...> sequence) is to be conveyed as "e\\*'".
-Similarly, a program rendering Pod in a Mac OS application window, would
-presumably need to know that "\xE9" maps to codepoint 142 in MacRoman
-encoding that (at time of writing) is native for Mac OS. Such
-Unicode2whatever mappings are presumably already widely available for
-common output formats. (Such mappings may be incomplete! Implementers
+これにより、おそらく多くのフォーマッタは Unicode 符号位置
+(e-acute 文字のための "\xE9") からターゲット出力形式でそのような並びを
+伝えるためのエスケープシーケンスやコードへのマッピングを行う表を
+持つことを要求されます。
+*roff の世界へのコンバータでは、例えば "\xE9" (リテラルか
+EE<lt>...> 並びかに関わらず) は "e\\*'" として伝えられます。
+同様に、Mac OS アプリケーションウィンドウに Pod をレンダリングする
+プログラムはおそらく "\xE9" を、(これを書いている時点では) Mac OS に
+ネイティブな MacRoman エンコーディングの部号位置 142 に
+マッピングされることを知っている必要があります。
+このような「Unicode から何か」へのマッピングはおそらく一般的な
+出力形式については既に広く利用可能です。
+(このようなマッピングは不完全かも知れません!
+Implementers
are not expected to bend over backwards in an attempt to render
Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any
of the other weird things that Unicode can encode.) And
@@ -2069,11 +2070,11 @@
=end original
-If, surprisingly, the implementor of a Pod formatter can't find a
-satisfactory pre-existing table mapping from Unicode characters to
-escapes in the target format (e.g., a decent table of Unicode
-characters to *roff escapes), it will be necessary to build such a
-table. If you are in this circumstance, you should begin with the
+もし、驚くべきことに、Pod フォーマッタの実装者が、Unicode 文字から
+ターゲット形式のエスケープへのマッピングに関する、満足できる既に存在する
+表(例えば Unicode 文字から *roff エスケープへのまともな表) を
+発見できない場合、そのような表を構築する必要があります。
+If you are in this circumstance, you should begin with the
characters in the range 0x00A0 - 0x00FF, which is mostly the heavily
used accented characters. Then proceed (as patience permits and
fastidiousness compels) through the characters that the (X)HTML
@@ -2293,9 +2294,9 @@
=end original
-This means that the space in the middle of the visible link text must
-not be broken across lines. In other words, it's the same as this:
-(TBT)
+これは、表示されるリンクテキストの途中にある空白は行をまたいではいけない
+(must not)ということです。
+言い換えると、以下と同じです:
L<"AutoloadedE<160>Functions"/Autoloaded Functions>
@@ -2306,9 +2307,8 @@
=end original
-However, a misapplied space-to-NBSP replacement could (wrongly)
-produce something equivalent to this:
-(TBT)
+しかし、空白から NBSP への変換を間違って適用すると、以下のようなものと
+等価なものを(間違って)生成してしまうかもしれません:
L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>
@@ -2331,10 +2331,9 @@
=end original
-Formatters may choose to just not support the S format code,
-especially in cases where the output format simply has no NBSP
-character/code and no code for "don't break this stuff across lines".
-(TBT)
+フォーマッタは、単に S フォーマッティングコードに対応しないことを
+選択してもかまいません(may); 特に出力形式に NBSP 文字/コードや
+「この内容は行をまたがない」ためのコードがない場合です。
=item *
@@ -2354,13 +2353,14 @@
=end original
-Besides the NBSP character discussed above, implementors are reminded
-of the existence of the other "special" character in Latin-1, the
-"soft hyphen" character, also known as "discretionary hyphen",
-i.e. C<EE<lt>173E<gt>> = C<EE<lt>0xADE<gt>> =
-C<EE<lt>shyE<gt>>). This character expresses an optional hyphenation
-point. That is, it normally renders as nothing, but may render as a
-"-" if a formatter breaks the word at that point. Pod formatters
+先に議論した NBSP 文字の他に、実装者は Latin-1 にその他の「特殊」文字の
+存在を思い出させます; "soft hyphen" 文字、またの名を
+"discretionary hyphen"、例えば C<EE<lt>173E<gt>> = C<EE<lt>0xADE<gt>> =
+C<EE<lt>shyE<gt>>) です。
+この文字はオプションのハイフン位置を表現します。
+これは、普通は何もレンダリングしませんが、フォーマッタがこの位置で
+単語を分割したとき、"-" としてレンダリングされます。
+Pod formatters
should, as appropriate, do one of the following: 1) render this with
a code with the same meaning (e.g., "\-" in RTF), 2) pass it through
in the expectation that the formatter understands this character as
@@ -2374,7 +2374,6 @@
=end original
例えば:
-(TBT)
sigE<shy>action
manuE<shy>script
@@ -2408,9 +2407,8 @@
=end original
-In practice, it is anticipated that this character will not be used
-often, but formatters should either support it, or delete it.
-(TBT)
+実際には、この文字はそう頻繁に使われないであろうと推測されますが、
+フォーマッタはこれに対応するか、削除するかのどちらかをするべきです(should)。
=item *
@@ -2449,11 +2447,9 @@
この文書を通じて、"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.
-(TBT)
+(典型的には Pod 形式の文書では、"pod", "Pod", "POD" のいずれかを使えます。
+これらの違いを理解することは有用です; しかしどう綴るかに捕らわれすぎるのは
+普通は有用ではありません。
=back
@@ -2697,11 +2693,10 @@
=end original
-Note that you can distinguish URL-links from anything else by the
-fact that they match C<m/\A\w+:[^:\s]\S*\z/>. So
-C<LE<lt>http://www.perl.comE<gt>> is a URL, but
-C<LE<lt>HTTP::ResponseE<gt>> isn't.
-(TBT)
+URL リンクは C<m/\A\w+:[^:\s]\S*\z/> でマッチングするという事実でその他の
+ものと区別できると言うことに注意してください。
+従って C<LE<lt>http://www.perl.comE<gt>> は URL ですが、
+C<LE<lt>HTTP::ResponseE<gt>> は違います。
=item *
@@ -2715,11 +2710,12 @@
=end original
-In case of LE<lt>...> codes with no "text|" part in them,
+"text|" 部分がない LE<lt>...> コードの場合、
older formatters have exhibited great variation in actually displaying
-the link or cross reference. For example, LE<lt>crontab(5)> would render
-as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage"
-or just "C<crontab(5)>".
+the link or cross reference.
+例えば、LE<lt>crontab(5)> は "the C<crontab(5)> manpage" あるいは
+"in the C<crontab(5)> manpage" あるいは単に "C<crontab(5)>" と
+レンダリングされます。
(TBT)
=begin original
@@ -2728,8 +2724,8 @@
=end original
-Pod processors must now treat "text|"-less links as follows:
-(TBT)
+Pod プロセッサは "text|" の内リンクを以下のように
+扱わなければなりません(must):
L<name> => L<name|name>
L</section> => L<"section"|/section>
@@ -2744,9 +2740,8 @@
=end original
-Note that section names might contain markup. I.e., if a section
-starts with:
-(TBT)
+セクション名にはマークアップを含んでいるかも知れないことに注意してください。
+つまり、セクションが以下のいずれかで始まっていると:
=head2 About the C<-M> Operator
@@ -2756,8 +2751,7 @@
=end original
-or with:
-(TBT)
+または:
=item About the C<-M> Operator
@@ -2767,8 +2761,7 @@
=end original
-then a link to it would look like this:
-(TBT)
+これへのリンクは以下のようになります:
L<somedoc/About the C<-M> Operator>
@@ -2780,10 +2773,9 @@
=end original
-Formatters may choose to ignore the markup for purposes of resolving
-the link and use only the renderable characters in the section name,
-as in:
-(TBT)
+フォーマッタはリンクを解決する目的でマークアップを無視して、
+以下のようにセクション名としてレンダリング可能な文字だけを使うことを
+選択できます(may):
<h1><a name="About_the_-M_Operator">About the <code>-M</code>
Operator</h1>
@@ -2812,19 +2804,18 @@
=end original
-Previous versions of perlpod distinguished C<LE<lt>name/"section"E<gt>>
-links from C<LE<lt>name/itemE<gt>> links (and their targets). These
-have been merged syntactically and semantically in the current
-specification, and I<section> can refer either to a "=headI<n> Heading
-Content" command or to a "=item Item Content" command. This
-specification does not specify what behavior should be in the case
-of a given document having several things all seeming to produce the
-same I<section> identifier (e.g., in HTML, several things all producing
-the same I<anchorname> in <a name="I<anchorname>">...</a>
-elements). Where Pod processors can control this behavior, they should
-use the first such anchor. That is, C<LE<lt>Foo/BarE<gt>> refers to the
-I<first> "Bar" section in Foo.
-(TBT)
+以前のバージョンの perlpod は C<LE<lt>name/"section"E<gt>> リンクを
+C<LE<lt>name/itemE<gt>> リンク (およびそのターゲット) と区別していました。
+現在の仕様ではこれらは文法的および意味論的にマージされ、
+I<section> は "=headI<n> Heading Content" コマンドまたは "=item Item Content"
+コマンドのどちらかを参照できるようになりました。
+この仕様は、一つの文書に同じ I<section> 識別子を出力するように見えるものが
+複数ある場合 (例えば、HTML では、<a name="I<anchorname>">...</a> で
+同じ I<anchorname> を生成するものが複数ある場合) の振る舞いは
+規定していません。
+Pod プロセッサがこの振る舞いを制御できるところでは、そのようなアンカーの
+最初のものを使うべきです(should)。
+つまり、C<LE<lt>Foo/BarE<gt>> は Foo にある I<最初の> "Bar" を参照します。
=begin original
@@ -2835,11 +2826,9 @@
=end original
-But for some processors/formats this cannot be easily controlled; as
-with the HTML example, the behavior of multiple ambiguous
-<a name="I<anchorname>">...</a> is most easily just left up to
-browsers to decide.
-(TBT)
+しかし一部のプロセッサ/形式はこれは簡単には制御できません; HTML の例では、
+複数の曖昧な <a name="I<anchorname>">...</a> の振る舞いは、ブラウザが
+決定するに任せるのがもっとも簡単です。
=item *
@@ -2853,12 +2842,12 @@
=end original
-Authors wanting to link to a particular (absolute) URL, must do so
-only with "LE<lt>scheme:...>" codes (like
-LE<lt>http://www.perl.org>), and must not attempt "LE<lt>Some Site
-Name|scheme:...>" codes. This restriction avoids many problems
-in parsing and rendering LE<lt>...> codes.
-(TBT)
+特定の (絶対) URL へリンクしたい著者は、それを
+(LE<lt>http://www.perl.org> のように) "LE<lt>scheme:...>" コードでのみ
+行わなければならず(must)、"LE<lt>Some Site Name|scheme:...>" コードを
+使おうとしてはいけません(must not)。
+この制限により、LE<lt>...> コードのパースおよびレンダリングするときの
+多くの問題を回避します。
=item *
@@ -2869,9 +2858,8 @@
=end original
-In a C<LE<lt>text|...E<gt>> code, text may contain formatting codes
-for formatting or for EE<lt>...> escapes, as in:
-(TBT)
+C<LE<lt>text|...E<gt>> コードは、以下のようにフォーマッティングや
+EE<lt>...> のためのフォーマッティングコードを含んでいてもかまいません(may):
L<B<ummE<234>stuff>|...>
@@ -2883,10 +2871,10 @@
=end original
-For C<LE<lt>...E<gt>> codes without a "name|" part, only
-C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur. That is,
-authors should not use "C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>".
-(TBT)
+"name|" 部分のない C<LE<lt>...E<gt>> コードでは、
+C<EE<lt>...E<gt>> と C<ZE<lt>E<gt>> のコードのみが使えます(may)。
+つまり、著者は "C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>" を使うべきではありません
+(should not)。
=begin original
@@ -2896,10 +2884,9 @@
=end original
-Note, however, that formatting codes and ZE<lt>>'s can occur in any
-and all parts of an LE<lt>...> (i.e., in I<name>, I<section>, I<text>,
-and I<url>).
-(TBT)
+しかし、フォーマッティングコードと ZE<lt>> は LE<lt>...> の全ての部分
+(つまり in I<name>, I<section>, I<text>, I<url>) に現れることに
+注意してください。
=begin original
@@ -2908,9 +2895,9 @@
=end original
-Authors must not nest LE<lt>...> codes. For example, "LE<lt>The
-LE<lt>Foo::Bar> man page>" should be treated as an error.
-(TBT)
+著者は LE<lt>...> コードをネストさせてはいけません(must not)。
+例えば、"LE<lt>The LE<lt>Foo::Bar> man page>" はエラーとして扱われるべきです
+(should)。
=item *
@@ -2921,9 +2908,8 @@
=end original
-Note that Pod authors may use formatting codes inside the "text"
-part of "LE<lt>text|name>" (and so on for LE<lt>text|/"sec">).
-(TBT)
+Pod 著者は "LE<lt>text|name>" (および LE<lt>text|/"sec">)の "text" 部分には
+フォーマッティングコードを使ってもよい(may)ことに注意してください。
=begin original
@@ -2931,8 +2917,7 @@
=end original
-In other words, this is valid:
-(TBT)
+言い換えると、次のものは有効です:
Go read L<the docs on C<$.>|perlvar/"$.">
@@ -3674,10 +3659,10 @@
=end original
-A Pod processor may signal that the above (specifically the "=head1"
-paragraph) is an error. Note, however, that the following should
-I<not> be treated as an error:
-(TBT)
+Pod プロセッサは上述のようなもの (特に "=head1" 段落) をエラーとして
+扱ってもかまいません(may)。
+しかし、以下のようなものをエラーとして扱う I<べきではない> (should not)
+ことに注意してください。
=begin somedata
@@ -3849,12 +3834,11 @@
=end original
-Pod processors should tolerate empty
-"=begin I<something>"..."=end I<something>" regions,
-empty "=begin :I<something>"..."=end :I<something>" regions, and
-contentless "=for I<something>" and "=for :I<something>"
-paragraphs. I.e., these should be tolerated:
-(TBT)
+Pod プロセッサは 空の "=begin I<something>"..."=end I<something>" 領域、
+空の "=begin :I<something>"..."=end :I<something>" 領域、中身のない
+"=for I<something>" 段落と "=for :I<something>" 段落を
+許容するべきです(should)。
+つまり、いかのようなものは許容されるべきです(should):
=for html
@@ -3873,9 +3857,9 @@
=end original
-Incidentally, note that there's no easy way to express a data
-paragraph starting with something that looks like a command. Consider:
-(TBT)
+ところで、コマンドのように見えるもので始まるデータ段落を記述する簡単な
+方法はないことに注意してください。
+以下を考えます:
=begin stuff
@@ -3891,10 +3875,9 @@
=end original
-There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data
-paragraph "=shazbot\n". However, you can express a data paragraph consisting
-of "=shazbot\n" using this code:
-(TBT)
+ここで、"=shazbot" はデータ段落 "=shazbot\n" ではなく Pod コマンド
+"shazbot" としてパースされます。
+しかし、"=shazbot\n" からなるデータ段落は以下のようにして記述できます:
=for stuff =shazbot