`helpviewer`

Программа просмотра справки 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]

Поддерживаемые платформы:

Neutrino

Опции:

-b цвет

Установить цвет фона в соответствии с указанным шестнадцатеричным кодом RGB.

-f цвет

Установить цвет переднего плана (текста) в соответствии с указанным шестнадцатеричным кодом RGB.

-F начальная_страница

Принудительно отобразить страницу, указанную в параметре начальная_страница при запуске. Эта страница должна находиться в корне тем.

-h высота[%]

Высота окна, в пикселях или в процентах по отношению к высоте экрана (если введен символ %).

-l цвет

Установить цвет ссылок в соответствии с указанным шестнадцатеричным кодом RGB.

-m

Включить кэширование (ускорение поиска за счет использования дополнительного объема памяти).

-o

Сохранять порядок тем в соответствии с файлом TOC (по умолчанию первые два уровня тем сортируются).

-r topic.toc

Отобразить только указанные темы из корня тем. Допускается указывать несколько опций -r.

-Si|m|n

Начальное состояние главного окна (свернуто, развернуто на весь экран, нормальный вид).

-s имя_сервера

Имя сервера Photon:

Значение имя_сервера	Использование сервера
путь_к_узлу	путь_к_узлу`/dev/photon`
полный_путь	полный_путь
относительный_путь	`/dev/`относительный_путь

-t каталог_тем

Отобразить файл справки, на который ссылается каталог тем.

-u домашняя_страница

Определить домашнюю страницу. Эта страница отображается утилитой helpviewer при нажатии на кнопку Home или при выборе пункта меню File-->Home.

-w ширина[%]

Ширина окна, в пикселях или в процентах от ширины экрана (если введен символ %).

-x положение[%][r]

Координата x верхнего левого угла окна, в пикселях или в процентах от ширины экрана (если введен символ %). Если указан модификатор r, то координата определяется относительно текущей консоли.

-y положение[%][r]

Координата y верхнего левого угла окна, в пикселях или в процентах от высоты экрана (если введен символ %). Если указан модификатор r, то координата определяется относительно текущей консоли.

url

Отобразить файл справки, на который указывает заданный адрес URL.

Описание:

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

Приложение helpviewer поддерживает документы, написанные на языке разметки HTML. Однако helpviewer может осуществлять доступ только к локальным файлам и, следовательно, не может использоваться в качестве Интернет- браузера. Также поддерживаются форматы изображений GIF, JPEG и BMP.

Файл HTML, который требуется открыть, можно указать с помощью адресов URL или путей к темам:

Адрес URL указывает путь файловой системы, где расположен текст справки в локальной сети. Пример адреса URL:

$QNX_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).

Поддерживаемые элементы

В следующей таблице приведен список элементов HTML и атрибутов, поддерживаемых приложением helpviewer:

Элемент	Теги	Атрибуты
Комментарий	`<!-- comment -->`
Документ	`<html>`...`</html>`
Заголовок страницы	`<head>`...`</head>`
Название страницы	`<title>`...`</title>`
Ссылка	`<link>`	`href=`url, `rel=`строка
Тело	`<body>`...`</body>`	`id=`строка, `bgcolor=`шестнадцатеричный_код, `link=`шестнадцатеричный_код, `text=`шестнадцатеричный_код
Заголовок 1	`<h1>`...`</h1>`	`id=`строка, `align=left`\|`center`\|`right`
Заголовок 2	`<h2>`...`</h2>`	`id=`строка, `align=left`\|`center`\|`right`
Заголовок 3	`<h3>`...`</h3>`	`id=`строка, `align=left`\|`center`\|`right`
Заголовок 4	`<h4>`...`</h4>`	`id=`строка, `align=left`\|`center`\|`right`
Заголовок 5	`<h5>`...`</h5>`	`id=`строка, `align=left`\|`center`\|`right`
Заголовок 6	`<h6>`...`</h6>`	`id=`строка, `align=left`\|`center`\|`right`
Горизонтальная черта	`<hr>`
Абзац	`<p>`...[`</p>`]	`id=`строка
Разрыв строки	`<br>`	`id=`строка
Изображение	`<img>`	`src=`url, `align=top`\|`middle`\|`bottom`, `alt=`строка, `id=`строка
Закладка	`<a>`...`</a>`	`href=`url, `name=`строка, `id=`строка
Предварительно отформатированный текст	`<pre>`...`</pre>`	`id=`строка
Блок цитирования	`<blockquote>`...`</blockquote>`	`id=`строка
Адрес	`<address>`...`</address>`	`id=`строка
Примечание	`<note>`...`</note>`	`src=`url, `id=`строка
Список определений	`<dl>`...`</dl>`	`compact`, `id=`строка
Термин	`<dt>...[</dt>]`	`id=`строка
Описание	`<dd>`...[`</dd>`]	`id=`строка
Нумерованный список	`<ol>`...`</ol>`	`id=`строка
Маркированный список	`<ul>`...`</ul>`	`id=`строка
Элемент списка	`<li>`...[`</li>`]	`id=`строка
Выделение	`<em>`...`</em>`
Усиленное выделение	`<strong>`...`</strong>`
Код	`<code>`...`</code>`
Пример	`<samp>`...`</samp>`
Набор с клавиатуры	`<kbd>`...`</kbd>`
Переменная	`<var>`...`</var>`
Определение	`<dfn>`...`</dfn>`
Цитата	`<cite>`...`</cite>`
Телетайп	`<tt>`...`</tt>`
Полужирный	`<b>`...`</b>`
Курсив	`<i>`...`</i>`
Подчеркивание	`<u>`...`</u>`
Таблица	`<table>`...`</table>`	`border`, `border=0`, `align=left`\|`center`\|`right`, `id=`строка
Заголовок таблицы	`<th>`...[`</th>`]	`align=left`\|`center`\|`right`, `id=`строка
Табличные данные	`<td>`...[`</td>`]	`align=left`\|`center`\|`right`, `id=`строка
Строка таблицы	`<tr>`...[`</tr>`]	`id=`строка

Поддерживаемые сущности

В Helpviewer также поддерживаются стандартные сущности (entity) HTML1/ISO для символов, а также следующие сущности:

Сущность	Значение	Визуализация
` `	Неразрывный пробел	Пробел
`&emsp;`	Максимальный пробел	Пробел
`&ensp;`	Нормальный пробел	Пробел
`—`	Длинное тире	Тире (`–`)
`–`	Короткое тире	Тире (`–`)
`“`	Открывающая двойная кавычка	Двойная кавычка (“)
`”`	Закрывающая двойная кавычка	Двойная кавычка (”)
`‘`	Открывающая одинарная кавычка	‘
`’`	Закрывающая одинарная кавычка	’
`™`	Символ торговой марки	TM

Создание тематических файлов

Для организации интерактивной справки утилитой helpviewer используется таблица содержания. Содержание хранится отдельно от самих файлов HTML и не является частью определения HTML.

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

Тематические файлы должны иметь расширение .toc. Они представляют собой текстовые файлы, содержащие по одной теме на строку. Формат каждой строки темы следующий:

уровень|заголовок|файл HTML или TOC

где:

уровень

Уровень заголовка. Значение 1 соответствует заголовку верхнего уровня, доступ пользователей к которому осуществляется непосредственно из дерева тем. Уровни заголовка 1 и 2 сортируются дереве тем в алфавитном порядке; уровни 3 и ниже выводятся в порядке следования в файле TOC.

заголовок

Текст заголовка темы (использовать коды HTML не допускается, разрешен только простой текст).

Файл HTML или TOC

Файл HTML или его URL-адрес, либо файл 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, содержащий несколько комплектов документов, в том числе:

папку и TOC высшего уровня для справки по IDE – ide_en и ide_en.toc.
В TOC содержится единственная запись 1 уровня, указывающая на файл HTML для комплекта документов высшего уровня, ide_en/bookset.html.

Уровень 2

Каталог уровня комплекта документов.

На этом уровне расположен каталог и файл TOC для каждого документа в комплекте документов и файл HTML высшего уровня для комплекта документов.

В качестве примера можно привести каталог $QNX_TARGET/usr/help/product/ide_en содержащий следующие файлы и каталоги:

bookset.html – базовая страница HTML для комплекта документов.
user_guide – каталог для «Руководства системного программиста (администратора)» КПДА.10964-01 32.
user_guide.toc – файл TOC с единственной записью второго уровня, указывающей на файл HTML высшего уровня для документа (user_guide/about.html).

Уровень 3

Каталог уровня документа.

На этом уровне расположен файл TOC и один или несколько тематических файлов HTML. Дополнительно могут присутствовать подкаталоги, позволяющие организовать файлы HTML по главам. В файле TOC содержатся записи уровня 3 и ниже для каждой темы в справочном документе.

В качестве примера можно привести каталог $QNX_TARGET/usr/help/product/phindows_en/user_guide, содержащий следующие файлы и каталоги:

about.html – файл HTML, включающий в себя все содержимое документа.
book.toc – файл TOC, содержащий все записи тем справки для таблицы содержания.

В справке должна применяться такая же трехуровневая иерархия, даже если имеется всего один документ. Утилита 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.

Файлы:

$QNX_TARGET/usr/help/product

Каталог тем по умолчанию

~/.ph/phelp/options

Конфигурационный файл

~/.ph/phelp/bookmarks

Закладки пользователя

~/.ph/phelp/history

Список просмотренных документов

Переменные среды:

QNX_HELP_PATH

Каталог файла справки по умолчанию. Значение этой переменной соответствует применению опции командной строки -t.

QNX_HELP_HOME_PAGE

Домашняя страница справки по умолчанию. Значение этой переменной соответствует применению опции командной строки - u.

Примечание. Эти переменные среды определяются интерпретаторами командной строки sh и ksh как переменные по умолчанию и указываются в файле /etc/profile.d/qnxsdk.sh. Если используется другой интерпретатор командной строки (например, esh или bsh) необходимо явным образом определить значения этих переменных, в противном случае вывод справки QNX по умолчанию с помощью команды helpviewer окажется невозможным.