Проект справки 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 может содержать более одного раздела фильтра. Каждый раздел фильтра состоит из оглавления, ключевых слов и списка файлов. Теоретически все части являются необязательными, но отсутствие чего-либо приведёт к пустому набору документации.

Оглавление

...
<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, ключевое слово не отображается в индексе и доступно только через QHelpEngineCore::documentsForIdentifier(). name и id могут быть указаны одновременно.

Файлы

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

Наконец, необходимо указать фактические файлы документации. Убедитесь, что упомянуты все файлы, необходимые для отображения справки. То есть, необходимо указать также таблицы стилей или подобные файлы. Файлы, как и все ссылки на файлы в проекте справки Qt, относительны к самому файлу проекта справки. Как показывает пример, файлы (но не каталоги) также могут быть указаны как шаблоны с использованием подстановочных знаков. Все перечисленные файлы будут сжаты и записаны в сжатый файл справки Qt. Таким образом, один единственный файл справки Qt содержит все файлы документации вместе с оглавлением и индексами.