QT Assistant, Не пойму, куда ткнуться. Ткните пожалуйста. Опции

[Shpiron]

Всем здравствуйте. Я в QT третий день, как бы это смешно не звучало.. Моя задача - научиться делать в ней доку. Есть набор html-файлов, хочу их отобразить с помощью QT Assistant'a...
Но как то сделать, не соображу совсем. Перечитала кучу материалов в нете. Прочитала пример про SimpleTextViewer. Но не поняла ничего
Не пойму, где что писать, где какие xml-ки формировать, куда что загонять для генерации.. как получить qch-файлы...
Подскажите что-нибудь.. Пожааалуйста...

[kibsoft]

Using Qt Assistant as a Custom Help Viewer и The Qt Help Framework почитайте в ассистенте.

Generating Qt Help

Building help files for the Qt help system assumes that the html documentation files already exist, i.e. the Qt help system does not offer the possibility to create html files like e.g. Doxygen.

Once the html documentents are in place, a Qt Help Project file has to be created. After specifying all relevant information in this file, it needs to be compiled by calling:

qhelpgenerator doc.qhp -o doc.qch
The file 'doc.qch' contains then all html files in compressed form along with the table of contents and index keywords. To test if the generated file is correct, open Qt Assistant and install the file via the Settings|Documentation page.

[alex977]

Перевод примера "Simple Text Viewer" (пока на сайте не появился).
Скопировать пример в другой каталог. Поменять на нужные файлы. Выполнить шаги, приведенные в описании примера.

Раскрывающийся текст

Пример "Simple Text Viewer" показывает, как использовать Qt Assistant в качестве настраиваемого просмотрщика помощи для вашего приложения.

Это делается в два этапа. Во-первых, создаётся документация и настраивается Qt Assistant; во-вторых, в приложение добавляется функциональность для запуска и управления Qt Assistant.

Приложение "Simple Text Viewer" позволяет пользователю выбрать и просмотреть существующие файлы.

Приложение предоставляет свою собственную пользовательскую документацию, которая доступна в меню Help в панели меню главного окна, или щелкнув по кнопке Help в диалоге поиска файла приложения.

Пример состоит из четырех классов:

* Assistant предоставляет функциональность для запуска Qt Assistant.
* MainWindow - главное окно приложения.
* FindFileDialog позволяет пользователю искать файлы используя совпадение с метасимволами (wildcard).
* TextEdit предоставляет браузер форматированного текста, который гарантирует, что изображения на которые есть ссылки в документах HTML, будут правильно выведены на экран.

Обратите внимание на то, что мы комментируем только те части реализации, которые относятся к главному вопросу, который заставляет Qt Assistant действовать как настраиваемый просмотрщик справки для нашего приложения Simple Text Viewer.

Создание документации и настройка Qt Assistant

Как создать реальную документацию в форме HTML-страниц - за рамками этого примера. Вообще, HTML-страницы могут быть написаны вручную или сгенерированы с помощью инструментов документирования таких как qdoc или Doxygen. Для целей данного примера мы притворились, что файлы HTML уже созданы. Поэтому единственной вещью, которая осталось сделать - сообщить Qt Assistant как структурировать и отображать справочную информацию.

Упорядочение документации для Qt Assistant

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

Чтобы упорядочить документацию и сделать её пригодной для Qt Assistant, мы создаём файл проекта помощи Qt (.qhp). Первой и наиболее важной частью файл проекта является объявление пространства имён. Пространство имён является уникальным и будет первой частью URL страницы в Qt Assistant. Кроме того, мы установили виртуальную папку, которая служит в качестве общей папка для наборов документации. Это означает, что два набора документации идентифицируемых двумя разными пространствами имён могут перекрёстно ссылаться на файлы HTML пока эти файлы находятся в одной большой виртуальной папке. Тем не менее, для этого примера, у нас есть только один набор документации, поэтому имя виртуальной папки и её функциональность не важны.

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>com.trolltech.examples.simpletextviewer</namespace>
<virtualFolder>doc</virtualFolder>

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

С другой стороны, так как мы имеем только один набор документации, нам не нужна функциональность фильтрования Qt Assistant и поэтому мы можем пропустить атрибуты фильтра.

Теперь мы создадим оглавление. Элемент в оглавлении определяется тегом section, который содержит атрибуты для элемента заголовка а также ссылку на фактическую страницу. Теги секций могут вкладываться друг в друга до бесконечности, но по практическим соображениям не рекомендуется вкладывать их глубже, чем на три или четыре уровня. Для нашего примера мы хотим использовать следующую структуру оглавления:

* "Simple Text Viewer"
o "Find File"
+ "File Dialog"
+ "Wildcard Matching"
+ "Browse"
o "Open File"

В файле проекта помощи структура представлена так:

<filterSection>
<toc>
<section title="Simple Text Viewer" ref="index.html">
<section title="Find File" ref="./findfile.html">
<section title="File Dialog" ref="./filedialog.html"></section>
<section title="Wildcard Matching" ref="./wildcardmatching.html"></section>
<section title="Browse" ref="./browse.html"></section>
</section>
<section title="Open File" ref="./openfile.html"></section>
</section>
</toc>

После определения оглавления, мы перечисляем все ключевые слова указателя:

<keywords>
<keyword name="Display" ref="./index.html"/>
<keyword name="Rich text" ref="./index.html"/>
<keyword name="Plain text" ref="./index.html"/>
<keyword name="Find" ref="./findfile.html"/>
<keyword name="File menu" ref="./findfile.html"/>
<keyword name="File name" ref="./filedialog.html"/>
<keyword name="File dialog" ref="./filedialog.html"/>
<keyword name="File globbing" ref="./wildcardmatching.html"/>
<keyword name="Wildcard matching" ref="./wildcardmatching.html"/>
<keyword name="Wildcard syntax" ref="./wildcardmatching.html"/>
<keyword name="Browse" ref="./browse.html"/>
<keyword name="Directory" ref="./browse.html"/>
<keyword name="Open" ref="./openfile.html"/>
<keyword name="Select" ref="./openfile.html"/>
</keywords>

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

<files>
<file>browse.html</file>
<file>filedialog.html</file>
<file>findfile.html</file>
<file>index.html</file>
<file>intro.html</file>
<file>openfile.html</file>
<file>wildcardmatching.html</file>
<file>images/browse.png</file>
<file>images/*.png</file>
</files>
</filterSection>
</QtHelpProject>

Теперь файл проекта помощи завершён. Если вы хотите увидеть получившуюся документацию в Qt Assistant, сгенерируйте из него сжатый файл помощи Qt и зарегистрируйте его с коллекцией справки Qt Assistant по умолчанию.

qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
assistant -register simpletextviewer.qch

Если вы запустите теперь Qt Assistant, то вы увидите рядом с документацией Qt документацию Simple Text Viewer. Это хорошо для целей отладки, но для окончательной версии мы хотим иметь в Qt Assistant только документацию Simple Text Viewer.
Настройка Qt Assistant

Самый лёгкий способ заставить Qt Assistant выводить на экран только документацию Simple Text Viewer - создать свой собственный файл коллекции помощи. Файл коллекции сохраняется в двоичном формате, подобном формату сжатого файла помощи, и генерируется из файл проекта коллекции помощи (*.qhcp). С помощью файла коллекции можно настроить внешний вид и даже некоторую функциональность предлагаемую Qt Assistant.

Сначала мы изменим заголовок окна и пиктограмму. Вместо показа "Qt Assistant" он будет показывать "Simple Text Viewer", так понятнее пользователю, что просмотрщик помощи фактически принадлежит нашему приложению.

<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
<title>Simple Text Viewer</title>
<applicationIcon>images/handbook.png</applicationIcon>
<cacheDirectory>Trolltech/SimpleTextViewer</cacheDirectory>

Тег cacheDirectory задаёт подкаталог в каталоге пользовательских данных (смотрите Файлы коллекции справки Qt), где сохраняется файл кэша для полнотекстового поиска или файл настроек.

После этого мы установим страницу, отображаемую Qt Assistant при самом первом запуске в новой конфигурации. URL состоит из пространства имён и виртуальной папки, определённой в файле проекта помощи Qt, следом - имя файла реальной страницы.

<startPage>qthelp://com.trolltech.examples.simpletextviewer/doc/index.html</startPage>

Потом мы меняем имя пункта меню "About" на "About Simple Text Viewer". Содержимое диалога About также изменяется задав файл, откуда брать текст о программе или пиктограмму.

<aboutMenuText>
<text>About Simple Text Viewer</text>
</aboutMenuText>
<aboutDialog>
<file>about.txt</file>
<icon>images/icon.png</icon>
</aboutDialog>

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

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

<enableDocumentationManager>false</enableDocumentationManager>
<enableAddressBar>false</enableAddressBar>
<enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>

Для нужд тестирования мы уже сгенерировали сжатый файл помощи и регистрируется вместе с коллекцией помощи Qt Assistant'а по умолчанию. Со следующими строками мы достигнем такого же результата. Единственным и важным отличием является то, что мы зарегистрировали сжатый файл помощи, не в коллекции по умолчанию, но в нашем собственном файле коллекции.

<docFiles>
<generate>
<file>
<input>simpletextviewer.qhp</input>
<output>simpletextviewer.qch</output>
</file>
</generate>
<register>
<file>simpletextviewer.qch</file>
</register>
</docFiles>
</QHelpCollectionProject>

В качестве последнего шага, мы генерируем двоичный файл коллекции из файла проекта коллекции помощи. Это делают запустив инструмент qcollectiongenerator.

qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc

Чтобы проверить все наши настройки сделанные в Qt Assistant, мы добавили имя файла коллекции в командную строку:

assistant -collectionFile simpletextviewer.qhc

Сообщение отредактировал alex977 - 13.6.2010, 23:01

[Litkevich Yuriy]

как получить qch-файлы

Это очень просто. Вот реальный пример файла проекта справки (qhp), для самого асиситента:

assistant.qhp

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
    <namespace>com.trolltech.assistant.460</namespace>
    <virtualFolder>qdoc</virtualFolder>
    <customFilter name="Qt Assistant Manual">
        <filterAttribute>qt</filterAttribute>
        <filterAttribute>tools</filterAttribute>
        <filterAttribute>assistant</filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute>qt</filterAttribute>
        <filterAttribute>tools</filterAttribute>
        <filterAttribute>assistant</filterAttribute>
        <filterAttribute>4.6.0</filterAttribute>
        <toc>
            <section ref="assistant-manual.html" title="Qt Assistant Manual">
                <section ref="examples.html" title="Examples">
                    <section ref="help-simpletextviewer.html" title="Simple Text Viewer Example"/>
                </section>
                <section ref="assistant-manual.html" title="Manual">
                    <section ref="assistant-manual.html" title="Qt Assistant Manual"/>
                    <section ref="assistant-details.html" title="Qt Assistant in More Detail"/>
                    <section ref="assistant-custom-help-viewer.html" title="Using Qt Assistant as a Custom Help Viewer"/>
                </section>
            </section>
        </toc>
        <keywords>
            <keyword name="Qt Assistant" id="Qt Assistant" ref="assistant-manual.html#qt-assistant"/>
            <keyword name="Qt Assistant Manual" id="Qt Assistant Manual" ref="assistant-manual.html"/>
            <keyword name="Qt Assistant in More Detail" id="Qt Assistant in More Detail" ref="assistant-details.html"/>
            <keyword name="Simple Text Viewer Example" id="Simple Text Viewer Example" ref="help-simpletextviewer.html"/>
            <keyword name="Using Qt Assistant as a Custom Help Viewer" id="Using Qt Assistant as a Custom Help Viewer" ref="assistant-custom-help-viewer.html"/>
        </keywords>
        <files>
            <file>help-simpletextviewer-main-cpp.html</file>
            <file>help-simpletextviewer-textedit-h.html</file>
            <file>help-simpletextviewer-assistant-cpp.html</file>
            <file>images/assistant-docwindow.png</file>
            <file>help-simpletextviewer-mainwindow-cpp.html</file>
            <file>help-simpletextviewer-mainwindow-h.html</file>
            <file>assistant-custom-help-viewer.html</file>
            <file>images/assistant-assistant.png</file>
            <file>images/assistant-search.png</file>
            <file>images/assistant-address-toolbar.png</file>
            <file>help-simpletextviewer-assistant-h.html</file>
            <file>images/assistant-preferences-filters.png</file>
            <file>images/simpletextviewer-mainwindow.png</file>
            <file>images/assistant-preferences-options.png</file>
            <file>help-simpletextviewer-findfiledialog-cpp.html</file>
            <file>help-simpletextviewer.html</file>
            <file>help-simpletextviewer-findfiledialog-h.html</file>
            <file>images/assistant-preferences-fonts.png</file>
            <file>examples.html</file>
            <file>images/assistant-toolbar.png</file>
            <file>images/assistant-dockwidgets.png</file>
            <file>images/simpletextviewer-findfiledialog.png</file>
            <file>images/assistant-preferences-documentation.png</file>
            <file>images/assistant-filter-toolbar.png</file>
            <file>assistant-details.html</file>
            <file>help-simpletextviewer-simpletextviewer-pro.html</file>
            <file>assistant-manual.html</file>
            <file>help-simpletextviewer-textedit-cpp.html</file>
            <file>images/simpletextviewer-example.png</file>
            <file>images/assistant-toolbar.png</file>
            <file>images/simpletextviewer-findfiledialog.png</file>
            <file>images/trolltech-logo.png</file>
            <file>images/assistant-search.png</file>
            <file>images/assistant-preferences-documentation.png</file>
            <file>classic.css</file>
            <file>images/assistant-filter-toolbar.png</file>
            <file>images/simpletextviewer-example.png</file>
            <file>images/assistant-assistant.png</file>
            <file>images/qt-logo.png</file>
            <file>images/assistant-address-toolbar.png</file>
            <file>images/simpletextviewer-mainwindow.png</file>
            <file>images/assistant-dockwidgets.png</file>
            <file>images/assistant-preferences-filters.png</file>
            <file>images/assistant-docwindow.png</file>
            <file>images/assistant-preferences-fonts.png</file>
            <file>images/assistant-preferences-options.png</file>
        </files>
    </filterSection>
</QtHelpProject>

в каталоге где лежит этот файл лежат и файлы указанные в нём, картинки лежат в подкаталоге images
Чтобы получить сжатые файлы справки нужно просто скомандовать:

qhelpgenerator.exe assistant.qhp -o assistant.qch

Про содержимое qhp:
namespace - должно быть уникальным, это начало адреса, например, для файла assistant-manual.html, в адресной строке асиситента будет выглядеть так:


toc - оглавление, то что будет в нём отображаться

keywords - предметный указатель (или просто указатель), то что будет в нём отображаться

files - список файлов, которые должны быть помещены в сжатый файл справки

-----
customFilter - создаёт новый фильтр, который можно выбрать в панели фильтра асиситента:


filterSection - секция описывающая содержимое фильтра. Здесь речь идёт о неком уже существующем фильтре и выбирается он комбинацией атрибутов.
Например, в assistant.qhp создан фильтр с именем "Qt Assistant Manual", а в своём файле вы можете просто перечислить в секции filterSection, его атрибуты. При этом не создавая нового фильтра. Тогда при выборе фильтра "Qt Assistant Manual" будет доступна документация по Асистенту и ваша.

Под доступностью понимается: наличие соответствующих пунктов в Оглавлении, Указателе и при полнотекстовом поиске.

[Shpiron]

Всем спасибо, начинаю что-то понимать потихоньку...
Вопроса два:
1. для того, чтобы...., нужно просто написать
qhelpgenerator.exe assistant.qhp -o assistant.qch

У меня это получается непросто.. Так как файлы помощи и генератор.exe лежат в абсол.тно разных местах.. Это нормально? То есть, чтоб это выполнить, мне нужно для каждого файла указать полный путь...

2. Сгенерить двоичный файл из файла коллекции .qhcp - это последний этап сборки помощи.
Что после этого должно выйти? Простите за неграмотность, но в итоге ведь должен выйти какой-то exe-шник, который я запускаю и открывается окно помощи.. нет?

[Litkevich Yuriy]

То есть, чтоб это выполнить, мне нужно для каждого файла указать полный путь...

конечно, но путь может быть и относительным. (относительно того каталога в котором выполняется команда)

ведь должен выйти какой-то exe-шник, который я запускаю и открывается окно помощи.. нет?

нет. Эти файлы нужно будет добавить в асистент. (см. справку)

Вот почитайка команды Qt RTT для добавления перевода документации к имеющейся:

Раскрывающийся текст

=== Руководство по установке документации Qt версии 4.5. ===
Переместите файлы *.qch в каталог %QTDIR%\doc\qch

==== Добавление документации в Qt Assistant ====
1) Запускаем Qt Assistant
2) Меню "Правка" -> "Настройки" -> вкладка "Документация"
3) Нажимаем кнопку "Добавить"
4) В появившемся диалоге выбираем эти qch-файлы, и нажимаем кнопку диалога "Открыть"
(в списке документации должны появится строчки c префиксом: ru.trolltech.* )
5) Нажимаем "Ок" и ждем завершения индексации.
(В боковой панели "Оглавление (Contents)" должны появится пункты с русским названием, типа "Руководство по ...")
6) Щелкаем правой кнопкой мышки по панели инструментов и включаем пенель фильтра.
7) Можете выбрать фильтр "Qt 4.5.2 - RU", тогда англоязычная документация скроется (и не будет учавствовать в поиске)

Замечание:
Чтобы быстро переключится с одного языка на другой, достаточно в строке адреса исправить префикс "ru" на "en" или наоборот.

[Shpiron]

Всем спасибо огромное, у меня даже что-то получилось..
Появился еще вопросик: когда меняется html-файл, что нужно сделать, чтобы исправленная версия отобразилась? Перерегистрировать? или может вообще ничего не нужно, я зря парюсь?

[Kagami]

Если какой-либо файл .html изменился, то надо пересоздать файл .qch.

Сообщение отредактировал Kagami - 14.6.2010, 22:45

[Shpiron]

У меня получилось отобразить желаемую структуру.. Слева отображается дерево, раскрываются списки, а вот справа ничего не отображается
вообще пусто... что я не так делаю?

[Litkevich Yuriy]

Shpiron, ты экспериментируешь прямо с асиситентом?