ここでは、PEAR がサポートする形式でドキュメントを作成する方法について詳細に説明します。 読者としては、パッケージをメンテナンスしている PEAR 開発者および、 これから新しくパッケージを投稿しようと考えている方々を想定しています。
DocBook は XML の方言で、 様々なプロジェクトでドキュメントの管理に使用されています。 オープンソースのプロジェクトでの DocBook の使用例としては、 KDE や PHP のドキュメントがあります。 PEAR においても DocBook を使うこととしました。それにより、 PEAR パッケージの技術文書を作成するための強固な基礎が得られるものと 考えたからです。
DocBook を使うことのトレードオフとして、その使用が若干難しいということが挙げられます。 ドキュメントをテストするために、ツールをいくつかインストールする必要がありますし、 （それほど複雑でないにしても）XML の方言を覚える必要があります。 しかし、いったん DocBook の働きに慣れると、 DocBook によるドキュメント作成を楽しめるようになります。
Norman Walsh, Leonard Muellner 著、O'Reilly & Associates, Inc. 出版の書籍、 [DocBook: The Definitive Guide] は、DocBook を学ぼうとする人々にとって貴重な情報源です。 オンラインで 読むことができます。
是非、この書籍の "DocBook Element Reference" の章を読んでください。 すべての 要素について、 どの要素の親になれ、またどの要素の子になることが可能であるかなど、 詳細な情報が記載されています。
DocBook XML は（他の XML ファイルと同様に）通常のテキストエディタで編集できますが、 作成したドキュメントの妥当性を検証するためにソフトを幾つかインストールすると良いでしょう。 必要なソフトウエアとそのインストール方法については、 PHP Documentation HOWTO を参照してください。 ソフトウエアについて以外にも、この文書以上に役に立つ情報が数多く記されています すべて読んでおくことをお勧めします （第 2 章は PHP 特有の事項についての情報を扱っているので、 読み飛ばすことができます）。
OS X 上でのインストール PHP Documentation HOWTO では、Mac OS X のユーザに対して Fink のパッケージを使用するよう推奨しています。これ以外にも MacPorts プロジェクトのパッケージも使用可能です。 MacPorts をインストールした後で、 次のコマンドを使用してツール群をインストールします。
残念ながら、特定の環境では、ソフトウエアのインストールが難しい場合もありえます。 しかし、ソフトウエアを適切に動作させることが出来ないからといって、 ドキュメントを書かないことの言い訳にはなりません。 自動で peardoc を CVS からダウンロードしビルドする、 2 機のテストサーバがあります。 あなたの変更によって発生したパースエラーは、 ビルド後のログにて見ることができます。
| Brett Bieber によるビルド (log) (二時間おきに更新されます) |
| TAKAGI Masahiro によるビルド (log) (毎日 06:00 JST = 21:00 UTC に更新されます) |
| 警告 |
PEAR の WEB サイトにアップされるマニュアルは、週に一回ビルドされます。 この時、XML の妥当性チェック時にエラーが起きると、ビルドが失敗します。 ビルドが失敗すると、マニュアルが古いバージョンのままとなってしまいます。 ですから、常に テストビルドのログをチェックし、 変更が妥当であることを確認するようにしてください。 また、メインビルドが行われる (日曜 ~12:00 UTC) 直前のコミットは 控えてください。 |
必要なソフトが揃ったら、次に、PEAR の CVS リポジトリから マニュアルの XML ソースを取得します。
$ cvs -d :pserver:<user>@cvs.php.net:/repository login
[password]
$ cvs -d :pserver:<user>@cvs.php.net:/repository co peardoc
|
cvs.php.net のアカウントを持っていない場合は、ユーザ名として cvsread を使用します。 パスワードを聞かれたら、phpfi と入力してください。
上記を実行すると、./peardoc ディレクトリ内に 最新のソースのローカルコピー ("sandbox") が得られます。 あなたが、CVS に詳しく無いのならば、オンラインブック "Open Source Development with CVS" を参照すると、必要な情報が得られるでしょう。
作成されたディレクトリ peardoc を見れば概要が判ると思いますので、 ここでは、ディレクトリ構造の完全な詳細については述べません。 パッケージに関する文書を作成する場合には、はじめに peardoc/en/package/ ディレクトリを見ると良いでしょう。 ディレクトリ構造について、その他の質問がある場合は、 文書関連メーリングリスト (documentation list) でたずねてください。
DocBook によるドキュメントの作成について、くどくどと述べる代わりに、 すばやい理解ができるように "参考文献" を幾つか示します。
PEAR の CVS ツリーには DocBook XML のテンプレートが含まれており、 標準的な PEAR ドキュメントの記述構成を示しています。
このテンプレートの簡単な利用法は次のようになります。 まず、ワーキングディレクトリにコピーして適切にリネームします。 パッケージのプログラムの実装に沿って編集し、 最後に、リポジトリのパッケージのディレクトリにアップロードします。
HTTP_Request は比較的小さいパッケージで、そのドキュメントは、 エンドユーザ向けにパッケージの基本的機能を解説する複数の文書で構成されています。 各機能の説明にあたっては、少なくとも 1 つのサンプルが示されています。 数個のメソッドしかない小さなパッケージは、 このようなタイプのドキュメントを作成すれば十分です。
XML_Beautifier も比較的小さいパッケージですが、 さまざまなオプションを設定することが可能です。 これらのオプションについては、そのドキュメント中で解説されています。 加えて、(HTTP_Request と異なり) メソッドの API ドキュメントの他にも、いくつものサンプルが示されています。
DB は大規模なパッケージで、 そのドキュメントは、サンプルも含め良くできています。 DB のドキュメントは、peardoc/authoring に示された形式に適切に従っています。上のリンクは、CVS リポジトリ内の XML ソースへのものです。 HTML 変換後のもの を調べて見るのも有用でしょう。
上記の例の他にも、ローカルの CVS ツリーの peardoc ディレクトリには、ドキュメントが数多く詰まっています。 特に、peardoc/en/packages/ ディレクトリが参考になるでしょう。 また、CVS モジュールを web で見る こともできます。あなたが、今読んでいるこのファイルの生 XML は こちら です。
そのパッケージ内の各クラスの各関数ごとに、何十ものファイルを作っていくのは大変です。 幸いにも、PEAR には PhpDocumentor があります。 これを使用すると、各クラスやメソッドについてのドキュメントの雛形を作成してくれます。
テスト用のディレクトリを作成し、その中に移動しましょう。 そして、次のコマンドを入力します。 phpdoc -p on -f /path/to/my/package/source/File.php -t . -o "XML:DocBook/peardoc2:default" -dc myPackageCategory ファイルができあがったら、その内容を確認してみましょう。 そして、サンプルやドキュメントを追加したり、不要な部分を削除したりします。
注意 phpdoc が作成するのは、 ドキュメントの雛形 です。 そのままでは不完全な状態なので、後から編集する必要があります!
DocBook のソースから人が可読な形式を生成するには、 上記ソフトが必要です。PEAR ドキュメンテーションシステムでは、 Unix スタイルの makefile を用います。
peardoc$ autoconf
peardoc$ ./configure --with-lang=en
peardoc$ make html
|
英語以外の言語をビルドする場合は、上記の en のところを対応する言語コードに 変更してください。
DSSSL スタイルシートが見つからない場合は、次のようなメッセージが表示されます。
checking for docbook.dsl... defaulting - WARNING!!! DSSSL NOT FOUND - WON'T WORK THIS WAY |
この場合は、DSSSL パッケージをインストールしているかどうかをもう一度確かめてください。 Mac で Fink を使用している場合は、dsssl の場所を明示的に指定しなければなりません。 ./configure --with-dsssl=/sw/share/sgml/dsssl/docbook-dsssl-nwalsh
Windows 環境で DSSSL スタイルシートを取得する最も簡単な方法は、 cvs.php.net から phpdoc モジュールをチェックアウトすることです。 このモジュールの中の dsssl/ ディレクトリに、DSSSL スタイルシートがあります。
上記により、マニュアル全体の "生の" HTML が生成されます。 その結果は、html/ サブディレクトリに置かれます。
make test コマンドは、 XML が、構文的に正確でビルドが上手く実行されるか確認を行います。 可読形式の結果は生成しません。 make html ほどの実行時間は必要としません。
多くの開発者が、make html コマンドをうまく実行できないという問題を報告しています。 彼らが言うには、出力がファイルに書き込まれずコンソールに出力されるようです。 もしあなたがこの現象に遭遇した場合、もし DocBook ソースを /home/you/cvs/peardoc にチェックアウトしているのなら phpdoc モジュールも (先に説明した方法を使用して) /home/you/cvs/phpdoc にチェックアウトしてください。 その後、もういちど make html を実行します。
libxml2 ツールキット に含まれている xmllint プログラムを使用してテストを行うこともできます。 システム上で、 DSSSL/make のセットアップが 正しく動作しない場合に特に有用です。
DocBook ソースが正しく整形式であるかどうかの確認に加えて、 xmllint は、意味論的な正しさの確認も RELAX NG スキーマを用いて行うことができます。 DocBook 用のスキーマファイルは、docbook.org から ZIP 形式のパッケージで提供されています。 パッケージを peardoc ソースのディレクトリ下の relaxng/ ディレクトリに展開したら、 PEAR ドキュメントのルートディレクトリで次のように xmllint を実行します。
xmllint --valid --noout --relaxng relaxng/ manual.xml
ビルド処理にはかなりの時間が掛かります（ビルドのテストは十分高速です）。 そのため、デバックやテストの作業がたいへん面倒です。 ビルドの効率を高めるには、ドキュメントのルートディレクトリにある make-partial.php スクリプトを使用します。 このスクリプトは、対話的なコマンドラインスクリプトで、 マニュアルの必要な部分を選択的にインクルードすることができます。 次に示す例は、デベロッパーズガイドと HTTP パッケージの ドキュメントだけからなるマニュアルを生成するものです。 部分的なビルドにより、ビルドにかかる時間が劇的に減少します。
peardoc$ ./make-partial.php
Include about-pear? [NO]
Include guide-newmaint? [NO]
Include guide-developers? [NO] y
Include guide.developers.intro? [NO]
Include guide.developers.meaning? [NO]
Include guide.developers.contributing? [NO]
Include guide.developers.packagedef? [NO]
Include guide.developers.release? [NO]
Include guide.developers.supporting? [NO]
Include guide.developers.recommendations? [NO]
Include guide.developers.documentation? [NO] y
Include core? [NO]
Include packages? [NO] y
Include package.authentication? [NO]
Include package.benchmarking? [NO]
Include package.caching? [NO]
Include package.configuration? [NO]
Include package.console? [NO]
Include package.database? [NO]
Include package.datetime? [NO]
Include package.encryption? [NO]
Include package.fileformats? [NO]
Include package.filesystem? [NO]
Include package.gtk? [NO]
Include package.html? [NO]
Include package.http? [NO] y
Include package.images? [NO]
Include package.internationalization? [NO]
Include package.logging? [NO]
Include package.mail? [NO]
Include package.math? [NO]
Include package.networking? [NO]
Include package.numbers? [NO]
Include package.payment? [NO]
Include package.pear? [NO]
Include package.php? [NO]
Include package.science? [NO]
Include package.streams? [NO]
Include package.structures? [NO]
Include package.system? [NO]
Include package.text? [NO]
Include package.tools? [NO]
Include package.xml? [NO]
Include package.webservices? [NO]
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
/usr/bin/jade -wno-idref -d html.dsl -V use-output-dir -t sgml ./phpdocxml.dcl manual.xml
|
make-partial.php で 全部の問いにきちんと答えるのは結構時間がかかります。 make partial に適切なパラメータを渡したほうが、ずっと早いでしょう。たとえば make partial INCLUDE="packages package.database" のようにします。ID の一覧は、make の出力を調べればわかります。
ドキュメントの翻訳も重要な仕事です。 翻訳済みのドキュメントについても、英語版に変更が加えられると、 アップデートが必要となります。 翻訳を行う流れは、このマニュアルのリビジョンの追跡 のセクションを参照してください。
本章で、DocBook ドキュメントの作成についてのすべての疑問に答えられては いないかも知れません。 質問や何か問題がある場合は、pear-doc@lists.php.net にて、 PEAR ドキュメントチームに気軽に連絡を取ってください。 文書関連メーリングリスト (documentation list) に参加するには、 pear-doc-subscribe@lists.php.net へメールを送ってください。
ドキュメント作成や翻訳に関する FAQ もご覧ください。