Проект справки 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 содержит необязательные определения пользовательских фильтров. Пользовательский фильтр содержит список атрибутов фильтра, которые будут использоваться позднее для отображения только набора документации, которому назначены все эти атрибуты. Таким образом, при установке текущего фильтра в QHelpEngine на My Application 1.0 будет показана только документация, для которой атрибуты фильтра установлены как myapp и 1.0.

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

Вы можете определить любое количество пользовательских фильтров в файле проекта справки. Важно знать, что вам не нужно указывать атрибуты фильтра в одном и том же файле проекта. Эти атрибуты могут быть определены в любом файле справки, в разделе фильтра.

Раздел фильтра

Раздел фильтра содержит фактическую документацию. Один файл проекта справки Qt может содержать более одного раздела фильтра. Каждый раздел фильтра состоит из четырёх частей: раздела атрибутов фильтра, оглавления, ключевых слов и списка файлов. Теоретически все части являются необязательными, но отсутствие чего-либо приведёт к пустому набору документации.

Атрибуты фильтра

Каждый раздел фильтра должен иметь назначенные к нему атрибуты фильтра, чтобы включить фильтрацию документации. Если атрибут фильтра не определён, документация будет показана только если фильтрация не выполняется, то есть текущий пользовательский фильтр в QHelpEngine не содержит атрибутов фильтра.

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

В этом случае атрибуты фильтра myapp и 1.0 назначены разделу фильтра. Это означает, что всё содержимое, указанное в этом разделе, будет показано только в том случае, если текущий пользовательский фильтр имеет myapp или 1.0, или оба, в качестве атрибутов фильтра.

Оглавление

...
<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 содержит все файлы документации вместе с содержимым и индексами.

Примечание: Ссылающиеся файлы должны находиться в той же директории, что и файл проекта справки (или в подкаталоге). Абсолютный путь к файлу также не поддерживается.