Qt Help Projet

Un projet d'aide Qt Help rassemble toutes les données nécessaires pour générer un fichier d'aide compressé. En plus des données d'aide proprement dites, comme 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 pour identifier le fichier d'aide. Un projet d'aide correspond à un ensemble de documentation, par exemple le manuel qmake.

Qt Help Format du fichier de projet

Le format de fichier est basé sur XML. Pour une meilleure compréhension du 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 à QHelpEngine de retrouver la documentation appropriée pour un lien donné, chaque ensemble de documentation doit avoir un identifiant unique. Un identifiant unique permet également à la collection d'aide de garder la trace d'un ensemble de documentation sans se fier à son nom de fichier. Le système d'aide 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 d'avoir un espace de noms pour chaque ensemble de documentation signifie naturellement que les ensembles de documentation sont bien séparés. Du point de vue du moteur d'aide, c'est un avantage. Cependant, du point de vue du rédacteur, il est souvent souhaitable de faire référence à certains sujets d'un manuel à l'autre sans avoir à spécifier des 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 lorsqu'ils définissent des hyperliens pointant l'un vers l'autre. Si un fichier est contenu dans les deux ensembles de documentation, celui 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 Mon application, il suffit d'écrire doc.html#section1 pour faire référence à la première section du manuel Mon application.

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

Section sur les filtres

Une section filtre contient la documentation proprement dite. Un fichier de projet d'aide Qt Help peut contenir plus d'une section filtre. Chaque section filtre se compose de la table des matières, des mots-clés et de la liste des fichiers. En théorie, toutes les parties sont facultatives, mais ne rien spécifier dans ces sections aboutira à une 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, elles ne devraient pas dépasser 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 d'aide Qt Help, est relative au fichier du projet d'aide 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 des mots-clés énumère 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 le nom de l' attribut est utilisé, le mot-clé spécifié apparaîtra dans l'index visible. En d'autres termes, il sera accessible via la classe QHelpIndexModel. Si id est utilisé, le mot-clé n'apparaît pas dans l'index et n'est accessible que via QHelpEngineCore::documentsForIdentifier(). name et id peuvent être spécifiés en même temps.

Fichiers

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

Enfin, les fichiers de documentation proprement dits doivent être énumérés. Veillez à ce que tous les fichiers nécessaires à l'affichage de l'aide soient mentionnés. En d'autres termes, les feuilles de style et autres fichiers similaires doivent également être listés. Les fichiers, comme toutes les références de fichiers dans un projet d'aide Qt Help, sont relatifs au fichier du projet d'aide lui-même. Comme le montre l'exemple, les fichiers (mais pas les répertoires) peuvent également être spécifiés en tant que motifs à l'aide de caractères génériques. Tous les fichiers listés seront compressés et écrits dans le fichier d'aide compressé de Qt Help. Ainsi, au final, un seul fichier d'aide Qt Help contient tous les fichiers de documentation avec le contenu et les index.