第 21 章 ドキュメントの作成

目次
DocBook XML 形式
良いドキュメントを書くコツ

ここでは、PEAR がサポートする形式でドキュメントを作成する方法について詳細に説明します。 読者としては、パッケージをメンテナンスしている PEAR 開発者および、 これから新しくパッケージを投稿しようと考えている方々を想定しています。

DocBook XML 形式

DocBook は XML の方言で、 様々なプロジェクトでドキュメントの管理に使用されています。 オープンソースのプロジェクトでの DocBook の使用例としては、 KDEPHP のドキュメントがあります。 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 機のテストサーバがあります。 あなたの変更によって発生したパースエラーは、 ビルド後のログにて見ることができます。

Mika Tuupola によるビルド (log) (タイムゾーン: EET = UTC+2, EEST = UTC+3, 二時間おきに更新されます)
TAKAGI Masahiro によるビルド (log) (毎日 06:00 JST = 21:00 UTC に更新されます)

この自動ビルドによって、 加えた変更が実際のマニュアルでどのように見えるかをチェックすると良いでしょう。 PEAR の WEB サイトにアップされるマニュアルは、 週に一度だけ(日曜の ~12: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" を参照すると、必要な情報が得られるでしょう。

ドキュメントの作成

DocBook によるドキュメントの作成について、くどくどと述べる代わりに、 すばやい理解ができるように "参考文献" を幾つか示します。

  • peardoc/en/authoring

    PEAR の CVS ツリーには DocBook XML のテンプレートが含まれており、 標準的な PEAR ドキュメントの記述構成を示しています。

    このテンプレートの簡単な利用法は次のようになります。 まず、ワーキングディレクトリにコピーして適切にリネームします。 パッケージのプログラムの実装に沿って編集し、 最後に、リポジトリのパッケージのディレクトリにアップロードします。

  • HTTP Request

    HTTP_Request は比較的小さいパッケージで、そのドキュメントは、 エンドユーザ向けにパッケージの基本的機能を解説する複数の文書で構成されています。 各機能の説明にあたっては、少なくとも 1 つのサンプルが示されています。 数個のメソッドしかない小さなパッケージは、 このようなタイプのドキュメントを作成すれば十分です。

  • XML Beautifier

    XML_Beautifier も比較的小さいパッケージですが、 さまざまなオプションを設定することが可能です。 これらのオプションについては、そのドキュメント中で解説されています。 加えて、(HTTP_Request と異なり) メソッドの API ドキュメントの他にも、いくつものサンプルが示されています。

  • DB

    DB は大規模なパッケージで、 そのドキュメントは、サンプルも含め良くできています。 DB のドキュメントは、peardoc/authoring に示された形式に適切に従っています。上のリンクは、CVS リポジトリ内の XML ソースへのものです。 HTML 変換後のもの を調べて見るのも有用でしょう。

上記の例の他にも、ローカルの CVS ツリーの peardoc ディレクトリには、ドキュメントが数多く詰まっています。 特に、peardoc/en/packages/ ディレクトリが参考になるでしょう。 また、CVS モジュールを web で見る こともできます。あなたが、今読んでいるこのファイルの生 XML は こちら です。

ドキュメントのテスト

xmllint を使用

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]
Include pecl? [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
         

他に質問がありますか?

本章で、DocBook ドキュメントの作成についてのすべての疑問に答えられては いないかも知れません。 質問や何か問題がある場合は、pear-doc@lists.php.net にて、 PEAR ドキュメントチームに気軽に連絡を取ってください。 文書関連メーリングリスト (documentation list) に参加するには、 pear-doc-subscribe@lists.php.net へメールを送ってください。

レンタルサーバー

SNS