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

haruki Wed Apr 28 05:56:45 2004 EDT Modified files: /peardoc/ja/guide/developers documentation.xml Log: last half

http://cvs.php.net/diff.php/peardoc/ja/guide/developers/documentation.xml?r1=1.1&r2=1.2&ty=u Index: peardoc/ja/guide/developers/documentation.xml diff -u peardoc/ja/guide/developers/documentation.xml:1.1 peardoc/ja/guide/developers/documentation.xml:1.2 --- peardoc/ja/guide/developers/documentation.xml:1.1 Mon Oct 27 09:01:05 2003 +++ peardoc/ja/guide/developers/documentation.xml Wed Apr 28 05:56:45 2004 @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8" ?> -<!-- $Revision: 1.1 $ --> -<!-- Sync: 1.1 --> +<!-- $Revision: 1.2 $ --> +<!-- EN-Revision: 1.19 Maintainer: haruki Status: working --> <!-- WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING THIS DOCUMENT YET. @@ -14,7 +14,7 @@ </author> </docinfo> - <title>ドキュメントを書く</title> + <title>ドキュメントの作成</title> <para> This chapter provides a detailed description how to write @@ -24,31 +24,56 @@ </para> <sect1 id="developers.documentation.docbook"> - <title>Using Docbook XML</title> - <titleabbrev>Docbook</titleabbrev> + <title>The DocBook XML format</title> + <titleabbrev>DocBook XML</titleabbrev> <para> - <ulink url="&url.docbook.xml;">Docbook</ulink> is an XML dialect + <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 + 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>. + <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. </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. + </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. + </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. + </para> <sect2> <title>Required software</title> <para> - Even if Docbook XML can (like any other XML file) be written using + 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 requires software and a installation - instruction can be found + efforts. A list of the required software and a installation + instruction can be found in the <ulink url="&url.php.manual.howto;">PHP Documentation HOWTO</ulink>. Apart from providing information about the software, - this HOWTO does also provide a ton of other useful - information that goes beyond this chapter. One is encouraged to + 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.) </para> @@ -60,15 +85,27 @@ <userinput> &dollar; cvs -d :pserver:&lt;user&gt;@cvs.php.net:/repository login </userinput> + <replaceable> [password] + </replaceable> <userinput> &dollar; cvs co peardoc </userinput> </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>. + </para> + <para> After that the directory <filename>./peardoc</filename> will contain a local copy (<quote>sandbox</quote>) of the latest - sources. + 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. </para> </sect2> @@ -76,15 +113,215 @@ <title>Directory structure</title> <para> - In the directory <filename>peardoc</filename> one will find a bunch - of files in the root directory and some subdirectories. The files - in the root folder are not important yet. As a first step one - should browse through the subdirectory <filename>en</filename>, - which contains the english version of the manual. For developers - who want to document their packages, only the subdirectory - <filename>package</filename> is of importance now. + 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>. </para> </sect2> + + <sect2> + <title>Writing documentation</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: + + <itemizedlist> + <listitem> + <simpara> + <ulink + 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. + </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> + <simpara> + <ulink + url="&url.pear.cvs.peardoc;en/package/http/http-request/">HTTP + 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. + </simpara> + </listitem> + <listitem> + <simpara> + <ulink + url="&url.pear.cvs.peardoc;en/package/xml/xml-beautifier/">XML + 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. + </simpara> + </listitem> + <listitem> + <simpara> + <ulink + 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>. + </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>. + </para> + </sect2> + + <sect2> + <title>Translating documentation</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. + </para> + </sect2> + + <sect2> + <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>. + </simpara> + </sect2> + + </sect1> + + <sect1 id="developers.documentation.tips"> + + <title>Tips for good documentation</title> + <titleabbrev>Documentation Tips</titleabbrev> + + <para> + このセクションでは、 + ドキュメントを論理的に構成する方法ついて述べます。 + <literal>peardoc</literal> 標準による + ドキュメント構成の仕様を扱うものではありません。 + </para> + + <para> + <orderedlist> + <listitem> + <para> + パッケージは、ある問題を解決します。 + その問題とは、いったい何でしょうか?。 + そして、その問題について、エンドユーザが理解していない + 前提事項は何かを考えてください。 + （エンドユーザは、その問題が解決すべきことだとすら + 考えていないかもしれません。） + 例えば、テンプレートのパッケージは、コードからのデザインの分離、 + ビジネスロジックからの + ディスプレイロジックの分離という問題を解決するものです。 + 可能ならば、初心のプログラマが理解できるような用語で説明してください。 + </para> + </listitem> + <listitem> + <para> + パッケージは、 + どのような独自の方法で問題を解決していますか。 + ほとんどのドキュメントが、方法について記述していません。 + たとえば、数多くのテンプレートエンジンが存在し、 + それぞれが同じ問題を解決しようとしていますが、 + 同じ方法では行っていません。 + ブロックベースのテンプレートエンジンは + ロジックをまったく持っていませんが、 + Smarty のようなテンプレートは + まったく新しいテンプレート言語を定義しています。 + テンプレートをコンパイルするものもありますし、 + 行わないものもあります。 + 何が、パッケージの特徴でしょうか? + コードをまったく読んでいない人でも、問題の解決の方法について + 良く理解できますか? + </para> + </listitem> + <listitem> + <para> + サンプルをいくつか示してください。 + 基本的な機能を示すシンプルな例から始めてください。 + ユーザに対して、パッケージをすばやく使い始める方法を示すことになります。 + また、より複雑な例によって、ユーザはパッケージのより高度な使用方法を + 理解できるようになります。 + </para> + </listitem> + <listitem> + <para> + もし、（よくあることですが） + パッケージのインターフェイスが複雑だったり、 + 多くの定数があったりして、1、2のサンプルでは完全に説明できない場合、 + それらをドキュメント中ですべて説明してください。 + ユーザが必ず使わなければならないインターフェイス、例えば、 + データベースDSNやアプリケーションのコマンドライン引数、 + 設定ファイルの定数、その他すべての非コードな要素について、 + ドキュメントを作成してください。 + </para> + </listitem> + <listitem> + <para> + 最後に、ドキュメントを校正してください。 + 可能なら、あなたのプロジェクトを熟知していない誰かに、 + ドキュメントを見てもらってください。 + あなたが見落としていた前提事項を捕らえてくれるかもしれません。 + </para> + </listitem> + </orderedlist> + </para> </sect1> </chapter>