cvs: peardoc /ja/chapters faq.xml standards.xml

haruki Thu Jul 1 07:29:37 2004 EDT Modified files: /peardoc/ja/chapters faq.xml standards.xml Log: small refines. sync with en

http://cvs.php.net/diff.php/peardoc/ja/chapters/faq.xml?r1=1.6&r2=1.7&ty=u Index: peardoc/ja/chapters/faq.xml diff -u peardoc/ja/chapters/faq.xml:1.6 peardoc/ja/chapters/faq.xml:1.7 --- peardoc/ja/chapters/faq.xml:1.6 Mon Apr 19 14:02:51 2004 +++ peardoc/ja/chapters/faq.xml Thu Jul 1 07:29:36 2004 @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8" ?> -<!-- $Revision: 1.6 $ --> -<!-- EN-Revision: 1.11 Maintainer: haruki Status: ready --> +<!-- $Revision: 1.7 $ --> +<!-- EN-Revision: 1.13 Maintainer: haruki Status: ready --> <!-- CREDITS: elf --> <!-- [mj] The FAQ needs some heavy revision - don't translate it right now --> @@ -536,8 +536,8 @@ さまざまなシステムやエディタが使用されるコミュニティでは、 タブは機能しません。 他人にはうまく表示されないとすれば、 - 人々は結局、スペースを使って体裁を整えることになるでしょう。 - スペースを使うことだけが、だれが見ても同じように見えるようにする + 結局、スペースを使って体裁を整えるしかありません。 + スペースを使うことだけが、誰が見ても同じように見えるようにする 唯一の方法なのです。 </simpara> <para> @@ -561,12 +561,12 @@ </titleabbrev> <para> 翻訳作業に携わるということは、 - 単に英語のファイルを翻訳し結果をコミットするということ - だけではありません。英語のファイルの内容にあわせて、 + 単に英語のファイルを翻訳し結果をコミットするだけで終わりません。 + 英語ファイルの内容にあうように 翻訳済みのファイルをアップデートすることにも、 たくさんの労力が必要となります。 英語ツリーのファイルに加えられた変更を追跡するためには、 - <ulink url="http://www.pear.php.net/support.php">PEAR ドキュメンテーション + <ulink url="mailto:&email.pear.doc-subscribe;">PEAR ドキュメンテーション メーリングリスト</ulink> を購読し、コミットメッセージやアーカイブを読むべきです。 ファイルが更新されなければ、翻訳の利用価値がなくなっていきます。 @@ -574,7 +574,7 @@ <simpara> 更新するべき場所がどこなのかに加え、 いつ・だれがそのファイルを翻訳したのかということがわからなければ、 - 他言語のファイルの更新は困難となります。 + 翻訳済みファイルの更新は困難となります。 そこで、PEARには、 <literal>peardoc</literal> のファイルの変更日および リビジョンを追跡するシステムがあります。 @@ -582,61 +582,61 @@ <sect2 id="faq.translators.revcheck-comments"> <title>リビジョンコメント</title> <para> - 中央の単一ファイルに全情報を保持させるものとは異なり、 - リビジョンコメントのシステムはファイルごとに情報を - ストアします。 + 中央の単一ファイルに全情報を保持するシステムとは異なり、 + リビジョンコメントのシステムはファイルごとに情報をストアします。 翻訳者・リビジョン番号およびステータス情報に関する情報を、 リビジョンコメントに格納します。 - それではサンプルのファイルのヘッダがどのようなものか、みてみましょう。 + それではサンプルのファイルのヘッダがどのようなものか見てみましょう。 <filename>bookinfo.xml</filename>ファイルです。 <programlisting> &lt;!-- EN-Revision: 1.16 Maintainer: jane Status: ready --&gt; </programlisting> </para> <para> - 翻訳の更新に使われた最後の英語ファイルのリビジョン番号 + 翻訳の更新がされた最後の英語ファイルのリビジョン番号 (EN-Revision: 1.16)、および、 - 翻訳者の CVS アカウント名がわかります。 + 翻訳者の CVS アカウント名が記されています。 必要ならば、いくぶんかのステータス情報を追加することができます （例、部分的な翻訳に対しては"partial"）。 このリビジョンコメントのシステムでは、情報を - 中央の1つの場所ではなく、各XMLファイルに記述します。 - 英語ツリーには1300以上のファイルがあるので、 - このほうが非常に便利です。 + 中央の1つの場所ではなく、各 XML ファイルに記述します。 + 英語ツリーには 1300 以上ものファイルがあるので、このほうが非常に便利です。 </para> <para> - 現在、3つのフィールド - (英語リビジョン・メンテナ・状態)すべてが必須です。 + 現在、3 つのフィールド + (英語リビジョン・メンテナ・状態) すべてが必須項目です。 メンテナ (Maintainer) は CVS のユーザ名、 あるいは空白文字のないニックネームを用います。 状況 (Status) は空白なしで何でもでありです。 このヘッダは、CVS によって、 (自動的に更新される <literal>$Revision</literal> と異なり) - 自動的に更新されないことに注意してください。 - 更新するには、自分自身で編集します。 + 自動的に更新されませんので注意してください。 + 自分自身で編集し、更新します。 </para> <para> - 良さを理解いただけたでしょうが、ただし、このコメントを使用すると、 - 翻訳済ファイルの一覧をさっと見ることはできなくなります。 - しかし、これまで以上のものを得ることができます。 - 翻訳済ファイルの全リストを作成したい場合には、 - /peardoc/ ディレクトリで以下を実行します。 + リビジョンコメントの良さは理解いただけたことと思います。 + ただし、リビジョンコメントを使用すると、 + （1ファイルに全情報を記述した場合と異なり） + 翻訳済ファイルのリストをさっと見ることはできなくなります。 + しかし、より良いリストを得ることができます。 + /peardoc/ ディレクトリで以下のコマンドを実行すると、 + 翻訳済ファイルの全リストを作成できます。 <programlisting> ./scripts/revcheck_pear.php xx > revcheck.html </programlisting> ここで、<literal>xx</literal> は仮の言語コードです。 このスクリプトを実行させると、 - 同じディレクトリに <filename>revcheck.html</filename> が作成され、 - その言語の全ファイルのリビジョンの比較や diff への - リンクを得られます。 - また、メンテナの名前をパラメタとして付加すると、 - 指定したメンテナが係わったファイルだけのリストを得ることもできます。 + 同ディレクトリに <filename>revcheck.html</filename> が作成され、 + 指定した言語の全ファイルのリビジョンの比較や、diff への + リンクが纏められています。 + さらに、メンテナの名前をパラメタとして付加すると、 + 指定したメンテナが係わったファイルのリストを得ることもできます。 </para> <para> - このスクリプトには、生成される HTML ページに対して利用可能な + このスクリプトには、生成される HTML ページに対して適用できる いくつかのオプション拡張があります。 <filename>translation.xml</filename> というファイルはこの拡張ためにあります。 - 以下は、想像上の xx 言語向けのシンプルなな + 以下は、仮の xx 言語向けのシンプルなな <filename>translation.xml</filename> のファイルです。 <programlisting> <![CDATA[ @@ -671,17 +671,19 @@ </translation> ]]> </programlisting> - このファイルには、CVS アカウントのないユーザも加えることができ、 - 翻訳済のドキュメントにも、進行中(work-in-progress)のファイルにも + このファイル（の translators 要素）には、 + CVS アカウントを持たないユーザも加えることができ、 + 翻訳済のドキュメント（のリビジョンコメント）にも、 + 更新中のファイル（work-in-progress 要素）にも アサインできます。 このアドオンを使用する最大の利点は、 <filename>revcheck.html</filename> のファイル中に、 - 翻訳者やファイルについての動的なテーブルを生成するのに、 - これらの全情報が使われるということです。 - すべての翻訳者は、アサインされた個別のファイルからリンクされ、 - きれいな表が全翻訳者のステータスを表示します。 - 時間がかかる更新が行われている場合は、翻訳済みのファイルをアサインする - ことが必要かもしれません。 + 翻訳者やファイルについての動的なテーブルを生成する際に、 + これらの情報が使われるということです。 + 各ファイルから関連する各翻訳者へのリンクが生成されます。 + また、きれいな表で各翻訳者のステータスを表示します。 + 時間がかかる更新が行われている場合は、 + 更新中のファイルを（work-in-progress 要素に）アサインすると良いでしょう。 </para> <para> &lt;file&gt; には、2つのオプションのパラメータが付加できます。 http://cvs.php.net/diff.php/peardoc/ja/chapters/standards.xml?r1=1.3&r2=1.4&ty=u Index: peardoc/ja/chapters/standards.xml diff -u peardoc/ja/chapters/standards.xml:1.3 peardoc/ja/chapters/standards.xml:1.4 --- peardoc/ja/chapters/standards.xml:1.3 Fri Jun 18 03:49:38 2004 +++ peardoc/ja/chapters/standards.xml Thu Jul 1 07:29:36 2004 @@ -1,7 +1,7 @@ <?xml encoding="utf-8"?> -<!-- $Revision: 1.3 $ --> -<!-- EN-Revision: 1.22 Maintainer: Status: ready --> -<!-- CREDITS: --> +<!-- $Revision: 1.4 $ --> +<!-- EN-Revision: 1.26 Maintainer: haruki Status: ready --> +<!-- CREDITS: hirokawa --> <chapter id="standards"> <title>標準コーディング規約</title> <note> @@ -14,8 +14,8 @@ <sect1 id="standards.indenting"> <title>インデント</title> <para> - タブではなく、空白 4 つのインデントを使用してください。 - PEAR コードを編集するために Emacs を使用する場合、indent-tabs-mode を + 空白 4 つのインデントを使用してください。タブは使わないでください。 + PEAR コードの編集に Emacs を使用する場合、indent-tabs-mode を nil に設定する必要があります。以下に、これらのガイドラインに基づき Emacs を設定するモードフックの例を示します（PHP ファイルを編集する際に これがコールされるようにする必要があります）。 @@ -116,7 +116,7 @@ <para> 上記のように、関数の返り値を変数に代入する際に使用する等号の左右には、 空白を１つ置くべきです。相関する一連の代入文の場合には、 - 可読性を向上させるために空白をより多く置いても良いでしょう。 + 可読性を向上させるために空白を複数置いても良いでしょう。 <programlisting role="php"> <![CDATA[ $short = foo($bar); @@ -143,9 +143,10 @@ </programlisting> </para> <para> - デフォルト値を有する引数は引数リストの終わりに置きます。 - 関数は処理が適当である場合、常に関数から意味のある値を返すよう - にしてください。以下にやや長い例を示します。 + デフォルト値を有する引数は、引数リストの終わりに置きます。 + 関数は処理が適当である場合、 + 常に関数から意味のある値を返すようにしてください。 + 以下に、やや長い例を示します。 <programlisting role="php"> <![CDATA[ function connect(&$dsn, $persistent = false) @@ -252,13 +253,13 @@ 関数のリライトや新たなロジックの提供の場合には、例外もありえます。 </para> <para> - 簡単なコードの整理やバグ修正は、作者のリストに新たに個人を追加する + 簡単なコードの整理やバグ修正は、作者のリストに新たに人を追加する までの理由にはなりません。 </para> <para> コア PEAR リポジトリにないファイルについても、著作権・ライセンス・ 作者を記述した同様のブロックを含む必要があります。すべてのファイルには、 - 統一したmodelineコメントを含むべきです + 統一した modeline コメントを含むべきです </para> </sect1> @@ -268,9 +269,9 @@ 本節は、cvs.php.net の CVS を使用するパッケージにのみ適用されます。 </simpara> <para> - 各ファイルに、CVS のキーワード &dollar;Id&dollar; を含めてください。 - 各ファイルを編集した際に、まだ無い場合にはこのタグを追加してください - （または、<quote>Last Modified:</quote>のような既存の形式を置換してください）。 + 各ファイルに、CVS のキーワード &dollar;Id&dollar; を記述してください。 + 各ファイルを編集した際に、無ければ追加してください + （もしくは、<quote>Last Modified:</quote> のような形式があれば置換してください）。 <!-- <note> <simpara> @@ -288,7 +289,7 @@ </para> <para> CVS タグは、指定したリリースに属するパッケージのファイルのリビジョンを - 示すラベルとして使用されます。以下に必須及び推奨される CVS + 示すラベルとして使用されます。以下に必須および推奨される CVS タグ のリストを示します。 <variablelist> @@ -307,8 +308,8 @@ <listitem> <simpara> （ブランチ, オプション）リリース前にリリース侯補版を公開する必要が - あると考えた場合には、リリース版を分岐し、実際のリリース前に重要な - 修正のみが適用されるようにするというのは良い考えです。 + あると考えた場合には、リリース版を分岐するというのは良い考えです。 + というのも、重大な修正だけをリリースに適用できるからです。 その間にも、通常の開発はメイントランクにおいて継続することが可能です。 </simpara> </listitem> @@ -318,17 +319,17 @@ <listitem> <simpara> （ブランチ, オプション）（例えば1.2の後に1.2.1といった） - <quote>マイクロリリース</quote>を行う際に、 - メインの開発トランクが非常に活溌で、マイクロリリース間で + <quote>マイクロリリース</quote> を行う際に、 + メインの開発トランクが非常に活発で、マイクロリリースで 僅かな変更のみを行いたい場合に、ブランチを使用することもできます。 </simpara> </listitem> </varlistentry> </variablelist> - RELEASE タグのみが必須で、残りは有用なものを推奨しているだけです。 + RELEASE タグのみが必須です。残りも有用ですので使用を推奨します。 </para> <para> - 以下は、<classname>Money_Fast</classname>パッケージに + 以下は、<classname>Money_Fast</classname> パッケージに 1.2 リリースタグを付ける方法を示すものです。 <informalexample> <screen><prompt>$ </prompt><command>cd pear/Money_Fast</command> @@ -339,7 +340,7 @@ </computeroutput> </screen> </informalexample> - これにより、PEAR Web サイトで残りのリリース手順を実行することが + これにより、PEAR Web サイトにて以降のリリース手順を行うことが できるようになります。 </para> <para> @@ -355,9 +356,9 @@ </screen> </informalexample> <literal>QA_2_0_0_BP</literal>タグは、<quote>分岐点 (branch point)</quote> - タグで、タグの開始点です。このような分岐点から CVS ブランチを開始するのは - 常に良い考えです。MAINT ブランチは、その分岐点と同様に RELEASE - タグを使用することが可能です。 + タグで、タグの開始点です。 + このような分岐点から CVS ブランチを開始するのは良い考えです。 + MAINT ブランチは、RELEASE タグも分岐点として使用することができます。 </para> </sect1> @@ -376,10 +377,11 @@ <sect2> <title>クラス</title> <para> - クラスは、内容が分かる名前を指定する必要があります。可能ならば略語の - 使用は避けてください。クラス名は、常に大文字で始まる必要があります。 + クラスには、内容が分かる名前を指定するべきです。 + 略語の使用は可能なかぎり避けてください。 + クラス名は、常に大文字で始めるべきです。 PEAR クラス階層は、クラス名にも反映され、各階層レベルは、 - アンダースコア1つで区切られます。良いクラス名の例を以下に示します。 + アンダースコアで区切られます。良いクラス名の例を以下に示します。 <informaltable> <tgroup cols="3"> <tbody> @@ -398,11 +400,11 @@ <para> 関数とメソッドは、<quote>studly caps</quote>形式 （<quote>bumpy case</quote> または <quote>camel caps</quote> とも呼ばれます） - を使用して名前を付ける必要があります。 - 関数は、パッケージ間の名前の衝突を避けるためにパッケージ名を接頭辞として - 加える必要があります。（接頭辞の後の）名前の最初の文字は小文字で、 + を使用して名前を付けるべきです。 + 関数には、パッケージ間の名前の衝突を避けるためにパッケージ名を接頭辞として + 加えるべきです。（接頭辞の後の）名前の最初の文字は小文字で、 新しい単語を始める際の各先頭文字は大文字とします。 - 例をいくつか以下に示します。 + いくつかの例を以下に示します。 <informaltable> <tgroup cols="4"> <tbody> @@ -417,8 +419,8 @@ </informaltable> </para> <para> - プライベートなクラスメンバ（宣言された同じクラスの内部からだけの使用を - 意図したクラスメンバ。 + プライベートなクラスメンバ + （それが宣言されたクラスの内部からだけの使用を意図したクラスメンバ。 PHP は、プライベート名前空間をまだサポートしていません。）は、 アンダースコア 1 つを前に付けます。例を以下に示します。 <informaltable> @@ -437,19 +439,21 @@ <sect2> <title>定数</title> <para> - 定数は、常にすべて大文字で記述し、単語を区切る際にはアンダースコアを - 使用します。使用されるクラス／パッケージを大文字で表した名前を - 定数の接頭辞として使用します。例えば、<literal>DB::</literal> パッケージ - で使用される定数はすべて<literal>DB_</literal>で始まります。 + 定数は、常にすべて大文字で記述し、単語の区切りにはアンダースコアを + 使用するべきです。使用されるクラス／パッケージを大文字で表した名前を + 定数の接頭辞として付加してください。 + 例えば、<literal>DB::</literal> パッケージで使用される定数は、 + すべて <literal>DB_</literal> で始まります。 </para> </sect2> <sect2> <title>グローバル変数</title> <para> パッケージでグローバル変数を定義する必要がある場合、その名前は、 - アンダースコアで始まり、その後にパッケージ名と別のアンダースコア - が続くようにする必要があります。例えば、PEAR パッケージは、 - $_PEAR_destructor_object_list という名前のグローバル変数を使用します。 + アンダースコアを前後に付けたパッケージ名で始めるべきです。 + 例えば、PEAR パッケージは、 + <literal>$_PEAR_destructor_object_list</literal> + という名前のグローバル変数を使用します。 </para> </sect2> </sect1> @@ -478,21 +482,21 @@ </para> <para> 1) - 各行は、 ラインフィード(改行: <literal>LF</literal>) で終える。 + 各行は、 ラインフィード(改行: <literal>LF</literal> ) で終える。 ラインフィードは、10進数で <literal>10</literal>、 8進数で <literal>012</literal>、16進数で <literal>0A</literal> と表示されます。 Mac のようにキャリッジリターン - (行頭復帰: <literal>CR</literal>)で終えたり、 + (行頭復帰: <literal>CR</literal> )で終えたり、 Windows のようにキャリッジリターンとラインフィードの組 - (<literal>CRLF</literal>)で終えたりしてはいけません。 + (<literal>CRLF</literal> )で終えたりしてはいけません。 </para> <para> 2) - PHP の終了タグ (<literal>?&gt;</literal>) の後には - ラインフィードを <emphasis>1 つ</emphasis>置くべきです。 - つまり、ファイルの最後にカーソルを移動させ時に、 - PHP の終了タグの <emphasis>1 つ</emphasis>下の行に + PHP 終了タグ (<literal>?&gt;</literal> ) の後には + ラインフィードを <emphasis>1 つ</emphasis> 置くべきです。 + つまり、ファイルの最後にカーソルを移動させると、 + PHP 終了タグの <emphasis>1 つ</emphasis> 下の行に カーソルがあるようにすべきと言うことです。 </para> </listitem> @@ -513,17 +517,18 @@ </para> <para> <quote>折り畳みマーカ (fold markers)</quote> - （<literal>// {{{</literal> および <literal>// }}}</literal>） + （<literal>// {{{</literal> および <literal>// }}}</literal> ） は、オプションです。折り畳みマーカを使わない場合は、 <literal>foldmethod=marker</literal> を vim のヘッダから削除してください。 </para> <para> サンプルには、Docblock コメントの書き方についての詳細が記載されています。 - これらの指示に従うことは、2 つの意味で重要です。第 1 は、docblocks は - 読みやすく、コードが何の動作をするかをユーザや開発者がすばやく理解できます。 + これらの指示に従うことは、2 つの意味で重要です。第 1 は、Docblock は + 読みやすく、コードがどのような動作をするかを + ユーザや開発者がすばやく理解できるからです。 第 2 に、PEAR の WEB サイトでは、パッケージの各リリースについて - phpDocumentor によって生成された API ドキュメントを掲載しています。 - WEB サイト上の API ドキュメントを役に立つものにするには、 + phpDocumentor によって生成された API ドキュメントを掲載しているからです。 + WEB サイト上の API ドキュメントを有用なものにするには、 きちんとコメントを記述しておく必要があります。 </para> <para> @@ -548,7 +553,7 @@ // | Your Name <you@example.com> | // +----------------------------------------------------------------------+ // -// $Id: standards.xml,v 1.3 2004/06/18 07:49:38 haruki Exp $ +// $Id: standards.xml,v 1.4 2004/07/01 11:29:36 haruki Exp $ require_once 'PEAR.php'; @@ -600,7 +605,7 @@ * @category categoryname * @package packagename * @author Original Author <author@example.com> - * @version $Id: standards.xml,v 1.3 2004/06/18 07:49:38 haruki Exp $ + * @version $Id: standards.xml,v 1.4 2004/07/01 11:29:36 haruki Exp $ * @access public * @see NetOther, Net_Sample::Net_Sample() * @since Class available since Release 1.2.0