Qt Help Project

A Qt help project collects all data necessary to generate a compressed help file. Along with the actual help data, like the table of contents, index keywords and help documents, it contains some extra information like a namespace to identify the help file. One help project stands for one documentation, e.g. the Qt Assistant manual.

Qt Help Project File Format

The file format is XML based. For a better understanding of the format we'll discuss the following example:

 <?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>index.html</file>
             <file>doc.html</file>
         </files>
     </filterSection>
 </QtHelpProject>

Namespace

To enable the QHelpEngine to retrieve the proper documentation to a given link, every documentation set has to have a unique identifier. A unique identifier makes is also possible for the help collection to keep track of a documentation set without relying on its file name. The Qt help system uses a namespace as identifier which is defined by the mandatory namespace tags. In the example above, the namespace is "mycompany.com.myapplication.1_0".

Virtual Folders

Having a namespace for every documentation naturally means that the documentation sets are quite separated. From the help engines point of view this is beneficial, but from the documentors view it is often desirable to cross reference certain topic from one manual to another without having to specify absolute links. To solve this problem, the help system introduced the concept of virtual folders.

A virtual folder will become the root directory of all files referenced in a compressed help file. When two documentations share the same virtual folder, they can use relative paths when defining hyperlinks pointing to the other documentation. If a file is contained in both documentations or manuals, the one from the current manual has precedence over the other.

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

The above example specifies 'doc' as virtual folder. If another manual, e.g. for a small helper tool for 'My Application' specifies the same folder, it is sufficient to write 'doc.html#section1' to reference the first section in the 'My Application' manual.

The virtual folder tag is mandatory and the folder must not contain any '/'.

Custom Filters

Next in the Qt help project file are the optional definitions of custom filters. A custom filter contains a list of filter attributes which will be used later to display only the documentation which has all those attributes assigned to. So, when setting the current filter in the QHelpEngine to "My Application 1.0" only the documentation which has "myapp" and "1.0" set as filter attributes will be shown.

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

It is possible to define any number of custom filters in a help project file. Important to know is, that the filter attributes have not to be specified in the same project file; they can be defined in any other help file. The definition of a filter attributes takes place by specifying them in a filter section.

Best Of

Actualités les plus lues

Semaine

Mois

Année

Le Qt Developer Network au hasard

Applications mobiles modernes avec Qt et QML

Le Qt Developer Network est un réseau de développeurs Qt anglophone, où ils peuvent partager leur expérience sur le framework. Lire l'article.

Communauté

Ressources

Liens utiles

Contact

Vous souhaitez rejoindre la rédaction ou proposer un tutoriel, une traduction, une question... ? Postez dans le forum Contribuez ou contactez-nous par MP ou par email (voir en bas de page).

Qt dans le magazine

Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia.	Qt 4.4
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP !