GNOME でドキュメントを作成し、利用してみる。
ドキュメントを作成し、翻訳を行い、インストールを行って、
最終的に yelp で閲覧するところまで。
今回は GNOME Photo Frame
のヘルプを例とする。
通常の GNOME アプリケーションとは異なり、Python を使う。
以下のツールが必要となる。
- gnome-doc-utils
- pkg-config
- rarian-compat
■1. 作成するデータ
作成するデータは以下の通り。
- ヘルプ本体の XML ファイル
- ヘルプを登録するための OMF ファイルの雛形
- 翻訳のための PO ファイル
基本的なファイルは以下のように help ディレクトリに配置する。
help/
gphotoframe.omf.in
C/gphotoframe.xml
C/figure/gphotoframe.png
ja/ja.po
ja/figure/gphotoframe.png
インストールする前には
PO ファイルから、ヘルプの XML ファイルと、OMF ファイルを
各言語ごとに生成する必要がある。
・ヘルプ本体の XML ファイル
適当に他の GNOME ドキュメンテーションの XML ファイルを参考に書けると思う。
基本的には 1 ファイルで、1 ドキュメントを記述する。
ちゃんとしたことは以下を参照。
ちなみに GNOME アプリケーションのドキュメントのライセンスは、だいたい
GNU Free Documentation License (GFDL) になっているみたい。
・OMF ファイルの雛形
ドキュメントをシステムに登録するには、
OMF (Open Metadata Framework) ファイルが必要になる。
GNOME Photo Frame だと以下の通り。これを gphotoframe.omf.in として
help ディレクトリに配置する。
<?xml version="1.0" standalone="no"?>
<omf>
<resource>
<subject category="GNOME|Applications|Graphics"/>
<type>user's guide</type>
<relation seriesid="01bfe79a-d094-c319-a063-ca3c4b5eb74d30"/>
<rights type="GNU FDL" license.version="1.1" holder="Cristian Marchi"/>
</resource>
</omf>
このうち seriesid はコマンド scrollkeeper-gen-seriesid で生成する。
・PO ファイル
XML ファイルの翻訳には xml2po を使う。ドキュメントの
po は、メッセージカタログの po とは別途管理する。
help ディレクトリに移動してから、以下のコマンドを実行する。
POT ファイルを作成する。後で説明するが、最終的には OMF
ファイルを生成しておき、以下のようにこれも翻訳対象ファイルとして指定しておいた方がよい。
% xml2po -o help.pot C/gphotoframe.xml C/gphotoframe-C.omf
% cp help.pot ja/ja.po
PO ファイルを更新する
% xml2po -u ja/ja.po C/gphotoframe.xml C/gphotoframe-C.omf
詳しい使用法は man を参照。
■2. ビルド
通常の GNOME アプリケーションなら gnome-doc-utils.make を使う。
Migrating to GNOME Documentation Build Utilities の
2.2 を参考にすればよい。ただ、Python など、make
を使わないシステムで、ビルドを自前でやろうとすると結構面倒。
・各言語用に OMF ファイルを生成
gphotoframe.omf.in から OMF を生成するには、xsltproc で行う。
これは各言語ごとに行うが、後で翻訳を行うためにも、まずは C 向けの OMF
を作成する。なお、対象となる XML
ファイルが翻訳されていると、それに応じて各要素も翻訳が行われる。OMF
ファイル用に別途 PO ファイルが必要になることはない。
% xsltproc \
-o ./C/gphotoframe-$lang.omf \
--stringparam db2omf.basename gphotoframe \
--stringparam db2omf.format 'docbook' \
--stringparam db2omf.dtd "-//OASIS//DTD DocBook XML V4.1.2//EN" \
--stringparam db2omf.lang C \
--stringparam db2omf.omf_dir "/usr/share/omf" \
--stringparam db2omf.help_dir "/usr/share/gnome/help" \
--stringparam db2omf.omf_in ./gphotoframe.omf.in \
`pkg-config --variable db2omf gnome-doc-utils` \
./C/gphotoframe.xml
OMF ファイルの生成は面倒なので、スクリプトを用意した方がよいだろう。
gphotoframe では、
makedoc.py
- gphotoframe のようなスクリプトを用意した。
・各言語用に XML ヘルプファイルを生成
xml2po を利用する。
% xml2po -p ja/ja.po -o ja/gphotoframe.xml C/gphotoframe.xml
・Python でのインストール
C なら標準のビルドシステムを使うだけなのだが、python の場合は
DistUtilsExtra
を使うのが今のところ一番楽みたい。
setup.py と setup.cfg の記述については上記のリンクを参照。
OMF ファイル、XML ファイルなどを各言語ごとに全部生成しておく必要はあるが、
決められたフォルダ (デフォルトでは help)
にそれらを置いておけば、setup.py でインストールで可能となる。
■3. 閲覧
・yelp の利用
閲覧に GNOME の標準システムでは yelp を使う。
インストール済みならば、URI で開くことができる。
% yelp ghelp:gphotoframe
ゆえにプログラムから呼び出すには、show_uri をコールすればよい。
Python なら以下の通り。
gtk.show_uri(None, 'ghelp:gphotoframe', gtk.gdk.CURRENT_TIME)
インストール前に試し読みするならば、ファイルを直接指定してもよい。
ただ、いずれにせよ OMF ファイルは必要になる。
% yelp ja/gphotoframe.xml
・HTML の生成
ブラウザで閲覧できるように、HTML を生成することもできる。
% xsltproc -o /tmp/index.html /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl ja/gphotoframe.xml
]]>
