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

每个部分标签代表目录中的一个项。部分可以嵌套到任何程度，但从用户的角度来看，不应超过四到五个级别。部分由其标题和引用定义。引用，就像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帮助项目文件格式#

命名空间#

虚拟文件夹#

过滤器部分#

目录#

关键词#

文件#