Pythonの日本語訳ドキュメントをDevhelpで参照する(メモ・2011年1月末時点)

2011年1月末時点ではPythonの日本語訳ドキュメントはEPUB,CHM,HTMLファイル群と複数の形式で配布されているが、GNU/Linux上で参照しやすい形式はこの中にはなく、CHM形式も開けるツールがあることはあるのだが、見栄えがHTMLファイル群より悪いのと見出しの文字化けが起こるのとで使いにくく、HTMLファイル群を用いるのが一番まともではあるのだが、そのままではたどりにくさや検索のしにくさを感じていた。
そこで「GLibやGTK+などに関連するライブラリのAPIリファレンスを参照するのに便利なDevhelpについて」で扱ったドキュメントビューアのDevhelpが使えないかと考え試行錯誤したところ、HTMLファイル群を含んだディレクトリを/usr/share/gtk-doc/html/に配置した上でそのディレクトリへ簡単な構造のXMLファイル(.devhelp2ファイル)を配置するだけでうまく表示できることが分かった。
(2011/2/5)/usr/share/gtk-doc/html/の代わりに/usr/share/devhelp/books/以下でも参照できることが分かった。/usr/share/gtk-doc/html/はGTK-Docというツールが出力するものの書き込み先なので、他の方法で生成されたものは/usr/share/devhelp/books/のほうが良さそう。

.devhelp2ファイルの内容について
表示上の問題とその対処

.devhelp2ファイルの内容について

.devhelp2ファイルの基本的な構造は

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE book PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "">
<book xmlns="http://www.devhelp.net/book" title="[ドキュメント名]" link="[トップページのファイル名]" author="[作者]" name="[名前]" version="2" language="[言語名]">
  <!-- chapters要素の下のsub要素が目次の項目となる -->
  <chapters>
    <sub name="[セクションのリンク文字列]" link="[リンク先のパス]"/>
    <!-- (中略) -->
    <sub name="[セクションのリンク文字列]" link="[リンク先のパス]"/>
  </chapters>
  <!-- functions要素は省略可 -->
  <functions>
    <!-- keyword要素のsince属性で「バージョンx.yから」のような記述が可能? -->
    <keyword type="[空文字列もしくはfunction,struct,macro,signal,enum,property,typedef,unionなど?]" name="[キーワードの名前]" link="[リンク先のパス]"/>
    <!-- (中略) -->
    <keyword type="[空文字列もしくはfunction,struct,macro,signal,enum,property,typedef,unionなど?]" name="[キーワードの名前]" link="[リンク先のパス]"/>
  </functions>
</book>

で、sub要素は子のsub要素(同様にして更にその子,孫,...)を含むこともできる。子を持たない階層は空要素(タグの末尾に「/」を付ける)とする。

    <sub name="[セクションのリンク文字列]" link="[リンク先のパス]">
      <sub name="[セクションのリンク文字列]" link="[リンク先のパス]">
        <sub name="[セクションのリンク文字列]" link="[リンク先のパス]"/>
      </sub>
    </sub>

リンク先のパスは最上位ディレクトリ(/usr/share/gtk-doc/html/[名前]/や/usr/share/devhelp/books/[名前]/)からの相対パスとなる。
(2011/2/5)ディレクトリに関する記述を追加

表示上の問題とその対処

実際にバージョン2.6のPythonの日本語訳ドキュメントのHTMLファイル群をDevhelpで開けるようにするための.devhelp2ファイルを最小限構成(トップページからのリンク先のみ)で記述して表示してみた。ところが

上のようにレイアウトのための余白が場所を取ってしまうので、_static/sphinxdoc.cssのbody要素のmarginを「0px」指定にした。すると

このようになり、うまくおさまるようになった。
しかし、これだけでは左の目次からそれぞれの中の階層がたどれない上に「検索」タブの検索もほとんどできないため、階層の分だけsub要素を追加していくことになった。

画像は途中まで作業した状態のもので、実際に目次のツリー上の任意の階層をたどって右側にそのページの内容を開くことができているが、この追加作業は目次のツリーの各項目の名前(目次上の表示文字列)とそれに対応するリンク先とを1つのsub要素として追加する地道なもので、ドキュメント全体の全ての項目を目次から選択可能にするにはかなりの手間と時間がかかる見通し。

次: Pythonの日本語訳ドキュメントをDevhelpで参照する(2011年2月上旬時点・ファイル配布)

使用したバージョン:

Devhelp 2.30.1

試験運用中なLinux備忘録・旧記事

はてなダイアリーで公開していた2007年5月-2015年3月の記事を保存しています。

Pythonの日本語訳ドキュメントをDevhelpで参照する(メモ・2011年1月末時点)

.devhelp2ファイルの内容について

表示上の問題とその対処