ドキュメント作成や翻訳に関する FAQ
新しいパッケージのドキュメントを追加したのに、 コンパイルされたマニュアルにそれが表示されません!
よくある理由は ./configure の実行を忘れていることです。 これにより、新しいページが検出され、含められるようになります。
別の理由としては、親ページにリンクを追加し忘れていることが考えられます。 en/package/ に、各パッケージのドキュメントへのリンクを含む xml ファイルがカテゴリごとに存在します。新しいページへのリンクをここに追加してください。
cannot generate system identifier for general entity "package.networking.net-ldap.search" のようなメッセージが表示された場合も、原因は同じです。
マニュアルをコンパイルしようとすると、結果がターミナルに表示されてしまいます。 ファイルができあがりません!
configure が DSSSL スタイルシートあるいは XSLT スタイルシートを見つけられませんでした。 まず最初にそれをインストールしてください。
スタイルシートがインストールされていれば、./configure はそのディレクトリを次のように出力します。
checking for docbook.dsl... autodetected: /path/to/dsssl-stylesheets-x.yz
checking for docbook.xsl... autodetected: /path/to/xsl-stylesheets-x.y.z
PEAR マニュアルの翻訳にあたって、元の英語版の変更点の 追跡を楽にするツールはありませんか？
翻訳作業に携わるということは、 単に英語のファイルを翻訳し結果をコミットするだけで終わりません。 英語ファイルの変更にあわせて翻訳済みのファイルを更新するのにも、 たくさんの労力が必要となります。 英語版のファイルに加えられた変更を追っかけるためには、 PEAR ドキュメンテーション メーリングリスト を購読し、コミットメッセージやアーカイブを確認するべきです。 更新が行われなければ、翻訳の利用価値がなくなっていきます。
更新するべき場所がどこなのかに加え、 いつ・だれがそのファイルを翻訳したのかということがわからなければ、 翻訳済みファイルの更新は困難となります。 そこで、PEAR には、 peardoc のファイルの変更日および リビジョンを追跡するシステムがあります。
リビジョンコメント
リビジョンコメントのシステムは、ファイルごとに情報を記録します。 中央の単一ファイルに全情報を記録するシステムではありません。 翻訳者・リビジョン番号およびステータス情報に関する情報を、 各ファイルごと、リビジョンコメントに記述します。 たとえば、ファイル bookinfo.xml のヘッダを見てみましょう。
<!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->
翻訳の更新がなされた最新の英語版ファイルのリビジョン番号 (EN-Revision: 1.16)、および、 翻訳者の CVS アカウント名が記されています。 必要ならば、ステータス情報を追加することができます （例、部分的な翻訳に対しては"partial"）。 このリビジョンコメントのシステムでは、情報を 1 つの場所にまとめて記述するのではなく、各 XML ファイルに記述します。 英語版のファイルは 2400 以上もあるので、このほうが非常に便利です。
現在、3 つのフィールド (英語リビジョン・メンテナ・状態) があり、すべてが必須項目です。メンテナ (Maintainer) は CVS のユーザ名、 あるいは空白文字のないニックネームを用います。 状況 (Status) は空白なしで何でもありです。 このヘッダは、CVS によって 自動的に更新されませんので注意してください。 自分自身で編集し、更新してください
リビジョンコメントの良さは理解いただけたことと思います。 ただし、リビジョンコメントを使用すると、 （ひとつのファイルに情報がまとまっていないので） 翻訳済ファイルのリストをさっと見る、なんて言うことができなくなります。 しかし、心配ありません。 /peardoc/ ディレクトリで次のコマンドを実行すると、 翻訳済ファイルのリストを作成できます。
./scripts/revcheck_pear.php xx > revcheck.html
ここで、xx は言語コードです（日本語なら ja）。 このスクリプトを実行させると、 同じディレクトリに revcheck.html が作成され、 そこには、指定した言語のすべてのファイルのリビジョン比較や diff への リンクがまとめられています。 さらに、メンテナの名前をパラメタとして付加すると、 指定したメンテナが係わったファイルのリストを得ることもできます。
このスクリプトには、オプション拡張がいくつかあり、 生成される HTML ページに対して適用されます。 translation.xml というファイルを使用します。 次に、言語 xx 向けのシンプルな translation.xml の例を示します。
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">
<translation>
<intro>
This is some introductory text for the xx language translators
about who is the manager of the translation, and where to find
more information. This paragraph is printed on the top of the
generated revcheck.html page.
</intro>
<translators>
<person name="Joe Doe" email="joe@hotmail.com"
nick="joedoe" cvs="yes" editor="yes"/>
<person name="Jane Smith" email="jsmith@yahoo.com"
nick="jane" cvs="yes"/>
<person name="Joe Forever" email="joe@forever.net"
nick="joefo" cvs="no"/>
</translators>
<work-in-progress>
<file name="appendices/aliases.xml" person="joedoe"
type="working"/>
<file name="functions/dbx.xml" person="joefo"
type="working"/>
</work-in-progress>
</translation>
このファイル（の translators 要素）には、 CVS アカウントを持たないユーザも加えることができ、 翻訳済のドキュメント（のリビジョンコメント）にも、 更新中のファイル（work-in-progress 要素）にもアサインできます。 このアドオンを使用する最大の利点は、 revcheck.html のファイル中に、 翻訳者やファイルについての動的なテーブルを生成する際に、 これらの情報が使われるということです。 各ファイルから関連する各翻訳者へのリンクが生成されます。 また、きれいな表で各翻訳者のステータスを表示します。 時間がかかる更新が行われている場合は、 更新中のファイルを（work-in-progress 要素に）アサインすると良いでしょう。
<file> には、date および revision という 2 つのオプションのパラメータが付加できます。 前者は、作業が開始された日付です。後者は、 作業の開始のためにチェックアウトされた英語ファイルのリビジョンです （表中にそのリビジョンが記載されます）。 現在のところ、date パラメータに決まった形式はありません。
さらに、このシステムには、個々のファイルについて、現在のメンテナ以外に作業した すべての人のクレジット（名前表示）をするためのアドオンがあります。 それには、クレジットコメントを付加します。 たとえば、history.xml におけるクレジットコメントは、 次のようになります（この例では、Joe Doe がはじめにファイルを翻訳して、 Jane がメンテナを引き継いでいます）。
<!-- CREDITS: joedoe -->
クレジットコメントには、コンマ区切りで複数の翻訳者のリストを記すことができます。 revcheck.html の翻訳者に関する表の表示のところに、 これらのコメントの内容が反映されます。
忘却曲線を使ってこの知識を確実に記憶に残す
