Файлы таблиц содержания

Файлы таблиц содержания (Table-of-contents-TOC) определяют список продуктов, имеющих информационную помощь, и иерархию тем для каждого продукта. Эти файлы имеют расширение .toc. Все они располагаются в директории /usr/help/product. Каждый продукт имеет TOC-файл 1-го уровня и директорию с чем-либо ещё. Так, например, помощь по Photon'у включает:

photon.toc

photon/

Файл photon.toc состоит из следующей строки:

1 | Photon micro GUI | ./photon/bookset.html

где:

1 – это уровень иерархии тем;

| – разделитель областей;

Photon micro GUI – название темы.

./photon/bookset.html – унифицированный указатель информационного ресурса (URL) комплекта описания.

 Не используйте вертикальную черту ( | ) в названии темы, поскольку она используется в TOC-файлах в качестве разделителя.

Директория photon содержит TOC-файл и директорию для каждой книги. Например, она включает:

prog_guide.toc

prog_guide/

Файл prog_guide.toc похож на файл photon.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 | Chades and corrections | #ChangesAndCorrections

3 | Introduction | intro.html#id1

4 | Photon Application Builder – PhAB | #PhABApplications

6 | Get immediate results | #id3

.....

Часть URL, следующая за # – это анкер, определённый в HTML.

Ссылки на темы помощи

Просмотровщик помощи понимает два явных способа задания расположения HTML-ского текста помощи, который должен отображаться:

• Унифицированный указатель информационного ресурса (URL)

• Маршрут тем

Унифицированный указатель информационного ресурса (url)

URL задаёт маршрут в файловой системе к файлу текста помощи. Он задаёт этот путь стандартным для HTML способом, за исключением того, что все файлы должны располагаться в локальной сети.

Вот пример URL:

/usr/help/product/photon/prog_guide/window_mgmt.html

 URL является чувствительным к регистру букв. Эти URL'ы ограничены рамками файлов помощи; они не могут использоваться для доступа к Всемирной Паутине.

Маршрут тем

Маршрут тем – это группа сцеплённых названий тем, определённых в дереве текущей темы. Например, вот маршрут тем, эквивалентный приведенному выше URL'у:

/Photon microGUI/Programmer's Guide/Window Management

Для просмотровщика помощи маршрут тем является нечувствительным к регистрам букв (в отличие от других просмотровщиков HTML-файлов) и маршрут может содержать групповые символы _* или ?, где "_*" согласуется со строкой, и "?" согласуется с символом. Выбирается первая тема, удовлетворившая сравнению.

Дерево тем, используемое просмотровщиком помощи, должно иметь по меньшей мере три уровня иерархии: верхний уровень известен как "книжная полка", второй – как "собрание сочинений", и третий – как "книга". Книга может содержать последующие уровни – глав, разделов.

Входы в книжную полку или книгу не могут содержать каких-либо HTML-файлов, а только .toc – входы на следующий уровень; текст помощи должен находиться только в книгах.

Связывание помощи с виджетами

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

Независимо от того, какой метод Вы выбрали, Вам необходимо выполнить в каждом окне Вашего приложения следующее:

1. Установить флаг Ph_WM_HELP в ресурсе управления флагов (Pt_ARG_WINDOW_MANAGER_FLAGS).

2. Установить флаг Ph_WM_RENDER_HELP в ресурсе отображения флагов (Pt_ARG_WINDOW_RENDER_FLAGS). Это добавит иконку "?" на рамку окна. Пользователь может щёлкнуть на иконке, затем щёлкнуть на виджете, и отобразится информация с помощью.

Если для Вашего приложения не применимо по каким-либо причинам использование иконки "?", см. раздел "Помощь без иконки "?" ниже в этой главе.

Для более полной информации см. главу "Управление окном".