Программа просмотра справки в Photon
helpviewer [-b цвет] [-f цвет] [-F начальная_страница] [-h высота[%]] [-l цвет] [-m] [-o] [-r topic.toc] [-S i|m|n] [-s сервер]
[-t каталог_тем] [-u домашняя_страница] [-w ширина[%]] [-x положение[%] [r]] [-y положение[%][r]] [url]
| Имя_сервера | Использование сервера |
|---|---|
| путь_к_узлу | путь_к_узлу/dev/photon |
| полный_путь | полный_путь |
| относительный_путь | /dev/относительный_путь |
ЗОСРВ «Нейтрино»
aarch64, arm, armv7, e2k, mips, ppc, x86
Приложение helpviewer отображает интерактивную справку с рядом навигационных средств, в т.ч. содержание, текстовый поиск, историю и закладки.
Приложение helpviewer поддерживает документы, написанные на языке разметки HTML. Однако helpviewer может осуществлять доступ только к локальным файлам и, следовательно, не может использоваться в качестве Интернет- браузера. Также поддерживаются форматы изображений GIF, JPEG и BMP.
Файл HTML, который требуется открыть, можно указать с помощью адресов URL или путей к темам:
$KPDA_TARGET/usr/help/product/neutrino/user_guide/examples.html
 | В адресах URL учитывается регистр. Эти URL-адреса ограничены локальными файлам справки; они не могут использоваться для доступа к Интернету. |
/Photon microGUI/User's Guide/Utilities/pdm
Для удобства в пути к теме регистр не учитывается и могут использоваться групповые символы * или ?, где * подставляется вместо строки, а ? – вместо символа. Для просмотра выбирается первая соответствующая тема.
Приложение helpviewer загружает содержание либо из единого тематического файла (с расширением .toc), либо из каталога. По умолчанию тематические файлы загружаются из каталога $QNX_TARGET/usr/help/product. Формат файлов тем описан в разделе "Создание тематических файлов" далее.
Создание файлов справки:
Приложение helpviewer поддерживает файлы справки, написанные на языке разметки HTML уровня 3.2 с рядом расширений. Файлы справки HTML можно создавать с помощью текстового редактора, специальных редакторов HTML или текстовых процессоров.
| В файлах справки не допускается использование функций версий HTML, более поздних, чем 3.2 (в противном случае возможен аварийный отказ helpviewer). |
Создание тематических файлов
Для организации интерактивной справки утилитой helpviewer используется таблица содержания. Содержание хранится отдельно от самих файлов HTML и не является частью определения HTML.
Тематические файлы создаются вручную на основе файлов интерактивной справки. Можно создать либо единый тематический файл, либо иерархию файлов тем в разных каталогах.
Тематические файлы должны иметь расширение .toc. Они представляют собой текстовые файлы, содержащие по одной теме на строку. Формат каждой строки темы следующий:
уровень|заголовок|файл HTML или TOC
где:
| В заголовках тем не допускается использовать символ вертикальной черты (|), поскольку этот символ применяется в файлах TOC в качестве разделителя. |
Обычно в тематическом файле содержатся записи, соответствующие каждому уровню заголовков HTML в файлах справки. Заголовок темы не обязательно должен быть идентичным заголовку в файле справки.
Каждая тема может ссылаться на файл HTML или на тематический файл. Если тема ссылается на файл HTML, при выборе темы отображается этот файл. Если тема ссылается на тематический файл, helpviewer считывает из этого файла подтемы и отображает их, однако HTML не отображается.
Если файл HTML находится в подкаталоге родительской темы, helpviewer выполняет сканирование каталога в поисках тематических файлов (только до 4 уровня тем). В таком случае указывать тематический файл явным образом не требуется.
Для повышения производительности утилиты helpviewer в каталогах, содержащих несколько файлов TOC, можно создать файлы toc_index. В файле toc_index просто перечислены файлы TOC из этого каталога; такой файл создается следующим образом:
ls *.toc > toc_index.
Предполагается, что файлы справки организованы в трехуровневую иерархию каталогов. Далее приведены уровни и типы файлов, которые должны содержаться на каждом из уровней.
Уровень 1
Каталог системы справки высшего уровня.
На этом уровне расположен каталог для каждого комплекта документов интерактивной справки и файл TOC высшего уровня для каждого комплекта.
В качестве примера можно привести каталог /usr/help/product, содержащий несколько комплектов документов, в том числе:
Уровень 2
Каталог уровня комплекта документов.
На этом уровне расположен каталог и файл TOC для каждого документа в комплекте документов и файл HTML высшего уровня для комплекта документов.
В качестве примера можно привести каталог $QNX_TARGET/usr/help/product/ide_en содержащий следующие файлы и каталоги:
Уровень 3
Каталог уровня документа.
На этом уровне расположен файл TOC и один или несколько тематических файлов HTML. Дополнительно могут присутствовать подкаталоги, позволяющие организовать файлы HTML по главам. В файле TOC содержатся записи уровня 3 и ниже для каждой темы в справочном документе.
В качестве примера можно привести каталог $QNX_TARGET/usr/help/product/phindows_en/user_guide, содержащий следующие файлы и каталоги:
В справке должна применяться такая же трехуровневая иерархия, даже если имеется всего один документ. Утилита helpviewer использует комбинацию уровня темы в файле TOC и уровня каталога файла TOC для организации вложенности тем на панели содержания.
Пример
Ниже приведен пример возможной вложенности файлов .toc. В каталоге $QNX_TARGET/usr/help/product расположен каталог справки Photon и файл TOC высшего уровня:
photon_2.0_en.toc photon_2.0_en/
Файл photon_2.0_en.toc содержит единственную строку:
1|Photon microGUI for QNX Neutrino|./photon_2.0_en/bookset.html
Каталог photon_2.0_en содержит файл TOC и по каталогу для каждого документа. Например, для документа "Programmer's Guide" ("Руководство разработчика") в этом каталоге содержатся следующие файлы и папки:
prog_guide.toc prog_guide/
Файл prog_guide.toc содержит единственную строку:
2|Programmer's Guide|./prog_guide/about.html
В каталоге prog_guide содержатся файлы HTML и файл book.toc, определяющий заголовки тем в файлах HTML:
3|About This Guide|about.html#ABOUTTHISGUIDE 4|Assumptions|#id3 4|Changes and corrections|#ChangesAndCorrections 3|Introduction|intro.html#id1 4|Photon Application Builder - PhAB|#PhABApplications 6|Get immediate results|#id3 ...
Часть URL, следующая за символом #, является закладкой, определенной в коде HTML.
| Если файлы .toc содержат символы в кодировке, отличной от ASCII, то для их правильного отображения на панели содержания их формат должен быть многобайтовым.
Редактор Photon ped позволяет вводить символы в кодировке UTF-8. Для получения подробной информации см. справочную страницу ped. |
Публикация тематических файлов
Таблицу содержания можно включить в таблицу содержания по умолчанию (вместе с требуемой интерактивной документацией), либо хранить ее отдельно и указать местоположение таблицы содержания при вызове утилиты helpviewer.
Добавление требуемой справки в справку по умолчанию
Для добавления требуемой справки в таблицу содержания по умолчанию необходимо создать тематический файл высшего уровня и добавить его в корневой каталог справки (/usr/help/product). Утилита helpviewer считывает все тематические файлы из корневого каталога и выполняет алфавитную сортировку тем.
Хранение справки в отдельном местоположении
Аналогично предыдущему случаю, в целях запуска утилиты helpviewer для собственной таблицы содержания и файлов справки следует изменить каталог файла справки по умолчанию с помощью опции -t, как показано ниже:
helpviewer -t /home/user/mytopics
Приложение helpviewer выводит только требуемую таблицу содержания и домашнюю страницу. Доступ к таблице содержания по умолчанию в данном случае не возможен.
Поиск
Для поиска по документации следует ввести ключевые слова в поле поиска ("Find") и нажать кнопку запуска ("Go!"). Разделителями считаются следующие символы:
,.:&()[]/\"#{};?-+=!\n пробел
Вводимые данные разбиваются на ключевые слова по вышеуказанным символам. Затем выполняется поиск по каждому ключевому слову в базе данных, и отбираются только результаты, содержащие все ключевые слова. Если флажок Match Whole Words ("Поиск по целым словам") не установлен, то по каждому ключевому слову выполняется поиск частичного совпадения. Например, среди результатов поиска по критерию "Toggle" выводится "PtToggle". Для поиска с учетом регистра ключевых слов следует установить флажок учета регистра Case sensitive.
Пробел эквивалентен оператору логического умножения (AND). Например, если в тексте документа выполняется поиск по критерию Photon coordinate space, находятся все документы, содержащие слова Photon, coordinate и space. Из этого не следует, что в найденных документах содержится полная строка Photon coordinate space.
| Эти переменные среды определяются интерпретаторами командной строки sh и ksh как переменные по умолчанию и указываются в файле /etc/profile.d/qnxsdk.sh. Если используется другой интерпретатор командной строки (например, esh или bsh) необходимо явным образом определить значения этих переменных, в противном случае вывод справки по умолчанию с помощью команды helpviewer окажется невозможным. |
Базовые подсистемы ЗОСРВ «Нейтрино», Photon
Предыдущий раздел: Приложения Photon