Qt帮助项目

Qt帮助项目收集生成压缩帮助文件所需的所有数据。除了实际的帮助数据（如目录、索引关键字和帮助文档）外，还包含一些额外的信息，如用于标识帮助文件的命名空间。一个帮助项目代表一个文档集，例如qmake手册。

Qt帮助项目文件格式

该文件格式基于XML。为了更好地理解格式，我们将讨论以下示例

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

命名空间

为了使QHelpEngine能够检索到给定链接的正确文档，每个文档集都必须有一个唯一的标识符。唯一标识符还使得帮助集合能够跟踪文档集而无需依赖于其文件名。Qt帮助系统使用命名空间作为标识符，该标识符由必须的命名空间标签定义。在上例中，命名空间是"mycompany.com.myapplication.1.0"。

虚拟文件夹

为每个文档集拥有一个命名空间自然意味着文档集相当分散。从帮助引擎的角度来看，这是有益的。然而，从编写者的角度来看，常常需要从一个手册引用到另一个手册中的某些主题，而无需指定绝对链接。为了解决这个问题，帮助系统引入了虚拟文件夹的概念。

虚拟文件夹将成为压缩帮助文件中所有引用文件的根目录。当两个文档集使用相同的虚拟文件夹时，它们可以在定义指向对方的超链接时使用相对路径。如果一个文件包含在两个文档集中，则当前集的文件具有优先级。

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

上述示例指定doc为虚拟文件夹。如果另一本手册指定相同的文件夹，例如为一个小型辅助工具My Application，则只需编写doc.html#section1来引用My Application手册中的第一个部分。

虚拟文件夹标签是必需的，且文件夹名称不得包含任何斜杠(/)。

筛选部分包含实际文档。Qt帮助项目文件可能包含多个筛选部分。每个筛选部分由目录、关键字和文件列表组成。从理论上讲，所有部分都是可选的，但不指定任何内容将导致文档集为空。

关键词

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

关键词部分列出了此过滤部分的全部关键词。一个关键词基本上由一个名称和一个文件引用组成。如果使用属性name，则该处指定的关键词将出现在可见索引中。也就是说，它可以通过QHelpIndexModel类来访问。如果使用id，则关键词不会出现在索引中，只能通过QHelpEngineCore::documentsForIdentifier()访问。name和id可以同时指定。

文件

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

最后，必须列出实际的文档文件。确保提及显示帮助所需的所有文件。也就是说，需要列出样式表或类似文件。这些文件，就像Qt帮助项目中的所有文件引用一样，相对于帮助项目文件本身是相对的。如示例所示，可以使用通配符指定文件（但不能指定目录）作为模式。所有列出的文件都将被压缩并写入Qt压缩帮助文件。因此，最终，单一的Qt帮助文件包含了所有文档文件以及内容索引。

注意：所引用的文件必须位于与帮助项目文件相同的目录内（或子目录下）。也不支持绝对文件路径。