現在、php-gtk-doc モジュールをビルドする方法は二通りあります。 標準的な方法のほうは、サーバ上で使用されており、 さまざまなビルドオプションを指定することができます。 もうひとつの方法については、現在は英語版で複数 HTML ファイル形式のものしか作成することができません。

もうひとつの方法の最大の利点は、PHP-GTk のマニュアルを Windows 上でコンパイルできることです。その際に、 cygwin のような Linux エミュレータをインストールする必要はありません。 しかしその代わりに、ビルド環境を構築するためにいくつかの Unix ツール をインストールする必要があります。 インストールするって言うか、単にルートディレクトリにファイルを展開するだけです。 なので、インターネットの接続速度が遅いなどの理由で cygwin をインストールできないような環境でも簡単に導入できます。

どちらのビルド方式を使用するにしても、XSL スタイルシートを処理するために xsltproc が必要となります。Linux 環境では、 これはパッケージマネージャからインストールします。 cygwin を使用している場合は、cygwin のインストーラを使用します。 cygwin を使用しない Windows 環境の場合は、xsltproc のバイナリ (iconv、zlib、libxml2 および libxslt パッケージが必要です) を Igor Zlatkovic (彼は xmlsoft.org のコントリビュータです) の プロジェクトのサイト から取得し、ルートディレクトリにそれを展開します。

マニュアルを更新したりだとかコンパイルしたりだとかするためには、 まずマニュアルのコピーを CVS から取得しなければなりません。 そのためには CVS クライアントが必要となります。たいていの Linux システムには、コマンドラインの cvs ツールがインストールされています。cygwin でも同様です。 Windows の場合は、クリックひとつで使える CVS クライアントである Tortoise CVS のようなものがあります。

ドキュメントのコピーをコマンドラインツール cvs で取得するには、 cvs -d :pserver:[email protected]:/repository co -P php-gtk-doc と入力します。

もしすでにコピーを持っているのなら、以下のようにしてそれを更新できます。 cvs -d :pserver:[email protected]:/repository update -Pd php-gtk-doc (php-gtk-doc ディレクトリの中にいる場合は、 php-gtk-doc の部分を省略できます (しなければなりません))。

ドキュメントのコピーを TortoiseCVS で取得するには、 File/CVS checkout を選択してフォームに入力します。 プロトコルは Password server (:pserver) を選択します。サーバは cvs.php.net、 そしてリポジトリのフォルダは /repository です。 CVS アカウントをお持ちの場合はそれを使用します。 もっていない場合は cvsread を使用します。 モジュールは、もちろん php-gtk-doc です。 現在のバージョンの TortoiseCVS では、Windows 用に改行コードが自動変換されます。 php.net のリポジトリでは、これは不要です。 手元の変更をコミットされる場合は、Options で Use UNIX line endings をチェックしておいてください。

コマンドラインで、php-gtk-doc directory ディレクトリに移動するために cd php-gtk-doc と入力します。 そして autoconf と入力し、設定ファイルを作成します。

このビルド方式は完全に国際化 (i18n) されており、デフォルトの設定は英語 (en) に対応しています。英語以外の言語用にコンパイルするには、 configure の際にその言語の言語コードを指定します。たとえば ./configure --with-lang=de のようになります。 これは、その言語用の基盤となるファイル、 たとえばこの例ではドイツ語用のファイルがある場合にのみ動作します!

これ以外に使用する可能性のあるオプションは、 --with-php=PATH です。PATH の部分には、使用したい PHP バイナリ実行ファイルのフルパスを指定します。 たいていの場合は、PHP 4 あるいは PHP 5 のバイナリを autoconf が自動的に見つけてくれます。しかし、時にはちょっと変わった設定をしている人もいるものです。 ビルドの際には CLI を使用する必要がありますが、CGI がその邪魔をすることがあります。

複数ファイル分割方式のビルド (html、 phpweb、test) の際に、書き出されたファイルがいちいち表示されるのをとめるには、 --disable-output を使用します。 これを使用すると、ビルドにかかる時間がすこしは短くなります。

最後にもうひとつ、--with-history オプションについて説明しておきましょう。これは、 使用するかもしれませんししないかもしれません。これを使用して、 manual/* (php-gtk-doc/manual のスナップショット) のみを含む外部ディレクトリを指定します。 これを使用するのは make updates の場合のみで、 サーバ上で更新されたドキュメントの一覧を作成するために使用します。 通常は使用することはないでしょう。

最後に、出力方式を選択します。 make bigmanual.html とすると、ひとつの巨大な HTML ファイルが五分弱で出来上がります。make text も同じですが、それに加えて単一のテキストファイル形式のマニュアルも作成します。 make html は、各ディレクトリに分かれた複数の HTML ファイルを作成し、images ディレクトリをコピーします。 make phpweb は、gtk.php.net にある形式のマニュアルを作成します。 よくあるご要望にこたえて、これ以外にも make test id=ID が使用できます。ID の部分はマニュアルの ID で、 たとえば tutorials.helloadvanced あるいは gtk.gtkwindow などになります。これは、関連するファイル群を build ではなく testbuild というディレクトリに作成します。

ほとんど使わないであろう出力形式が、あと二種類あります。 make mtoc は、機械可読形式の表を XML 形式で作成し、 make updates はマニュアルの更新一覧を作成します。これは https://gtk.php.net/ のホームページで用いられます。

これ以外の出力フォーマットについても、近い将来に対応する予定です。

コマンドラインで cd php-gtk-doc と入力し、 php-gtk-doc ディレクトリに移動します。そして、基本ファイル群を作成するために ./runfirst.sh (Windows の場合は sh ./runfirst.sh) を実行します。runfirst スクリプトをコールするのは、 新しいファイルをマニュアルに追加したときか、あるいはビルド日を更新する必要があるときです。 つまり、マニュアルを毎日定期的にコンパイルしたい場合は、 これを毎回コールする必要があります。

では、マニュアルを作ってみましょう。まず最初に念を押しておきますが、 php-gtk のマニュアルはさまざまな言語で作成されており、 さらに先に説明したようにさまざまな形式で作成できます。 そのため、コンパイルする際にはどのマニュアルを作成するのかを知っておく必要があります。 言語の定義は、二文字のコードによって行います。たとえば en は英語、de はドイツ語といった具合です。形式の指定は、次のいずれかどなります。 html は通常の html で、 gtk.php.net からダウンロードできるものと同じ形式です。 phpweb は、PHP-GTK サイトのオンラインドキュメントと同じようなファイルを作成します。 test は、特定のファイルだけをコンパイルしたい場合に使用します。

./gen_manual.sh <language> <type> 形式でコールします。たとえば ./gen_manual.sh en html のようになります。 すると、ターミナルに次々に文字があふれ出すことでしょう。 ここで、いったん席をはずして十分後くらいに戻ってきましょう - ちょっと時間がかかります。ファイルは、ディレクトリ build/<language>/<type>/ に作成されます。この例では build/en/html/ です。

マニュアルを編集した際に、その編集した部分が正しい形式であり期待通りの html に変換されることを確かめたい場合は、 ./gen_manual.sh <language> test <id> 形式でコールします。たとえば ./gen_manual.sh en test gtk.gtkiconview のようになります。これは特殊なモードで、この指定したページ (id) をコンパイルするために必要な最小限のものだけに絞り込んだマニュアルを作成します。 しかしこのスクリプトは完全ではなく、(現在は) リファレンスファイルだけしか作成できません。 この多くのリンクは、うまく動作しません。

PHP がインストールされた Apache ウェブサーバがある場合は、 livedocs を使用できます。live.php をブラウザで開き (ウェブサーバ経由で開きます。 ローカルディレクトリではありません!)、マニュアルを閲覧してみましょう。 リクエストに応じて随時ページが作成されます。たいていは 1 秒から 2 秒でできあがります。