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

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