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 set, for example the Qt Assistant Manual.

Qt Help Project File Format

The file format is XML-based. For a better understanding of the format we will 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>*.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 also makes it 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 set naturally means that the documentation sets are quite separated. From the help engine's point of view, this is beneficial. However, from the writer's view it is often desirable to cross reference certain topics 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 documentation sets share the same virtual folder, they can use relative paths when defining hyperlinks pointing to each other. If a file is contained in both documentation sets, the one from the current set has precedence over the other.

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

The above example specifies doc as virtual folder. If another manual specifies the same folder, for example for a small helper tool My Application, 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 name must not contain any slashes (/).

Custom Filters

The Qt help project file contains optional definitions of custom filters. A custom filter contains a list of filter attributes which will be used later to display only the documentation set that has all those attributes assigned. 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>
...

You can define any number of custom filters in a help project file. It is important to know that you do not have to specify the filter attributes in the same project file. These attributes can be defined in any help file, in a filter section.

Filter Section

A filter section contains the actual documentation. One Qt help project file may contain more than one filter sections. Every filter section consists of four parts, the filter attributes section, the table of contents, the keywords and the files list. In theory all parts are optional but not specifying anything there will result in an empty documentation set.

Filter Attributes

Every filter section should have filter attributes assigned to it, to enable documentation filtering. If no filter attribute is defined, the documentation will only be shown if no filtering occurs, meaning the current custom filter in the QHelpEngine does not contain any filter attributes.

...
<filterSection>
    <filterAttribute>myapp</filterAttribute>
    <filterAttribute>1.0</filterAttribute>
...

In this case, the filter attributes myapp and 1.0 are assigned to the filter section. This means that all contents specified in this section will only be shown if the current custom filter has myapp or 1.0, or both, as filter attributes.

Table of Contents

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

One section tag represents one item in the table of contents. The sections can be nested to any degree, but from a user's perspective it should not be more than four or five levels. A section is defined by its title and reference. The reference, like all file references in a Qt help project, are relative to the help project file itself.

Note: The referenced files must be in the same directory as the help project file (or in a subdirectory). An absolute file path is not supported either.

Keywords

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

The keyword section lists all keywords of this filter section. A keyword consists basically of a name and a file reference. If the attribute name is used, the keyword specified there will appear in the visible index. That is, it will be accessible through the QHelpIndexModel class. If id is used, the keyword does not appear in the index and is only accessible via QHelpEngineCore::linksForIdentifier(). name and id can be specified at the same time.

Files

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

Finally, the actual documentation files have to be listed. Make sure that all files necessary to display the help are mentioned. That is, stylesheets or similar files need to be listed as well. The files, like all file references in a Qt help project, are relative to the help project file itself. As the example shows, files (but not directories) can also be specified as patterns using wildcards. All listed files will be compressed and written to the Qt compressed help file. So, in the end, one single Qt help file contains all documentation files along with the contents and indices.

Note: The referenced files must be inside the same directory as the help project file (or in a subdirectory). An absolute file path is not supported either.