Qtヘルププロジェクト

Qt ヘルプ プロジェクトは、圧縮ヘルプ ファイルの生成に必要なすべてのデータを収集します。目次、インデックス キーワード、ヘルプ ドキュメントなどの実際のヘルプ データに加えて、ヘルプ ファイルを識別するために使用される名前空間などの追加情報も含まれています。ヘルプ項目はドキュメント セットを表します。

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

ファイル形式は 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」です。

仮想フォルダー

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

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

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

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

仮想フォルダーのラベルは必須であり、フォルダー名にはスラッシュ (/) を含めることはできません。

カスタムフィルター

Qt ヘルプ プロジェクト ファイルには、カスタム フィルターのオプションの定義が含まれています。カスタム フィルターにはフィルター プロパティのリストが含まれており、後でこれらのプロパティがすべて割り当てられているドキュメント セットのみを表示するために使用されます。そのため、QHelpEngine の現在のフィルターを「My Application 1.0」に設定すると、myapp と 1.0 がフィルター プロパティとして設定されているドキュメントのみが表示されます。

...
<customFilter name="My Application 1.0">
     <filterAttribute>myapp</filterAttribute>
     <filterAttribute>1.0</filterAttribute>
 </customFilter>
...

ヘルパー プロジェクト ファイルには、任意の数のカスタム フィルターを定義できます。同じプロジェクト ファイル内でフィルター プロパティを指定する必要がないことを知っておくことが重要です。これらのプロパティは、ヘルプ ファイルのフィルター セクションで定義できます。

フィルターセクション

フィルターセクションには実際のドキュメントが含まれています。Qt ヘルプ プロジェクト ファイルには、複数のフィルター セクションが含まれる場合があります。各フィルタリング セクションは、フィルタリング属性セクション、ディレクトリ、キーワード、ファイル リストの 4 つのセクションで構成されます。理論上、すべてのセクションはオプションですが、何も指定しないと空のドキュメント セットになります。

フィルター属性

各フィルター セクションには、ドキュメント フィルターを有効にするフィルター属性が割り当てられている必要があります。フィルター プロパティが定義されていない場合、ドキュメントはフィルター処理が行われていない場合にのみ表示されます。これは、QHelpEngine の現在のカスタム フィルターにフィルター プロパティが含まれていないことを意味します。

...
<filterSection>
    <filterAttribute>myapp</filterAttribute>
    <filterAttribute>1.0</filterAttribute>
    ...
</filterSection>
...

この場合、フィルター属性 myapp および 1.0 がフィルター セクションに割り当てられます。これは、現在のカスタム フィルターにフィルター属性として myapp または 1.0、またはその両方が含まれている場合にのみ、このセクションで指定されたすべてが表示されることを意味します。

目次

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

セクション タグはディレクトリ内の項目を表します。セクションは任意にネストできますが、ユーザーの観点からは 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::linksForIdentifier() 経由でのみアクセスできます。name と id は同時に指定できます。

ファイル

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

最後に、実際のドキュメント ファイルをリストする必要があります。ヘルプを表示するために必要なすべてのファイルが記載されていることを確認してください。つまり、スタイルシートまたは同様のファイルもリストする必要があります。これらのファイルは、Qt ヘルプ プロジェクト内のすべてのファイル参照と同様、ヘルプ プロジェクト ファイル自体に関連しています。この例が示すように、ワイルドカードを使用してファイル (ディレクトリではない) をパターンとして指定することもできます。リストされたすべてのファイルは圧縮され、Qt 圧縮ヘルプ ファイルに書き込まれます。したがって、最終的に、Qt ヘルプ ファイルには、コンテンツとインデックスだけでなく、すべてのドキュメント ファイルが含まれます。

**注意:** 参照ファイルは、ヘルプ プロジェクト ファイルと同じディレクトリ (またはサブディレクトリ) に存在する必要があります。絶対ファイル パスもサポートされていません。