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>

命名空间¶

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

虚拟文件夹¶

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

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

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

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

虚拟文件夹标签是必需的，文件夹名称不能包含任何斜杠（/）。

目录¶

...
<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>
   <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，则关键字不会出现在索引中，只能通过documentsForIdentifier()访问。name和id可以同时指定。

文件¶

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

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

注意

引用的文件必须位于帮助项目文件所在的同一目录（或子目录）中。不支持绝对文件路径。

Qt 帮助项目¶

Qt 帮助项目文件格式¶

命名空间¶

虚拟文件夹¶

筛选部分¶

目录¶

关键词¶

文件¶