Проект справки Qt (Qt Help Project)
Проект справки Qt объединяет все данные необходимые для создания сжатых файлов справки. Вместе с реальными данными справки, такими как оглавление, индекс ключевых слов и справочные документы, он содержит некоторую дополнительную информацию такую как пространства имен, чтобы идентифицировать файл справки. Один проект справки определяет одну документацию, например, руководство по Qt Assistant.
Формат проекта справки Qt
Формат файла основан на XML. Для лучшего понимания формата мы обсудим следующий пример:
<QtHelpProject version="1.0">
<namespace>mycompany.com.myapplication.1.0</namespace>
<virtualFolder>doc</virtualFolder>
<customFilter name="Моё приложение 1.0">
<filterAttribute>myapp</filterAttribute>
<filterAttribute>1.0</filterAttribute>
</customFilter>
<filterSection>
<filterAttribute>myapp</filterAttribute>
<filterAttribute>1.0</filterAttribute>
<toc>
<section title="Руководство по моему приложению" ref="index.html">
<section title="Глава 1" ref="doc.html#chapter1"/>
<section title="Глава 2" ref="doc.html#chapter2"/>
<section title="Глава 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".
Виртуальные каталоги (Virtual Folders)
Наличие пространства имен для каждой документации, естественно означает, что наборы документации совершенно независимы. С точки зрения движка справки это благоприятно, но с точки зрения документатора часто желательно, чтобы были перекрестные ссылки определенной темы из одного руководства в другое, без необходимости задания абсолютных ссылок. Чтобы решить эту проблему, справочная система вводит концепцию виртуальных каталогов.
Виртуальный каталог становится корневым каталогом всех файлов, указанных в сжатом файле справки. Когда две документации разделяют между собой один и тот же виртуальный каталог, они могут использовать относительные пути, определяя гиперссылки, указывающие на другую документацию. Если файл содержится в обеих документациях или руководствах, файл из текущего руководства имеет приоритет над другим.
...
<virtualFolder>doc</virtualFolder>
...
Пример выше устанавливает 'doc' как виртуальный каталог. Если другое руководство, например, для маленького вспомогательного инструмента к 'Моему приложению' указывает тот же каталог, достаточно написать 'doc.html#section1', чтобы сослаться на первый раздел в руководстве 'Моё приложение'.
Тег виртуального каталога является обязательным и каталог не должен содержать символы '/'.
Пользовательские фильтры
Следующее, в файле проекта Qt - это необязательное определение пользовательских фильтров. Пользовательский фильтр содержит список свойств фильтра, которые будут использованы позднее, чтобы отобразить только ту документацию, которая имеет все эти свойства. Таким образом, при установке текущего фильтра в QHelpEngine в значение "Моё приложение 1.0" будет отображена только та документация, которая имеет в качестве свойств фильтра "MyApp" и "1.0".
...
<customFilter name="Моё приложение 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="Руководство по моему приложению" ref="index.html">
<section title="Глава 1" ref="doc.html#chapter1"/>
<section title="Глава 2" ref="doc.html#chapter2"/>
<section title="Глава 3" ref="doc.html#chapter3"/>
</section>
</toc>
...
Один тег раздела (section) представляет одну запись в оглавлении. Разделы могут быть вложены в любой степени, но, исходя из удобств пользователей, они не должны иметь более четырёх-пяти уровней. Раздел определяется его заголовком и ссылкой. Ссылки, как и все ссылки на файлы, в проекте справки 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' используется, ключевое слово не появляется в предметном указателе и доступно только через функцию linksForIdentifier() QHelpEngineCore. Атрибуты 'name' и 'id' могут быть определены одновременно.
Файлы
...
<files>
<file>classic.css</file>
<file>*.html</file>
</files>
...
В конце, должны быть перечислены реальные файлы документации. Убедитесь, что указаны все файлы, необходимые для отображения справки, т.е. таблицы стилей или подобные файлы необходимо указать здесь же. Файлы, как все ссылки на файлы в проекте справки Qt, относятся к самому файлу проекта справки. Как показано в примерах, файлы (но не каталоги) можно также задать как шаблоны используя специальные символы. Все перечисленные файлы будут сжаты и записаны в сжатый файл справки Qt (Qt compressed help file). Таким образом, в конце, один единственный файл справки Qt содержит все файлы документации вместе с содержанием и предметным указателем. Замечание: Ссылочные файлы должны быть в том же каталоге (или внутри подкаталога) что и файл проекта справки. Абсолютный путь к файлу также не поддерживается.
Авторские права © 2010 Nokia Corporation и/или её дочерние компании |
Торговые марки |
Qt 4.6.4 |
|