Проект справки Qt

Проект справки Qt собирает все данные, необходимые для создания сжатого файла справки. Наряду с фактическими данными справки, такими как оглавление, ключевые слова индекса и документы справки, он содержит дополнительную информацию, такую как пространство имен для идентификации файла справки. Один проект справки соответствует одному набору документации, например, Справочная система Qt Assistant.

Формат файла проекта справки 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::linksForIdentifier(). name и id можно указать одновременно.

Файлы

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

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

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