cvs: peardoc /ja/guide/developers documentation.xml

From: Date: Wed, 07 Jul 2004 13:49:06 +0000
Subject: cvs: peardoc /ja/guide/developers documentation.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-4573@lists.php.net to get a copy of this message
haruki Wed Jul 7 09:49:06 2004 EDT Modified files: /peardoc/ja/guide/developers documentation.xml Log: sync with en

http://cvs.php.net/diff.php/peardoc/ja/guide/developers/documentation.xml?r1=1.3&r2=1.4&ty=u Index: peardoc/ja/guide/developers/documentation.xml diff -u peardoc/ja/guide/developers/documentation.xml:1.3 peardoc/ja/guide/developers/documentation.xml:1.4 --- peardoc/ja/guide/developers/documentation.xml:1.3 Thu May 20 06:03:29 2004 +++ peardoc/ja/guide/developers/documentation.xml Wed Jul 7 09:49:05 2004 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="utf-8" ?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <!-- EN-Revision: 1.19 Maintainer: haruki Status: working --> <!-- WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING @@ -9,77 +9,136 @@ <chapterinfo> <author> + <firstname>Daniel</firstname> + <surname>Convissor</surname> + </author> + <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> </chapterinfo> <title>ドキュメントの作成</title> + <titleabbrev>ドキュメント</titleabbrev> <para> - This chapter provides a detailed description how to write - documentation using one of the supported formats. It is aimed at both - PEAR developers that are already maintaining packages in PEAR and at - people who are planning to contribute a new package. + ここでは、PEARによりサポートされる形式でのドキュメントの作成方法について + 詳細に説明します。すでにパッケージをメンテナンスしている PEAR 開発者に加え、 + これから新しくパッケージを寄与しようと考えている方々も対象としています。 </para> <sect1 id="developers.documentation.docbook"> - <title>The DocBook XML format</title> + <title>DocBook XML 形式</title> <titleabbrev>DocBook XML</titleabbrev> <para> - <ulink url="&url.docbook.xml;">DocBook</ulink> is an XML dialect - that is used by a wide range of projects to maintain their - documentation. Examples for DocBook usage in OpenSource projects are - the documentations of <ulink url="&url.kde;">KDE</ulink> and - <ulink url="&url.php;">PHP</ulink>. PEAR has opted for using - DocBook, because we believe that it provides a solid foundation for - the technical documentation for PEAR packages. + <ulink url="&url.docbook.xml;">DocBook</ulink> は XML の方言で、 + 様々なプロジェクトでドキュメントの管理に使用されています。 + オープンソースのプロジェクトでの DocBook の使用例としては、 + <ulink url="&url.kde;">KDE</ulink> や <ulink url="&url.php;">PHP</ulink> + のドキュメントがあります。 + PEAR もまた DocBook を使うこととしました。DocBook により、 + PEAR パッケージの技術文書のための強固な基礎が得られるものと考えているからです。 </para> <para> - The trade-off for using DocBook is that it is relatively hard to - use. Testing documentation requires a number of tools to be - installed and one needs to learn a (not very complicated) XML - dialect. Once one is familiar with how DocBook works, they will - enjoy writing documentation with it though. + DocBook を使うことのトレードオフは、その使用が比較的難しいということが + 挙げられます。ドキュメントをテストするにも、ツールをいくつかインストールする + 必要がありますし、(それほど複雑でないにしても)XML の方言を覚える必要が + あります。しかし、いったん DocBook の働きに慣れると、 + DocBook によるドキュメント作成を楽しめるようになります。 </para> <para> - The book <ulink url="&url.docbook.book;"><citation>DocBook: The - Definitive Guide</citation></ulink>, written by Norman Walsh and - Leonard Muellner and published by <ulink - url="&url.oreilly;">O'Reilly &amp; Associates, Inc.</ulink>, is - <ulink url="&url.docbook.book.read;">available online</ulink> and it - makes up a great resource for people interested in learning DocBook. + また、Norman Walsh, Leonard Muellner 著、<ulink + url="&url.oreilly;">O'Reilly &amp; Associates, Inc.</ulink> 出版の書籍、 + <ulink url="&url.docbook.book;"><citation>DocBook: The + Definitive Guide</citation></ulink> を + <ulink url="&url.docbook.book.read;">オンラインで</ulink> + 読むことができます。 + DocBook を学ぼうとする人々にとって、この書籍は貴重な資料です。 </para> <para> - Definitely check out the book's - <ulink url="&url.docbook.book.reference;"> - <quote>DocBook Element Reference</quote></ulink> section. - This portion provides detailed information about - <emphasis>each</emphasis> element, including which elements - can (and must) be used as parents and children. + 是非ともこの書籍の<ulink url="&url.docbook.book.reference;"> + <quote>DocBook Element Reference</quote></ulink> の章を読んでください。 + <emphasis>すべての</emphasis> 要素について、 + どの要素が親になり、また子になれるかなど、 + 詳細な情報が記載されています。 </para> <sect2> - <title>Required software</title> + <title>必要なソフトウエア</title> <para> - Even if DocBook XML can (like any other XML file) be written using - a normal text editor, one needs to install some software on their - machine in order to test the validity of the documenting - efforts. A list of the required software and a installation - instruction can be found in the + DocBook XML は(他の XML ファイルと同様に)通常のテキストエディタで + 編集できますが、作成したドキュメントの妥当性を検証するために + ソフトを幾つかインストールすると良いでしょう。 + 必要なソフトウエアとそのインストール方法は、 <ulink url="&url.php.manual.howto;">PHP Documentation - HOWTO</ulink>. Apart from providing information about the software, - this HOWTO also provides a ton of other useful - information that goes far beyond this chapter. One is encouraged to - completely read it. (Chapter II can be skipped, because it only - contains information that is very PHP specific.) + HOWTO</ulink> を参照してください。 + ソフトウエアについて以外にも、本文書以上に役に立つ情報が数多く + 記されています(第2章は PHP 特有の事項についての情報を扱っているので、 + 飛ばすことができます)。 </para> + <para> - Once the necessary software is in place, one has to get the latest - version of the XML sources from PEAR's CVS repository: + 残念ながら、特定の環境ではソフトウエアのインストールが + 難しい場合もありえます。 + しかし、ソフトウエアを適切に動作させることが出来ないからといって、 + ドキュメントを書かないことの言い訳にはなりません。 + 2時間ごとに自動で peardoc を CVS からダウンロードしビルドする、 + 2機のテストサーバがあります。 + あなたが変更を加えたことによるパースエラーは、 + ビルド後のログにて見ることができます。 + <simplelist> + <member> + <ulink url="&url.doc.test.build.1.log;"> + &url.doc.test.build.1.log;</ulink> + (time zone: EET = UTC+2, EEST = UTC+3) + </member> + <member> + <ulink url="&url.doc.test.build.2.log;"> + &url.doc.test.build.2.log;</ulink> + (time zone: CET = UTC+1, CEST = UTC+2) + </member> + <member> + <ulink url="&url.doc.test.build.2.errlog;"> + &url.doc.test.build.2.errlog;</ulink> + </member> + </simplelist> + + PEAR の WEB サイトにアップされるマニュアルは、 + 週に一度(日曜の ~12:00 UTC)だけビルドされます。 + ですので、この自動ビルドによって、加えた変更が実際のマニュアルで + どのように見えるかをチェックするのが良いでしょう。 + <simplelist> + <member> + <ulink url="&url.doc.test.build.1;"> + &url.doc.test.build.1;</ulink> + </member> + <member> + <ulink url="&url.doc.test.build.2;"> + &url.doc.test.build.2;</ulink> + </member> + </simplelist> + + <warning> + <para> + PEAR の WEB サイトにアップされるマニュアルは、 + 週に一度ビルドされます。 + XML の妥当性チェック時にエラーが起きると、ビルドが失敗します。 + ビルドが失敗すると、古いバージョンのままとなります。つまり、 + マニュアルが古いままとなってしまいます。 + ですから、<emphasis>常に</emphasis> テストビルドのログをチェックし、 + 変更が妥当であることを確認するようにしてください。 + さらに、メインビルドが行われる(日曜 ~12:00 UTC) + 直前のコミットは <emphasis>控えてください。</emphasis> + </para> + </warning> + </para> + + <para> + 必要なソフトが揃ったら、次に、PEAR の CVS リポジトリからマニュアルの XML ソースを + 取って来る必要があります。 </para> <screen> <userinput> @@ -94,44 +153,41 @@ </screen> <para> - If you do not own an account for cvs.php.net, please choose - <userinput>cvsread</userinput> as the username. When asked for the - password, type <userinput>phpfi</userinput>. + cvs.php.net のアカウントを持っていない場合は、ユーザ名として + <userinput>cvsread</userinput> を使用し、 + パスワードを聞かれたら、<userinput>phpfi</userinput> と入力してください。 </para> <para> - After that the directory <filename>./peardoc</filename> will - contain a local copy (<quote>sandbox</quote>) of the latest - sources. If you are not yet familiar with CVS, then the online - book <ulink url="&url.cvs.book;"><quote>Open Source Development - with CVS</quote></ulink> will provide you with all the necessary - information. + 上記を実行すると、<filename>./peardoc</filename> ディレクトリ内に + 最新のソースのローカルコピー (<quote>sandbox</quote>) が得られます。 + あなたが、CVS に詳しく無ければ、オンラインブック + <ulink url="&url.cvs.book;"><quote>Open Source Development with CVS</quote></ulink> + を参照すると、必要な情報が得られるでしょう。 </para> </sect2> <sect2> - <title>Directory structure</title> + <title>ディレクトリ構造</title> <para> - This chapter will not describe all the details about the directory - structure, because one can find out the essentials about it by - browsing the previously created directory - <filename>peardoc</filename>. As a starting point for package - documentors <filename>peardoc/en/package/</filename> fits well. If - one has further questions concerning the directory structure, they - can ask on the <ulink url="mailto:&email.pear.doc;">documentation - mailinglist</ulink>. + 作成されたディレクトリ <filename>peardoc</filename> を見れば概要が + 判ると思いますので、ここでは、ディレクトリ構造の完全な詳細については述べません。 + パッケージに関する文書を作成する場合には、はじめに、 + <filename>peardoc/en/package/</filename> ディレクトリを見ると良いでしょう。 + ディレクトリ構造について、その他の質問がある場合は、 + <ulink url="mailto:&email.pear.doc;">文書関連メーリングリスト + (documentation list)</ulink> でたずねてください。 </para> </sect2> <sect2> - <title>Writing documentation</title> + <title>ドキュメントの作成</title> <para> - Instead of a long and boring description for writing documentation - using DocBook, we would like to point you to a bunch of - <quote>reference documents</quote>, from which you should be - able to learn quickly: + DocBook によるドキュメントの作成についてくどくどと述べる代わりに、 + すばやい理解ができるよう、 + <quote>参考文献</quote> を幾つか示します。 <itemizedlist> <listitem> @@ -140,16 +196,14 @@ url="&url.php.cvs.peardoc.authoring;">peardoc/authoring</ulink> </simpara> <simpara> - The CVS tree has a complete set of DocBook XML templates. - These files provide the standard of how PEAR - documentation should look. + PEAR の CVS ツリーには DocBook XML のテンプレートが含まれています。 + PEAR ドキュメントがどのように見えるかの標準を提供しています。 </simpara> <simpara> - The simplest way to utilize them is to copy them to - your working directory, rename them accordingly, edit - the contents to match the reality of your program and - then upload them to your package's directory in the - repository. + このテンプレートを利用する最も簡単な方法は、 + ワーキングディレクトリにコピーし、適切にリネームし、 + パッケージのプログラムの実際に合う様に内容を編集し、 + リポジトリのパッケージのディレクトリにアップロードすることです。 </simpara> </listitem> <listitem> @@ -159,12 +213,12 @@ Request</ulink> </simpara> <simpara> - The documentation for <classname>HTTP_Request</classname>, which - is a relatively small package, only consists of a bunch of - end-user documentation, which describes all of the basic - features of the package. Each feature description includes at - least one example. For small packages with only a handful of - methods this documentation type is absolutely enough. + <classname>HTTP_Request</classname> は比較的小さいパッケージで、 + そのドキュメントは、パッケージの基本的機能を解説する、エンドユーザ向けの + ドキュメント群から構成されています。 + 各機能の説明においては、すくなくとも1つのサンプルが示されています。 + 数個のメソッドしかない小さなパッケージは、このタイプのドキュメントを + 作成すれば十分です。 </simpara> </listitem> <listitem> @@ -174,12 +228,11 @@ Beautifier</ulink> </simpara> <simpara> - <classname>XML_Beautifier</classname> is a package that is also - relatively compact, but which supports different configuration - options. These options are described in the documentation - Additionally the documentation gives usage examples and - (unlike <classname>HTTP_Request</classname>) also - includes API documentation for its methods. + <classname>XML_Beautifier</classname> も比較的小さいパッケージですが、 + さまざまなオプションを設定することが可能です。 + これらのオプションはドキュメント中で解説されています。 + 加えて、>(<classname>HTTP_Request</classname> と異なり) + メソッドの API ドキュメントの他にも、いくつものサンプルが示されています。 </simpara> </listitem> <listitem> @@ -188,43 +241,38 @@ url="&url.pear.cvs.peardoc;en/package/database/db/">DB</ulink> </simpara> <simpara> - <classname>DB</classname> is a large PEAR package and has - excellent documentation, including usage examples. - The <classname>DB</classname> docs carefully adhere - to the formatting specified in peardoc/authoring. - The link above goes to the DocBook source code in - the CVS repository. It might be helpful to examine - <link - linkend="package.database.db">the HTML generated therefrom</link>. + <classname>DB</classname> は、大規模なパッケージで、 + そのドキュメントも、サンプルも含め、良くできています。 + <classname>DB</classname> のドキュメントは、peardoc/authoring + に示された形式に入念に従っています。上のリンクは、 CVS リポジトリ内の + XML ソースへのものです。<link linkend="package.database.db"> + HTML 変換されたもの</link> を調べて見るのも有用でしょう。 </simpara> </listitem> </itemizedlist> </para> <para> - In addition to the examples above, you will find much more - documenation examples by browsing the <filename>peardoc</filename> - directory, which contains your local version of the CVS - tree. Especially the directory - <filename>peardoc/en/packages/</filename> should be of interest for - you. You can also browse the CVS module using the <ulink - url="&url.pear.cvs.peardoc;">web interface</ulink>, including the - <ulink - url="&url.pear.cvs.peardoc;en/guide/developers/documentation.xml">raw - XML for the file you are presently reading</ulink>. + 上記の例の他にも、ローカルの CVS ツリーの <filename>peardoc</filename> + ディレクトリには、ドキュメントの例がさらに詰まっています。 + 特に、<filename>peardoc/en/packages/</filename> ディレクトリが興味深いでしょう。 + また、CVS モジュールは<ulink url="&url.pear.cvs.peardoc;">web で見る</ulink> + こともできます。あなたが、今読んでいるこのファイルの生 XML は + <ulink url="&url.pear.cvs.peardoc;en/guide/developers/documentation.xml"> + こちら</ulink> です。 </para> </sect2> <sect2> - <title>Translating documentation</title> + <title>ドキュメントの翻訳</title> <para> - Translating documentation is another important task. - Not only does new documentation need to be translated - into the existing languages, additional languages are - welcome. Also, existing translations need to be brought - up to date because the English versions have been changed. - Help on how to perform the translation process is in the <link - linkend="faq.translators-revision-tracking">Revision Tracking</link> - section of the manual. + ドキュメントの翻訳も重要な仕事です。 + これまで翻訳が行われていない言語への翻訳を新たに行うことも歓迎ですし、 + 新しいドキュメントが加わった時に、それを翻訳することも必要です。 + また、翻訳済みのドキュメントも、英語版に変更が加えられると、 + アップデートが必要となります。 + 翻訳を行う流れは、本マニュアルの<link + linkend="faq.translators-revision-tracking">リビジョンの追跡</link> + のセクションを参照してください。 </para> </sect2> @@ -232,13 +280,14 @@ <title>Questions?</title> <simpara> - We are well aware that we cannot cover all questions about writing - DocBook documentation in this chapter. If you have more questions - or problems, do not hesitate to get in touch with the documentation - team at <ulink - url="mailto:&email.pear.doc;">&email.pear.doc;</ulink>. - To join the pear-doc list send an email to <ulink - url="mailto:&email.pear.doc-subscribe;">&email.pear.doc-subscribe;</ulink>. + 本章で、DocBook ドキュメントの作成についてのすべての質問に答えられては + いないかも知れません。質問や問題がある場合は、<ulink + url="mailto:&email.pear.doc;">&email.pear.doc;</ulink> にて、 + ドキュメントチームに気軽に連絡をとってください。 + 文書関連メーリングリスト (documentation list)に参加するには、 + <ulink + url="mailto:&email.pear.doc-subscribe;">&email.pear.doc-subscribe;</ulink> + へメールしてください。 </simpara> </sect2> @@ -246,13 +295,13 @@ <sect1 id="developers.documentation.tips"> - <title>Tips for good documentation</title> - <titleabbrev>Documentation Tips</titleabbrev> + <title>良いドキュメントを書くコツ</title> + <titleabbrev>ドキュメントのコツ</titleabbrev> <para> このセクションでは、 - ドキュメントを論理的に構成する方法ついて述べます。 - <literal>peardoc</literal> 標準による + ドキュメントを論理的に記述する方法ついて述べます。 + <literal>peardoc</literal> の標準に従った ドキュメント構成の仕様を扱うものではありません。 </para> @@ -262,61 +311,54 @@ <para> パッケージは、ある問題を解決します。 その問題とは、いったい何でしょうか?。 - そして、その問題について、エンドユーザが理解していない - 前提事項は何かを考えてください。 - (エンドユーザは、その問題が解決すべきことだとすら - 考えていないかもしれません。) + そして、その問題について、エンドユーザが理解していないかもしれない + 前提事項は何かを考えてください + (エンドユーザは、その問題が解決すべき事だとすら考えていないかもしれません)。 例えば、テンプレートのパッケージは、コードからのデザインの分離、 - ビジネスロジックからの - ディスプレイロジックの分離という問題を解決するものです。 - 可能ならば、初心のプログラマが理解できるような用語で説明してください。 + ビジネスロジックからのディスプレイロジックの分離という問題を解決するものです。 + このとき可能ならば、初心のプログラマが理解できるような用語で説明してください。 </para> </listitem> <listitem> <para> パッケージは、 どのような独自の方法で問題を解決していますか。 - ほとんどのドキュメントが、方法について記述していません。 + 多くのドキュメントが記述していないのが、問題解決の方法についてです。 たとえば、数多くのテンプレートエンジンが存在し、 - それぞれが同じ問題を解決しようとしていますが、 - 同じ方法では行っていません。 - ブロックベースのテンプレートエンジンは - ロジックをまったく持っていませんが、 - Smarty のようなテンプレートは - まったく新しいテンプレート言語を定義しています。 - テンプレートをコンパイルするものもありますし、 - 行わないものもあります。 + それぞれが同じ問題を解決しようとしていますが、同じ方法では行っていません。 + ブロックベースのテンプレートエンジンはロジックをまったく持っていませんが、 + Smarty のようなテンプレートはまったく新しいテンプレート言語を定義しています。 + テンプレートをコンパイルするものもありますし、しないものもあります。 何が、パッケージの特徴でしょうか? - コードをまったく読んでいない人でも、問題の解決の方法について - 良く理解できますか? + コードを読んでいないユーザも、問題解決の方法について良く理解できるでしょうか? </para> </listitem> <listitem> <para> サンプルをいくつか示してください。 基本的な機能を示すシンプルな例から始めてください。 - ユーザに対して、パッケージをすばやく使い始める方法を示すことになります。 - また、より複雑な例によって、ユーザはパッケージのより高度な使用方法を - 理解できるようになります。 + ユーザに対して、パッケージをすばやく使い始める方法を示すことができます。 + さらに、より複雑な例を示すことによって、 + ユーザはより高度な使用方法を理解できるようになります。 </para> </listitem> <listitem> <para> もし、(よくあることですが) パッケージのインターフェイスが複雑だったり、 - 多くの定数があったりして、1、2のサンプルでは完全に説明できない場合、 - それらをドキュメント中ですべて説明してください。 - ユーザが必ず使わなければならないインターフェイス、例えば、 + 多くの定数があったりして、1、2のサンプルでは完全に説明ができない場合、 + それらインターフェイスや定数を、ドキュメント中ですべて説明してください。 + ユーザが必ず使うことになるインターフェイス、例えば、 データベースDSNやアプリケーションのコマンドライン引数、 - 設定ファイルの定数、その他すべての非コードな要素について、 + 設定ファイルの定数、その他すべての非コード的な要素について ドキュメントを作成してください。 </para> </listitem> <listitem> <para> 最後に、ドキュメントを校正してください。 - 可能なら、あなたのプロジェクトを熟知していない誰かに、 - ドキュメントを見てもらってください。 + できるなら、あなたのプロジェクトを良く知らない誰かに + ドキュメントを読んでもらってください。 あなたが見落としていた前提事項を捕らえてくれるかもしれません。 </para> </listitem>
« previous php.pear.doc (#4573) next »