この章では、PHP-GTK 2 のドキュメント作成に貢献するための情報をとりあげます。 わからないことがある場合は、 php-gtk-doc メーリングリスト で質問してみましょう。
何らかのドキュメントを書いたなら、おそらくそれを公式マニュアルに追加したくなることでしょう。 そういった場合は、そのファイルを先ほど述べた php-gtk-doc メーリングリストに送るか、あるいは ドキュメントのクレジット に挙げられている貢献者の誰かに直接メールを送ってください。 彼らがあなたのドキュメントを CVS サーバに置いてくれるでしょう。 もし今後もずっと貢献を続けていくつもりなら、CVS アカウントを取得するとよいでしょう。 メーリングリストでアカウントを申請してください。
CVS アカウントを取得したら、変更をコミットする前には 常に マニュアルをコンパイルしてみるようにしましょう。 xml に問題があると、毎晩のマニュアル生成処理に失敗し、 他のみんなに迷惑がかかります。
マニュアルのソースは 300 以上のファイルで構成されています。 そして、まだまだ空白の部分が多くあります。 マニュアルを見ていて記述が足りない箇所にお気づきの場合は、 ぜひその部分に手を入れてください。 記述が足りない部分がどこにあるかわからない場合は、マニュアルのファイルを FIXME および TODO で検索してください。 そこからはじめるといいでしょう。
すでにお気づきでしょうが、マニュアルのソースは manual/ ディレクトリ内にあります。 この中に、各言語用のフォルダが含まれます。 manual/en/reference/ の中を見てみましょう。すると gtk や gdk のフォルダが見つかるでしょう。 すべてのクラスについて、これらのフォルダのいずれかの中に そのクラス用の xml ファイルが存在します。 これにより、複数の人がマニュアルの異なる部分を同時に作業できるようになります。 また、貧弱なマシンでもマニュアルのファイルを開けるようになります。
おそらく、新しいファイルを追加する必要はないでしょう。 少なくとも、クラスのドキュメントについてはすべて雛形が存在するからです。 新しいファイルを追加する際には、それを manual/reference.xml に登録することを忘れないようにしましょう。 そうしないと、追加したファイルがマニュアルに含められません。
クラスの画像は、別のディレクトリ images/ にあります。 このディレクトリの構造は、xml ファイルの構造とほぼ同じです。 たとえば GtkAboutDialog 用の画像は images/reference/gtk/gtkaboutdialog.png となります。 新しい画像を作成する場合は、できるだけサイズを小さくしてください。 30kb だとちょっと大きすぎです。すべての画像がそんな大きさだと、かなりの負荷になります。 また、ファイル形式は .png を用い、 色パレットを小さな固定値とすることでファイルサイズを節約してください。
実行可能なサンプルは、別のディレクトリ examples/ におきます。このディレクトリの構造は、画像や xml 文書ファイルとほぼ同じです。 ただ、各クラスごとのディレクトリが存在するという点が違います。 ファイル名は、使用例を示す関数/メソッドの名前をもとにして決まります。たとえば GtkAboutDialog の set_logo() 関数のサンプルは、 examples/reference/gtk/gtkaboutdialog/set_logo.phpw となります。拡張子に注意しましょう。デフォルトのコンストラクタのファイル名は constructor.phpw です。
最初に言っておきます。ドキュメントを書くツールは、なんでも好きなものでかまいません。 個人的には KDE のテキストエディタ Kate が好きですが、 別に vi や emacs でもかまいませんし、 なんだったら メモ帳 であったって別に問題ありません。 注意: 非 ASCII 文字を使用する場合は、 UTF-8 でのファイル保存に対応している必要があります。
ドキュメントは、構造化テキスト形式になります。 テキストは段落の中になければなりませんし、特定の単語を 強調 したり、あるいは リテラル として扱ったりしたい場合は、それを指定する必要があります。 HTML のページを書いたことがある人なら、 何が言いたいのかおわかりでしょう。
じゃあ、なぜ HTML のタグを使わないのかと疑問に思われるかもしれません。 その理由は、DocBook があくまでテキストの構造を記述するためのものであり、 テキストの整形を行うためのものではないからです。 HTML は、レイアウト (CSS) とコンテンツ (XHTML) をうまく分離しようとしています。 しかし、DocBook で作成するのは HTML だけではありません。 PDF や、実際の書籍の作成にも使用されます。書籍には、多くの特殊な要素があります。 たとえば章、節、例、そしてプログラミングマニュアルにおける メソッド、パラメータ、プロパティ、シグナルなどなどです。 それぞれの要素に対して、固有のタグが定義されています。 そのせいで、最初に docbook を使い始めたときには混乱するかもしれません。 しかし、これにより、出力内容を完全に制御できるという利点があるのです。
最も基本的な要素が <para> です。 これを使用して、テキストを段落に分けます。段落の中には、 リンク (link) やファイル名 (filename)、 そして表 (table) などの他のタグを含めることができます。 特別な段落型として <simpara> というものもあり、こちらはその内部に他のタグを含みません。
次に重要になるタグはリンクです。 この節 を参照ください。
単語や熟語を 強調 するには、 <emphasis> を使用するか、リテラル を <literal> で定義します。 ファイル名 を表すには <filename>、 変数 を表すには <varname> を使用します。それ以外にもさまざまなタグがありますが、 全部紹介しようとすると、それだけでひとつのマニュアルになってしまいます。
項目を箇条書きしたい場合は、<itemizedlist> (順序を指定しない) あるいは <orderedlist> (順序つき) タグを使用します。各項目は、<listitem> タグで囲みます。
<listitem> の内部には <para> やその他のタグを含めることができます。ほとんどの場合はクラスのドキュメントの雛形がすでに用意されています。 あなたがしなければならないことは、その説明や上で説明したタグを埋めていくことだけです。 中身を埋めなければならないタグは次のふたつです。 <shortdesc> には、 クラス/関数/シグナル/プロパティ についての簡単な説明を記入します (一段落でまとめ、できれば中に何のタグも含めないようにします)。 そして <desc> にはそのクラスの完全な説明を記入します (複数の段落を使用します)。
どこから手をつけていいのかわからない場合や、 選択したタグが正しいのかどうかが不安な場合は、 他の既存のファイルを参照ください。いい例となるでしょう。
リンクがあってこそのマニュアルです。リンクによってページ間をつなぎ、 関連する節にクリックひとつでジャンプできるようになります。 他のクラスや似た関数を参照する場合は、そこにリンクするようにしましょう。 それにより、読者が検索する手間を省けます。
マニュアルで使用できるページ間リンクは、次の四種類です。
クラスへのリンク は、そのクラスの概要ページにリンクします。 たとえば、
とすると GtkAboutDialog の概要ページにリンクします。 これは、GtkAboutDialog のようになります。メソッド/関数へのリンク は、 そのクラスの特定のメソッドや関数にリンクします。 関数名には、自動的に () が付加されます。 これを使用するには
のようにします。こうすると、マニュアル上では set_logo() のようになります。 パラメータ class は、 現在のクラスへリンクする際には必須ではありません。 しかし、常につけておくようにしましょう。 その内容をマニュアルの他のページにコピーする際に、余計な手間が省けます。- これは "close" のようになります。
- これは GtkButtonBoxStyle のようになります。 列挙子やフラグへのリンクは、次のようなオプションフィールドによっても可能です。 これは Gtk::ICON_LOOKUP_FORCE_SVG のように変換されます。
- これは action_area のようになります。
マニュアル内のフリーリンク は、テキスト内の特定の単語にリンクしたり チュートリアルの特定の節にリンクしたりする際に必要となります。 リンク先の節の ID を指定したうえで、好きなタイトルを選択します。
この結果は、 「マニュアルのコンパイル方法は ドキュメント作成のチュートリアル にあります。」 となります。URL へのリンク はマニュアルの中でも可能です。 HTTP、FTP やメールアドレスへの普通のリンクも使用することができます。
は ドキュメントメーリングリスト となります。もしマニュアル内で特定のリンクを何度も使用するのなら、 manual/global.ents の XML エンティティにそれを追加しましょう。すると、 が [email protected] となるのと同様に、 と書けば ドキュメントメーリングリスト となります。<ulink url="mailto:[email protected]">ドキュメントメーリングリスト</ulink>
PHP-GTK 2 のドキュメントは、PHP-GTK 1 用に作られたこれまでのドキュメントと異なり、 画像や外部のサンプルコードをサポートしています。
画像には三種類の形式があります。 クラスの画像、独立した段落を構成する通常の画像、 そしてテキスト中にインライン形式で配置できる画像です。
クラスの画像 は、 クラスの概要ページで説明の右側に表示されるものです。これは、単に
のように追加するだけです。 基底ディレクトリ &directory.images; に注目しましょう。 これは、コンパイル時に正しい画像ディレクトリに変換されます。通常の画像は、段落の中に
のように指定します。インライン画像は となります。サンプルコードも、マニュアルファイルから分離させることができます。 これは、実際にサンプルを実行させたい読者にとって便利です。 コードをいちいちコピーペーストする必要はなく、サンプルコードを直接実行できるのです。 さらに、マニュアルを作成したり編集している際にサンプルコードをテストするのも簡単です。
サンプルを別ファイルにできるのは、それが完全に実行可能なプログラムである場合 のみ です。コードの一部だけの場合はインラインにする必要があります。
別ファイルに分けたサンプルは、このようにして使用します。
<example>
<title>単純な GtkAboutDialog</title>
<programlisting role="php">
<xi:include xmlns:xi="https://www.w3.org/2001/XInclude"
href="../&directory.examples;/reference/gtk/gtkaboutdialog/constructor.phpw"
parse="text">
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
</xi:include>
</programlisting>
</example>
|
サンプルコードの一部をインライン表示するには、このようにします。
<informalexample>
<programlisting role="php"><![CDATA[
// ここに php のコードを書きます
]]></programlisting>
</informalexample>
|