GNOME ドキュメントの作成と利用

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

2010/10/26 (Tue) 00:53 | タグ: computer