Qt Help Projekt

Ein Qt Help-Projekt sammelt alle Daten, die zur Erstellung einer komprimierten Hilfedatei erforderlich sind. Neben den eigentlichen Hilfedaten wie dem Inhaltsverzeichnis, den Stichwörtern für den Index und den Hilfedokumenten enthält es einige zusätzliche Informationen wie einen Namensraum zur Identifizierung der Hilfedatei. Ein Help-Projekt steht für einen Dokumentationssatz, zum Beispiel das qmake-Handbuch.

Qt Help Projektdateiformat

Das Dateiformat basiert auf XML. Zum besseren Verständnis des Formats werden wir das folgende Beispiel erläutern:

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

Namensraum

Damit das „ QHelpEngine “ die richtige Dokumentation zu einem bestimmten Link abrufen kann, muss jeder Dokumentationssatz über eine eindeutige Kennung verfügen. Eine eindeutige Kennung ermöglicht es der Hilfe-Sammlung zudem, einen Dokumentationssatz nachzuverfolgen, ohne sich auf dessen Dateinamen verlassen zu müssen. Das Qt Help-System verwendet einen Namensraum als Kennung, der durch die obligatorischen Namensraum-Tags definiert wird. Im obigen Beispiel lautet der Namensraum „mycompany.com.myapplication.1.0“.

Virtuelle Ordner

Ein Namensraum für jeden Dokumentationssatz bedeutet natürlich, dass die Dokumentationssätze strikt voneinander getrennt sind. Aus Sicht der Hilfe-Engine ist dies vorteilhaft. Aus Sicht des Autors ist es jedoch oft wünschenswert, Querverweise auf bestimmte Themen von einem Handbuch zum anderen zu setzen, ohne absolute Links angeben zu müssen. Um dieses Problem zu lösen, wurde im 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 Dokumentationssätze denselben virtuellen Ordner nutzen, können sie relative Pfade verwenden, wenn sie Hyperlinks definieren, die aufeinander verweisen. Befindet sich eine Datei in beiden Dokumentationssätzen, hat die Datei aus dem aktuellen Satz Vorrang vor der anderen.

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

Im obigen Beispiel wird „doc“ als virtueller Ordner angegeben. Wenn ein anderes Handbuch denselben Ordner angibt, beispielsweise für ein kleines Hilfsprogramm namens „My Application“, reicht es aus, „doc.html#section1“ zu schreiben, um auf den ersten Abschnitt im Handbuch zu „My Application“ zu verweisen.

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

Filterabschnitt

Ein Filterabschnitt enthält die eigentliche Dokumentation. Eine Qt Help-Projektdatei kann mehr als einen Filterabschnitt enthalten. Jeder Filterabschnitt besteht aus dem Inhaltsverzeichnis, den Stichwörtern und der Dateiliste. Theoretisch sind alle Teile optional, doch wenn dort nichts angegeben wird, führt dies zu einem leeren Dokumentationssatz.

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 tief verschachtelt werden, aus Sicht des Benutzers sollten es jedoch nicht mehr als vier oder fünf Ebenen sein. Ein Abschnitt wird durch seinen Titel und seine Referenz definiert. Die Referenz ist, wie alle Dateireferenzen in einem Qt Help-Projekt, relativ zur Hilfe-Projektdatei 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 im Wesentlichen aus einem Namen und einer Dateireferenz. Wird das Attribut „name“ verwendet, erscheint das dort angegebene Schlüsselwort im sichtbaren Index. Das heißt, es ist über die Klasse „ QHelpIndexModel “ zugänglich. Wird „id“ verwendet, 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 aufgelistet werden. Stellen Sie sicher, dass alle zur Anzeige der Hilfe erforderlichen Dateien aufgeführt sind. Das heißt, auch Stylesheets oder ähnliche Dateien müssen aufgeführt werden. Die Dateien sind, wie alle Dateiverweise in einem Qt Help-Projekt, relativ zur Hilfe-Projektdatei selbst. Wie das Beispiel zeigt, können Dateien (jedoch keine Verzeichnisse) auch als Muster unter Verwendung von Platzhaltern angegeben werden. Alle aufgeführten Dateien werden komprimiert und in die komprimierte Qt Help-Datei geschrieben. Somit enthält letztendlich eine einzige Qt Help-Datei alle Dokumentationsdateien zusammen mit den Inhalten und Indizes.