Qt 帮助项目

Qt帮助项目收集生成压缩帮助文件所需的所有数据。除了诸如目录，索引关键字和帮助文档之类的实际帮助数据外，它还包含一些其他信息，例如用于标识帮助文件的名称空间。一个帮助项目代表一个文档集。

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>

Namespace

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

Virtual Folders

为每个文档集设置一个命名空间，自然意味着文档集是相对分离的。从帮助引擎的角度来看，这是有益的。然而，从编写者的角度来看，通常希望在不指定绝对链接的情况下，将某些主题从一本手册交叉引用到另一本手册。为了解决这个问题，帮助系统引入了虚拟文件夹的概念。

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

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

上面的例子指定了doc作为虚拟文件夹。如果另一本手册指定了相同的文件夹，例如一个小的辅助工具My Application，那么编写doc.html#section1以引用My Application中的第一节就足够了。

虚拟文件夹标签是强制性的，文件夹名称不得包含任何斜线（/）。

Custom Filters

Qt帮助项目文件包含自定义筛选器的可选定义。自定义筛选器包含筛选器属性列表，稍后将使用该列表仅显示已分配所有这些属性的文档集。因此，当将QHelpEngine中的当前筛选器设置为“My Application 1.0”时，只会显示将myapp和1.0设置为筛选器属性的文档。

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

你可以在帮助项目文件中定义任意数量的自定义筛选器。重要的是要知道，你不必在同一个项目文件中指定过滤器属性。这些属性可以在任何帮助文件的筛选器部分中定义。

Filter Section

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

Filter Attributes

每个过滤器部分都应该分配过滤器属性，以启用文档过滤。如果未定义筛选器属性，则只有在未进行筛选时才会显示文档，这意味着QHelpEngine中的当前自定义筛选器不包含任何筛选器属性。

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

在这种情况下，过滤器属性myapp和1.0被指定给过滤器部分。这意味着，只有在当前自定义筛选器具有myapp或1.0或两者都作为筛选器属性时，才会显示本节中指定的所有内容。

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

一个section标记表示目录中的一个项目。这些部分可以任意嵌套，但从用户的角度来看，它不应该超过四到五个级别。章节由其标题和参考文献定义。与Qt帮助项目中的所有文件引用一样，该引用是相对于帮助项目文件本身的。

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

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

关键字部分列出了这个过滤器部分的所有关键字。一个关键字基本上由一个名称和一个文件引用组成。如果使用属性name，则在那里指定的关键字将出现在可见索引中。也就是说，可以通过QHelpIndexModel类访问它。如果使用属性id，关键字不会出现在索引中，并且只能通过QHelpEngineCore::linksForIdentifier()进行访问。name和id可以同时指定。

Files

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

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

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