Qt Help Projekt

Ein Qt Help Projekt sammelt alle Daten, die notwendig sind, um eine komprimierte Hilfedatei zu erzeugen. Neben den eigentlichen Hilfedaten, wie dem Inhaltsverzeichnis, den Index-Schlüsselwörtern und den Hilfedokumenten, enthält es einige zusätzliche Informationen wie einen Namespace, um die Hilfedatei zu identifizieren. Ein Hilfeprojekt steht für eine Dokumentationsmenge, zum Beispiel das qmake Manual.

Qt Help Projektdateiformat

Das Dateiformat ist XML-basiert. Zum besseren Verständnis des Formats werden wir das folgende Beispiel besprechen:

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

Namespace

Um QHelpEngine in die Lage zu versetzen, die richtige Dokumentation zu einem bestimmten Link zu finden, muss jede Dokumentationsmenge einen eindeutigen Bezeichner haben. Ein eindeutiger Bezeichner macht es auch möglich, dass die Hilfesammlung einen Dokumentations-Satz verfolgen kann, ohne sich auf den Dateinamen zu verlassen. Das Qt-Hilfesystem verwendet einen Namespace als Bezeichner, der durch die obligatorischen Namespace-Tags definiert ist. Im obigen Beispiel ist der Namespace "mycompany.com.myapplication.1.0".

Virtuelle Ordner

Ein Namespace für jede Dokumentationsgruppe bedeutet natürlich, dass die Dokumentationsgruppen voneinander getrennt sind. Aus der Sicht der Hilfemaschine ist dies von Vorteil. Aus der Sicht des Autors ist es jedoch oft wünschenswert, auf bestimmte Themen von einem Handbuch zum anderen zu verweisen, ohne absolute Links angeben zu müssen. Um dieses Problem zu lösen, hat das Hilfesystem das Konzept der virtuellen Ordner eingeführt.

Ein virtueller Ordner wird zum Stammverzeichnis aller Dateien, auf die in einer komprimierten Hilfedatei verwiesen wird. Wenn zwei Dokumentationsgruppen denselben virtuellen Ordner nutzen, können sie relative Pfade verwenden, wenn sie Hyperlinks definieren, die aufeinander verweisen. Wenn eine Datei in beiden Dokumentationsgruppen enthalten ist, hat diejenige aus der aktuellen Gruppe Vorrang vor der anderen.

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

Im obigen Beispiel wird doc als virtueller Ordner angegeben. Wenn ein anderes Handbuch denselben Ordner angibt, z. B. für ein kleines Hilfsprogramm My Application, genügt es, doc.html#section1 zu schreiben, um auf den ersten Abschnitt im Handbuch My Application zu verweisen.

Das Tag für den virtuellen Ordner ist obligatorisch und der Ordnername darf keine Schrägstriche (/) enthalten.

Abschnitt filtern

Ein Filterabschnitt enthält die eigentliche Dokumentation. Eine Qt-Hilfe-Projektdatei kann mehr als einen Filterabschnitt enthalten. Jeder Filterabschnitt besteht aus dem Inhaltsverzeichnis, den Schlüsselwörtern und der Dateiliste. Theoretisch sind alle Teile optional, aber nichts anzugeben, führt zu einer leeren Dokumentation.

Inhaltsverzeichnis

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

Ein Abschnitts-Tag steht für einen Eintrag im Inhaltsverzeichnis. Die Abschnitte können beliebig verschachtelt werden, aber aus Sicht des Benutzers sollten es nicht mehr als vier oder fünf Ebenen sein. Ein Abschnitt wird durch seinen Titel und seinen Verweis definiert. Die Referenz ist, wie alle Dateireferenzen in einem Qt-Hilfeprojekt, relativ zu der Hilfeprojektdatei selbst.

Schlüsselwörter

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

Der Abschnitt Schlüsselwörter listet alle Schlüsselwörter dieses Filterabschnitts auf. Ein Schlüsselwort besteht grundsätzlich aus einem Namen und einem Dateiverweis. Wenn das Attribut name verwendet wird, erscheint das dort angegebene Schlüsselwort im sichtbaren Index. Das heißt, es wird über die Klasse QHelpIndexModel zugänglich sein. Wenn id verwendet wird, erscheint das Schlüsselwort nicht im Index und ist nur über QHelpEngineCore::documentsForIdentifier() zugänglich. name und id können gleichzeitig angegeben werden.

Dateien

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

Schließlich müssen die eigentlichen Dokumentationsdateien aufgeführt werden. Achten Sie darauf, dass alle Dateien, die für die Anzeige der Hilfe notwendig sind, aufgeführt werden. Das heißt, Stylesheets oder ähnliche Dateien müssen ebenfalls aufgeführt werden. Die Dateien sind, wie alle Dateireferenzen in einem Qt-Hilfeprojekt, relativ zu der Hilfeprojektdatei selbst. Wie das Beispiel zeigt, können Dateien (aber nicht Verzeichnisse) auch als Muster mit Wildcards angegeben werden. Alle aufgeführten Dateien werden komprimiert und in die komprimierte Qt-Hilfedatei geschrieben. Am Ende enthält eine einzige Qt-Hilfedatei alle Dokumentationsdateien zusammen mit den Inhalten und Indizes.