Qt (8)-2 QtAssistantで使うHELPファイルを作成する

公開日| 2009年06月26日 | コメントはまだありません。

カテゴリー:Qt |

概要 :
　Qtでは、WindowsでいうHTMLヘルプに変わるものとしてQtAssistantがあります。(先の記事でも記載しました。)
　このQtAssistantでは、独自ファイル(SQLite3フォーマット)のqchファイルとqhcファイルが必要となります。 (WindowsのHTMLヘルプでのchmファイルに相当します。)

　今回の記事では、そのQtAssistant用のHELPファイル(qchファイル,qhcファイル)の作成方法について記述します。

関連記事: Qt (8) QtAssistantのGUIの日本語化
関連記事: Qt (8)-3 Qtヘルプファイルを表示する

関連記事: http://doc.trolltech.com/4.5/qthelp.html

ここで使用したサンプルソースコード：

Qtサンプル12

QtAssistant用のHELPファイルについて

QtAssistant用のHELPファイルは、以下の２つの種類のファイルがあります。

ファイル種別	解説
.qchファイル	Qt Compressed Helpファイルつまりは、HTMLで記述されたドキュメント(画像などの付属情報も含めて)をSQLite3のデータベースファイル１つにまとめたものです。 Commpressedというが、実際には、zlibなどのような圧縮はされていないように思われます。 (あくまで、個人的な感想ですが、結構、大きなサイズになります。) qhelpgenerator コマンドで作成します。
.qhcファイル	Qt Help Collectionファイル単純には、.qchファイルを更に、SQLite3のデータベースファイル１つにまとめたものです。 HTMLドキュメントの実体は、あくまで、.qchファイルにあります。このファイルは、.qchファイルの管理を行うもので、検索などにも利用されているようです。 qcollectiongenerator コマンドで作成します。

更に、上記の２種のファイルを作成するための元ファイルがそれぞれ存在します。

ファイル種別	解説
.qhpファイル	Qt Help Projectファイル HTMLで記述されたドキュメント(画像などの付属情報も含めて)を１つのプロジェクトとして管理するためのXMLベースのファイルです。 Commpressedというが、実際には、zlibなどのような圧縮はされていないように思われます。 (あくまで、個人的な感想ですが、結構、大きなサイズになります。) qhelpgenerator コマンドで.qchファイルへ変換します。
.qhcpファイル	Qt Help Project Collectionファイル複数(一つでも可)の.qchファイルを、１つのコレクションとしての管理をするためのXMLベースのファイルです。ここでは、QtAssistantの画面の一部パーツのカスタマイズなども指定できます。 qcollectiongenerator コマンドで.qhcファイルへ変換します。

整理しておくと、以下のようになります。

HELPプロジェクトファイル(.qhp) -> .qch
HELPプロジェクトコレクションファイル(.qhcp) -> .qhc

ちょっと、複雑な感じです。
ただ、ここでは、以下のように捕らえておけば、なんとなく理解できるかもしれません。

プロジェクトをHTMLの管理
コレクションを全体の管理

WindowでのHTMLヘルプでは、以下のような構成だったと思います。

.hhcファイル(インデックス管理ファイル)
.hhkファイル(概要管理ファイル)
.hhpファイル(プロジェクト管理ファイル)

この２つのファイルから、.chmファイル(HTMLヘルプファイル)を作成します。

iniファイルフォーマットとXMLフォーマットの違いや、書く場所は異なりますが、基本的にHTMLヘルプファイル作成で必要な情報は、Qtヘルプでも必要と考えておけば良いと思います。
以降に、詳細な項目の説明がありますのでご参照ください。

Qtヘルプの元となる、HELPプロジェクトファイル(.qhp)、HELPプロジェクトコレクションファイル(.qhcp)の構成を以降に説明し、簡単な、Qtヘルプファイルを作成してみましょう。

HELPプロジェクトファイル(.qhp)について

HELPプロジェクトファイル(.qhp)は、XML形式で、一般的にUTF8で記述します。

まずは、簡単なサンプルを見てみましょう。

<?xml version="1.0" encoding="UTF-8"?>
    <QtHelpProject version="1.0">
    <namespace>Sample_Help</namespace>
    <virtualFolder>doc</virtualFolder>
    <customFilter name="Sample Help 1.0">
        <filterAttribute>Sample Help Application</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute>Test Help Application</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
        <toc>
            <section title="Sample Help" ref="index.html">
                <section title="Chapter 1" ref="doc1.html"/>
                <section title="Chapter 2" ref="doc2.html"/>
                <section title="Chapter 3" ref="doc3.html"/>
            </section>
        </toc>
        <keywords>
            <keyword name="keyword1" id="TestHelp::key1" ref="doc1.html"/>
            <keyword name="keyword2" ref="doc2.html"  />
            <keyword id="TestHelp::key2" ref="doc3.html"/>
        </keywords>
        <files>
            <file>index.html</file>
            <file>doc1.html</file>
            <file>doc2.html</file>
            <file>doc3.html</file>
            <file>img1.png</file>
            <file>img2.png</file>
            <file>img3.png</file>
        </files>
    </filterSection>
</QtHelpProject>

ここでは、以下の４つのHTMLドキュメントが既にあるものとして記述しています。

index.html
doc1.html
doc2.html
doc3.html

１行目は、XML形式の宣言と文字コードの指定です。
２行目は、Qtヘルププロジェクトのバージョン指定です。 2009.6時点では、"1.0"が最新です。これを見ても、このQtヘルプが最近、導入されたことがわかります。

３行目以降の各タグについて、以下の表で簡単に解説します。

HELPプロジェクトファイル(.qhp)

TAG名	解説
Namespace	このプロジェクトの名前(このプロジェクトへアクセスするためのアドレスになります)
virtualFolder	仮想ディレクトリ名(Namespaceに続くアドレスになります)
filterSection	フィルター定義デフォルトのフィルター定義です。このフィルター定義には、以下の更に詳細なタグを設定できます。 filterAttributeタグ:フィルター名、バージョンなどを定義します。 tocタグ:コンテンツツリーを定義します。ここでは、sectionタグを用いて、コンテンツタブに表示する情報を、階層化して表示順序を指定します。 keywordsタグ:インデックスを定義します。ここでは、keywordタグを用いて、インデックスタブに表示するキーワードを指定します。 filesタグ:HTMLドキュメントで使用しているファイルを定義します。ここでは、fileタグを用いて、HTMLドキュメントで使用している全てのファイルを定義します。
customFilter	カスタムフィルター定義 filterSectionタグと同様の定義でき、フィルターバーで選択することで、ここに定義したものだけを表示するようにもできます。

ここで、注意すべき点は、 HTMLドキュメントで使用している全てのファイルを定義しなければならないことです。
関連している画像ファイルや、CSSファイル、jsファイルなども全て指定しなければならないことに注意しなければなりません。

WindowのHTML ヘルプワークショップでは、HTMLファイルさえ指定すれば、自動で関連ファイルを取り込んでくれたのですが、 Qtヘルプの各コマンドでは、取り込みません。

さすがに、この部分は、閉口感があります。（早く、改善して欲しいものです。）

続けて、HELPプロジェクトコレクションファイル(.qhcp)について解説したいと思います。