argra****@users*****
argra****@users*****
2011年 9月 11日 (日) 01:06:12 JST
Index: docs/modules/diagnostics-1.17/diagnostics.pod
diff -u /dev/null docs/modules/diagnostics-1.17/diagnostics.pod:1.1
--- /dev/null Sun Sep 11 01:06:12 2011
+++ docs/modules/diagnostics-1.17/diagnostics.pod Sun Sep 11 01:06:12 2011
@@ -0,0 +1,415 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+diagnostics, splain - produce verbose warning diagnostics
+
+=end original
+
+diagnostics, splain - 詳細な警告診断メッセージを出力する
+
+=head1 SYNOPSIS
+
+=begin original
+
+Using the C<diagnostics> pragma:
+
+=end original
+
+C<diagnostics> プラグマを使う:
+
+ use diagnostics;
+ use diagnostics -verbose;
+
+ enable diagnostics;
+ disable diagnostics;
+
+=begin original
+
+Using the C<splain> standalone filter program:
+
+=end original
+
+C<splain> スタンドアロンフィルタプログラムを使う:
+
+ perl program 2>diag.out
+ splain [-v] [-p] diag.out
+
+=begin original
+
+Using diagnostics to get stack traces from a misbehaving script:
+
+=end original
+
+diagnostics を使って正常に動作しないスクリプトのスタックトレースを取る:
+
+ perl -Mdiagnostics=-traceonly my_script.pl
+
+=head1 DESCRIPTION
+
+=head2 The C<diagnostics> Pragma
+
+(C<diagnostics> プラグマ)
+
+=begin original
+
+This module extends the terse diagnostics normally emitted by both the
+perl compiler and the perl interpreter (from running perl with a -w
+switch or C<use warnings>), augmenting them with the more
+explicative and endearing descriptions found in L<perldiag>. Like the
+other pragmata, it affects the compilation phase of your program rather
+than merely the execution phase.
+
+=end original
+
+このモジュールは perl コンパイラ及び perl インタプリタ双方から
+(-w スイッチをつけたり C<use warnings> を使ったりしている時に)
+出力される簡潔な診断メッセージを L<perldiag> にあるようなより説明的で
+より親切な説明を増やすことで拡張します。
+他のプラグマと同様、実行フェーズだけでなくプログラムのコンパイルフェーズにも
+効果を持ちます。
+
+=begin original
+
+To use in your program as a pragma, merely invoke
+
+=end original
+
+プログラム中でプラグマとして使うには, 単純に
+
+ use diagnostics;
+
+=begin original
+
+at the start (or near the start) of your program. (Note
+that this I<does> enable perl's B<-w> flag.) Your whole
+compilation will then be subject(ed :-) to the enhanced diagnostics.
+These still go out B<STDERR>.
+
+=end original
+
+とプログラムの始まり(または始まり近く)で起動します。
+(これは perl の B<-w> フラグを有効に I<する> ことに注意して下さい。)
+あなたのコンパイル全体が強化された診断の支配下に
+置かれるようになります。
+診断は B<STDERR> に出力されます。
+
+=begin original
+
+Due to the interaction between runtime and compiletime issues,
+and because it's probably not a very good idea anyway,
+you may not use C<no diagnostics> to turn them off at compiletime.
+However, you may control their behaviour at runtime using the
+disable() and enable() methods to turn them off and on respectively.
+
+=end original
+
+実行時とコンパイル時の間の相互作用によって、そしてそれは
+どのみちあまりよいアイデアではないために、実行時に診断メッセージを
+消すために C<no diagnostics> 使えません。
+しかし、disable() 及び enable() メソッドを使って実行時にその振る舞いを
+制御することは可能です.
+
+=begin original
+
+The B<-verbose> flag first prints out the L<perldiag> introduction before
+any other diagnostics. The $diagnostics::PRETTY variable can generate nicer
+escape sequences for pagers.
+
+=end original
+
+B<-verbose> フラグは最初に他の診断に先立って L<perldiag> の概説を
+出力します。
+$diagnostics::PRETTY 変数でページャ用のよりよいエスケープシーケンスを
+生成できます。
+
+=begin original
+
+Warnings dispatched from perl itself (or more accurately, those that match
+descriptions found in L<perldiag>) are only displayed once (no duplicate
+descriptions). User code generated warnings a la warn() are unaffected,
+allowing duplicate user messages to be displayed.
+
+=end original
+
+perl 自身から発行される警告(より正確には、L<perldiag> で
+見つけることができる説明とマッチするもの)は、一度だけ
+表示されます(説明は重複しません)。
+warn() のように警告を生成するユーザのコードには影響しないので、ユーザが
+メッセージを重複して表示させることは妨げません。
+
+=begin original
+
+This module also adds a stack trace to the error message when perl dies.
+This is useful for pinpointing what caused the death. The B<-traceonly> (or
+just B<-t>) flag turns off the explanations of warning messages leaving just
+the stack traces. So if your script is dieing, run it again with
+
+=end original
+
+このモジュールは perl が die したときにエラーメッセージにスタック
+トレースを追加することも行います。
+これは何が死因だったのかをピンポイントに探り当てるのに便利です。
+B<-traceonly> (または単にB<-t>) フラグはスタックトレースは有効にしたまま
+警告メッセージの説明を切ります。
+従って、スクリプトが die するときには
+
+ perl -Mdiagnostics=-traceonly my_bad_script
+
+=begin original
+
+to see the call stack at the time of death. By supplying the B<-warntrace>
+(or just B<-w>) flag, any warnings emitted will also come with a stack
+trace.
+
+=end original
+
+を指定してもう一度実行することで死亡時のコールスタックを見ることが
+できます。
+<-warntrace> (または単に B<-w>)フラグを使うことですべての警告で
+スタックトレースが付与されます。
+
+=head2 The I<splain> Program
+
+(I<splain> プログラム)
+
+=begin original
+
+While apparently a whole nuther program, I<splain> is actually nothing
+more than a link to the (executable) F<diagnostics.pm> module, as well as
+a link to the F<diagnostics.pod> documentation. The B<-v> flag is like
+the C<use diagnostics -verbose> directive.
+The B<-p> flag is like the
+$diagnostics::PRETTY variable. Since you're post-processing with
+I<splain>, there's no sense in being able to enable() or disable() processing.
+
+=end original
+
+一見したところ全く別のプログラムのように見えますが、実際 I<splain> は
+F<diagnostics.pod> ドキュメントへのリンクと同様に(実行可能な)
+F<diagnostics.pm> へのリンク以上の何者でもありません。
+B<-v> フラグは B<use diagnostics -verbose> 指示子のようなものです。
+B<-p> フラグは $diagnostics::PRETTY 変数のようなものです。
+I<splain> で後処理をしているので処理を enable() または disable() を行う意味は
+ありません。
+
+=begin original
+
+Output from I<splain> is directed to B<STDOUT>, unlike the pragma.
+
+=end original
+
+I<splain> の出力はプラグマとは違って B<STDOUT> に出力されます.
+
+=head1 EXAMPLES
+
+(例)
+
+=begin original
+
+The following file is certain to trigger a few errors at both
+runtime and compiletime:
+
+=end original
+
+次のファイルはいくつかのエラーを実行時とコンパイル時に発生させます:
+
+ use diagnostics;
+ print NOWHERE "nothing\n";
+ print STDERR "\n\tThis message should be unadorned.\n";
+ warn "\tThis is a user warning";
+ print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
+ my $a, $b = scalar <STDIN>;
+ print "\n";
+ print $x/$y;
+
+=begin original
+
+If you prefer to run your program first and look at its problem
+afterwards, do this:
+
+=end original
+
+まず先にプログラムを実行して問題を見ておきたいのなら次のようにします:
+
+ perl -w test.pl 2>test.out
+ ./splain < test.out
+
+=begin original
+
+Note that this is not in general possible in shells of more dubious heritage,
+as the theoretical
+
+=end original
+
+より疑わしい遺産のシェルでは一般的に可能ではありませんが、
+理論的には:
+
+ (perl -w test.pl >/dev/tty) >& test.out
+ ./splain < test.out
+
+=begin original
+
+Because you just moved the existing B<stdout> to somewhere else.
+
+=end original
+
+なぜなら既存の B<stdout> をどこか別のところにやっているからです。
+
+=begin original
+
+If you don't want to modify your source code, but still have on-the-fly
+warnings, do this:
+
+=end original
+
+ソースコードを変更したくないけれども警告をその場でとりたいのであれば
+次のようにします:
+
+ exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&-
+
+=begin original
+
+Nifty, eh?
+
+=end original
+
+すごいでしょ?
+
+=begin original
+
+If you want to control warnings on the fly, do something like this.
+Make sure you do the C<use> first, or you won't be able to get
+at the enable() or disable() methods.
+
+=end original
+
+at the enable() or disable() methods.
+もし警告をその場で制御したいのならこのようなことを行います。
+最初に C<use> するようにします; これがないと enable() 及び
+disable() メソッドを使えません。
+
+ use diagnostics; # checks entire compilation phase
+ print "\ntime for 1st bogus diags: SQUAWKINGS\n";
+ print BOGUS1 'nada';
+ print "done with 1st bogus\n";
+
+ disable diagnostics; # only turns off runtime warnings
+ print "\ntime for 2nd bogus: (squelched)\n";
+ print BOGUS2 'nada';
+ print "done with 2nd bogus\n";
+
+ enable diagnostics; # turns back on runtime warnings
+ print "\ntime for 3rd bogus: SQUAWKINGS\n";
+ print BOGUS3 'nada';
+ print "done with 3rd bogus\n";
+
+ disable diagnostics;
+ print "\ntime for 4th bogus: (squelched)\n";
+ print BOGUS4 'nada';
+ print "done with 4th bogus\n";
+
+=head1 INTERNALS
+
+(内部動作)
+
+=begin original
+
+Diagnostic messages derive from the F<perldiag.pod> file when available at
+runtime. Otherwise, they may be embedded in the file itself when the
+splain package is built. See the F<Makefile> for details.
+
+=end original
+
+診断メッセージは実行時に F<perldiag.pod> ファイルから派生します.
+それ以外は splain パッケージがビルドされたときにファイルに
+埋め込まれています。
+詳細は F<Makefile> を見てください.
+
+=begin original
+
+If an extant $SIG{__WARN__} handler is discovered, it will continue
+to be honored, but only after the diagnostics::splainthis() function
+(the module's $SIG{__WARN__} interceptor) has had its way with your
+warnings.
+
+=end original
+
+既存の $SIG{__WARN__} ハンドラが見つかっても, 誠実に継続しますが
+それは diagnostics::splainthis() 関数(このモジュールの $SIG{__WANR__}
+インターセプタ)が警告にその手段を持ったときだけです.
+
+=begin original
+
+There is a $diagnostics::DEBUG variable you may set if you're desperately
+curious what sorts of things are being intercepted.
+
+=end original
+
+もしどんなものがインターセプトされているのかが猛烈に気になるのなら、
+$diagnostics::DEBUG 変数を設定してみるとよいでしょう。
+
+ BEGIN { $diagnostics::DEBUG = 1 }
+
+=head1 BUGS
+
+=begin original
+
+Not being able to say "no diagnostics" is annoying, but may not be
+insurmountable.
+
+=end original
+
+"no diagnostics" を使えないことは悩ましいですがおそらく
+乗り越えられないでしょう。
+
+=begin original
+
+The C<-pretty> directive is called too late to affect matters.
+You have to do this instead, and I<before> you load the module.
+
+=end original
+
+C<-pretty> 指示子は状況に影響を与えるには呼び出されるのが遅すぎます。
+代わりにモジュールを読み込む I<前に> 次のことを行う必要があります。
+
+ BEGIN { $diagnostics::PRETTY = 1 }
+
+=begin original
+
+I could start up faster by delaying compilation until it should be
+needed, but this gets a "panic: top_level" when using the pragma form
+in Perl 5.001e.
+
+=end original
+
+必要になるまでコンパイルを遅延させることで起動を高速にできますが、
+これは Perl 5.001e においてプラグマ形式を使ったとき "panic: top_level"
+を発生させます。
+
+=begin original
+
+While it's true that this documentation is somewhat subserious, if you use
+a program named I<splain>, you should expect a bit of whimsy.
+
+=end original
+
+この文書は重要に準じるものである一方、I<splain> という名前のプログラムを
+使うのならちょっとした奇行を予測しておくべきです。
+
+=head1 AUTHOR
+
+Tom Christiansen <F<tchri****@mox*****>>, 25 June 1995.
+
+=begin meta
+
+Translate: 山科 氷魚 (YAMASHINA Hio) <hio****@hio*****> (1.15)
+Update: SHIRAKATA Kentaro <argra****@ub32*****> (1.17)
+
+=end meta
+
+=cut
+