Qt Help Projet

Un projet Qt Help rassemble toutes les données nécessaires à la génération d’un fichier d’aide compressé. Outre les données d’aide proprement dites, telles que la table des matières, les mots-clés de l’index et les documents d’aide, il contient des informations supplémentaires, comme un espace de noms permettant d’identifier le fichier d’aide. Un projet Qt Help correspond à un ensemble de documentation, par exemple le manuel de qmake.

Qt Help Format de fichier du projet

Le format de fichier est basé sur XML. Pour mieux comprendre ce format, nous allons examiner l'exemple suivant :

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

Espace de noms

Pour permettre à l'QHelpEngine de récupérer la documentation appropriée correspondant à un lien donné, chaque ensemble de documentation doit disposer d'un identifiant unique. Un identifiant unique permet également à la collection d'aide de suivre un ensemble de documentation sans dépendre de son nom de fichier. Le système Qt Help utilise un espace de noms comme identifiant, défini par les balises d’espace de noms obligatoires. Dans l’exemple ci-dessus, l’espace de noms est « mycompany.com.myapplication.1.0 ».

Dossiers virtuels

Le fait de disposer d’un espace de noms pour chaque ensemble de documentation implique naturellement que ces ensembles sont bien séparés. Du point de vue du moteur d’aide, cela est avantageux. Cependant, du point de vue de l’auteur, il est souvent souhaitable de créer des références croisées entre certaines rubriques d’un manuel à l’autre sans avoir à spécifier de liens absolus. Pour résoudre ce problème, le système d’aide a introduit le concept de dossiers virtuels.

Un dossier virtuel devient le répertoire racine de tous les fichiers référencés dans un fichier d’aide compressé. Lorsque deux ensembles de documentation partagent le même dossier virtuel, ils peuvent utiliser des chemins relatifs pour définir des liens hypertextes pointant l’un vers l’autre. Si un fichier figure dans les deux ensembles de documentation, celui issu de l’ensemble actuel a la priorité sur l’autre.

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

L'exemple ci-dessus spécifie « doc » comme dossier virtuel. Si un autre manuel spécifie le même dossier, par exemple pour un petit outil d'aide « My Application », il suffit d'écrire « doc.html#section1 » pour faire référence à la première section du manuel « My Application ».

La balise de dossier virtuel est obligatoire et le nom du dossier ne doit contenir aucune barre oblique (/).

Section « Filtre »

Une section de filtre contient la documentation proprement dite. Un fichier de projet de Qt Help peut contenir plusieurs sections de filtre. Chaque section de filtre se compose de la table des matières, des mots-clés et de la liste des fichiers. En théorie, toutes ces parties sont facultatives, mais si vous ne spécifiez rien, vous obtiendrez un ensemble de documentation vide.

Table des matières

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

Une balise de section représente un élément de la table des matières. Les sections peuvent être imbriquées à volonté, mais du point de vue de l'utilisateur, il ne devrait pas y avoir plus de quatre ou cinq niveaux. Une section est définie par son titre et sa référence. La référence, comme toutes les références de fichiers dans un projet Qt Help, est relative au fichier du projet Qt Help lui-même.

Mots-clés

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

La section « mots-clés » répertorie tous les mots-clés de cette section de filtre. Un mot-clé se compose essentiellement d’un nom et d’une référence de fichier. Si l’attribut « name » est utilisé, le mot-clé qui y est spécifié apparaîtra dans l’index visible. Autrement dit, il sera accessible via la classe ` QHelpIndexModel `. Si l’attribut « id » est utilisé, le mot-clé n’apparaîtra pas dans l’index et ne sera accessible que via ` QHelpEngineCore::documentsForIdentifier()`. Les attributs « name » et « id » peuvent être spécifiés simultanément.

Fichiers

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

Enfin, les fichiers de documentation proprement dits doivent être répertoriés. Assurez-vous que tous les fichiers nécessaires à l’affichage de l’aide sont mentionnés. Autrement dit, les feuilles de style ou fichiers similaires doivent également être répertoriés. Les fichiers, comme toutes les références de fichiers dans un projet de Qt Help, sont relatifs au fichier du projet de Qt Help lui-même. Comme le montre l'exemple, les fichiers (mais pas les répertoires) peuvent également être spécifiés sous forme de modèles à l'aide de caractères génériques. Tous les fichiers répertoriés seront compressés et enregistrés dans le fichier d'aide compressé Qt. Ainsi, au final, un seul fichier d'aide Qt contient tous les fichiers de documentation ainsi que le sommaire et les index.