Qt Help プロジェクト

Qt Helpプロジェクトは、圧縮されたヘルプファイルを生成するために必要なすべてのデータを収集します。目次、索引キーワード、ヘルプドキュメントといった実際のヘルプデータに加え、ヘルプファイルを識別するための名前空間などの追加情報も含まれます。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 Helpでは、必須のネームスペースタグによって定義されるネームスペースを識別子として使用します。上記の例では、ネームスペースは「mycompany.com.myapplication.1.0」となります。

仮想フォルダ

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

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

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

上記の例では、仮想フォルダとして「doc」を指定しています。別のマニュアル（例えば、小さな補助ツール「My Application」のマニュアル）でも同じフォルダが指定されている場合、「doc.html#section1」と記述するだけで、「My Application」マニュアルの最初のセクションを参照することができます。

仮想フォルダタグは必須であり、フォルダ名にはスラッシュ (/) を含めてはなりません。

セクションのフィルタリング

フィルタセクションには、実際のドキュメントが含まれます。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 Helpプロジェクト内のすべてのファイル参照と同様に、ヘルププロジェクトファイル自体を基準とした相対パスです。

キーワード

...
<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>
...

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

ファイル

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

最後に、実際のドキュメントファイルを一覧指定する必要があります。ヘルプの表示に必要なすべてのファイルが指定されていることを確認してください。つまり、スタイルシートや類似のファイルも同様に一覧に含める必要があります。これらのファイルは、Qt Helpプロジェクト内のすべてのファイル参照と同様に、ヘルププロジェクトファイル自体を基準とした相対パスで指定されます。 例が示すように、ファイル（ディレクトリを除く）はワイルドカードを使用したパターンとして指定することもできます。リストされたすべてのファイルは圧縮され、Qtの圧縮ヘルプファイルに書き込まれます。したがって、最終的には、1つのQt Helpファイルに、すべてのドキュメントファイルと、コンテンツおよび索引がすべて含まれることになります。