Qt Help プロジェクト

Qtヘルププロジェクトは、圧縮されたヘルプファイルを生成するために必要なすべてのデータを収集します。目次、索引キーワード、ヘルプドキュメントのような実際のヘルプデータとともに、ヘルプファイルを識別するための名前空間のような余分な情報が含まれています。1つのヘルププロジェクトは1つのドキュメントセット、例えばqmakeマニュアルを表します。

Qt Help プロジェクトファイルの形式

ファイルフォーマットはXMLベースです。フォーマットをよりよく理解するために、以下の例について説明します：

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
    <namespace>mycompany.com.myapplication.1.0</namespace>
    <virtualFolder>doc</virtualFolder>
    <customFilter name="My Application 1.0">
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
        <toc>
            <section title="My Application Manual" ref="index.html">
                <section title="Chapter 1" ref="doc.html#chapter1"/>
                <section title="Chapter 2" ref="doc.html#chapter2"/>
                <section title="Chapter 3" ref="doc.html#chapter3"/>
            </section>
        </toc>
        <keywords>
            <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
            <keyword name="bar" ref="doc.html#bar"/>
            <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
        </keywords>
        <files>
            <file>classic.css</file>
            <file>*.html</file>
        </files>
    </filterSection>
</QtHelpProject>

名前空間

QHelpEngine 、与えられたリンクに対して適切なドキュメントを検索できるようにするため、すべてのドキュメント・セットには一意の識別子が必要です。一意な識別子は、ヘルプコレクションがファイル名に依存せずにドキュメントセットを追跡することを可能にします。Qt ヘルプシステムでは、必須の名前空間タグで定義された名前空間を識別子として使用します。上の例では、名前空間は "mycompany.com.myapplication.1.0 "です。

仮想フォルダ

すべてのドキュメントセットに名前空間を持つことは、当然、ドキュメントセットが完全に分離されていることを意味します。ヘルプエンジンの観点からは、これは有益です。しかし、書き手の立場からすると、絶対リンクを指定することなく、あるマニュアルから別のマニュアルへ特定のトピックを相互参照したいことがよくあります。この問題を解決するために、ヘルプシステムは仮想フォルダの概念を導入しました。

仮想フォルダは、圧縮されたヘルプファイルで参照されるすべてのファイルのルートディレクトリになります。2つのドキュメントセットが同じ仮想フォルダを共有している場合、お互いを指すハイパーリンクを定義する際に相対パスを使用することができます。ファイルが両方のドキュメントセットに含まれている場合、現在のセットのものが優先されます。

...
<virtualFolder>doc</virtualFolder>
...

上記の例では、仮想フォルダとしてdocを指定しています。他のマニュアルが同じフォルダを指定している場合、例えば小さなヘルパーツールMy Applicationの場合、My Applicationマニュアルの最初のセクションを参照するにはdoc.html#section1と書けば十分です。

仮想フォルダのタグは必須で、フォルダ名にはスラッシュ（/）を入れてはいけません。

フィルターセクション

フィルターセクションには、実際のドキュメントが含まれます。Qt Help プロジェクトファイルには、複数のフィルターセクションを含めることができます。すべてのフィルターセクションは、目次、キーワード、ファイルリストから構成されます。理論的には、すべての部分はオプションですが、何も指定しないと空のドキュメントセットになります。

目次

...
<toc>
    <section title="My Application Manual" ref="index.html">
        <section title="Chapter 1" ref="doc.html#chapter1"/>
        <section title="Chapter 2" ref="doc.html#chapter2"/>
        <section title="Chapter 3" ref="doc.html#chapter3"/>
    </section>
</toc>
...

1つのセクションタグは、目次の1つの項目を表します。セクションはどの程度まで入れ子にすることもできるが、ユーザーの立場からすると、4～5階層以上にはすべきではない。セクションは、タイトルと参照によって定義されます。参照は、Qt ヘルププロジェクトのすべてのファイル参照と同様に、ヘルププロジェクトファイル自体からの相対参照です。

キーワード

...
<keywords>
   <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
   <keyword name="bar" ref="doc.html#bar"/>
   <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
</keywords>
...

キーワードセクションには、このフィルターセクションのすべてのキーワードがリストされています。キーワードは基本的に名前とファイル参照からなる。属性名が使用された場合、そこで指定されたキーワードは可視インデックスに表示されます。つまり、QHelpIndexModel クラスからアクセスできるようになります。idが使用された場合、キーワードはインデックスに表示されず、QHelpEngineCore::documentsForIdentifier （）を介してのみアクセス可能となります。nameと idは同時に指定することができます。

ファイル

...
<files>
    <file>classic.css</file>
    <file>*.html</file>
</files>
...

最後に、実際のドキュメントファイルを列挙しなければなりません。ヘルプを表示するために必要なファイルがすべて記載されていることを確認してください。つまり、スタイルシートや同様のファイルもリストアップする必要があります。Qtヘルププロジェクトにおけるすべてのファイル参照と同様に、ファイルはヘルププロジェクトファイル自体からの相対的なものです。例にあるように、ファイル（ディレクトリではない）はワイルドカードを使ってパターンとして指定することもできます。リストされたファイルはすべて圧縮され、Qt圧縮ヘルプファイルに書き込まれます。そのため、最終的には、1つのQtヘルプファイルに、すべてのドキュメントファイルとその内容やインデックスが含まれることになります。