Пишем простой хелп

Сергей Осколков

🕛 04.07.2006, 13:36

Справочная система (далее в тексте также - "справка") - важная составная часть любой более-менее сложной (и даже простой) программы. Существуют разные форматы справочных систем. Справка в формате WinHelp - о ней в статье и пойдет речь, Html-help - как, например, справка к ОС Windows или к программам MS Office. В качестве справки может выступать набор связанных html-файлов, например так организована справка к СУБД MySQL. Из достоинств WinHelp можно назвать ее надежность и меньшие, чем у HTML-help, требования к ресурсам. Существуют различные программы для создания справочных систем названных типов. Однако, для создания несложной справки вполне достаточно стандартной программы MS Help Workshop, которая поставляется с Delphi. Потребуется еще редактор rtf файлов, в данной статье описывается работа со знакомым всем MS Word'ом. Все действия, которые будут описаны - несложные, но мне в свое время потребовалось определенное количество усилий и времени, чтобы разобраться по справке к Help Workshop, как все это делать. Надеюсь, что статья сможет облегчить этот путь для других. Расчитана она на начинающих. В статье описывается создание простой справки, оглавления к ней, создание последовательностей просмотра, вставка рисунков и гиперссылок, а также подключение справки к программе. Рассматривается только техническая сторона, вопрос о том, что написано в справке, оставлен в стороне.

Общие сведения

В состав операционной системы Windows входит подсистема поддержки справки - WinHelp. Она имеет свое API, которое позволяет предоставить справочную информацию в том или ином виде в приложениях Windows. Создание справочной системы можно разделить на две части
Создание собственно справки, ее содержания
Подключение справки к программе - то есть обеспечение доступа к справочной информации удобным для пользователя способом.

В состав справки к программе обычно входит несколько файлов:
Файлы содержащие собственно информацию - имеют расширение .hlp
Файлы оглавления - .cnt (от апглийского content)
После первого вызова справки WinHelp создает файл .gid
Также другие типы файлов, например, для полнотекстового поиска, о чем в статье речь не идет.

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

Для создания справки сначала нужно подготовить файлы, содержащие справочную информацию. Это - обычные документы в формате rtf, которые можно создавать с помощью различных программ. Я здесь буду описывать работу с MS Word (создаем документ и выбираем "Сохранить как" - "Текст в формате RTF"). Будем называть эти файлы тематическими (topic files). Для получения из тематических файлов готовых файлов справки (hlp), их нужно обработать (компилировать) программой HelpWorkshop (hwc.exe). Кроме собственно текста и рисунков, тематические файлы могут содержать также специальную разметку, которая несет в себе информацию, нужную для создания переходов по ссылкам, связи оглавления справки с ее темами и т.п. - для реализации различных возможностей WinHelp.

Обычно справка содержит несколько тем и оглавление, из которого можно перейти к этим темам. Самый простой вариант: если тема - одна и оглавления нет. В таком случае просто пишем то, что нужно и сохраняем это в файле с расширением ".rtf". Для создания нескольких тем процесс усложняется ненамного:
Каждая тема должна заканчиваться жестким переходом на новую станицу. Для этого после окончания темы нужно в меню (напомню, что речь идет о MS Word) "Вставка" выбрать "Разрыв"->"Начать новую страницу".

Для того, чтобы тема были доступна из оглавления к справке, нужно задать ей идентификатор. Для этого нужно в то место текста, куда будет впоследствии происходить переход из оглавления (начало темы или, если нужно, другое место), вставить специальную разметку, а именно: концевую сноску. Символом сноски нужно выбрать "#". Идентификатором темы служит текст сноски. Например, создадим тему "Поддержка", отделим ее от других тем разрывами страниц и зададим ей идентификатор "support". Для этого поместим каретку ввода около заголовка темы и выберем в меню "Вставка"->"Сноска...". В диалоговом окне (рис.1) выбираем вид сноски - "концевая", нумерация - "другая", в окошке для ввода символа пишем "#" (без кавычек, понятное дело). Нажимаем ОК, ссылка добавлена и каретка автоматически переведена к тексту ссылки. Пишем "support". Готово.
Повторяем то же самое для всех тем справки. Сохраняем файл. Теперь можно попробовать создать свой хелп.

Запускаем программу HelpWorkshop. Это - файл Hcw.exe в директории Delphi\Help\Tools\. Создаем новый проект через меню "File"->"New"->"Help Project". Справа на панели есть ряд кнопок, нажимаем "Files...". В диалоговом окне добавляем наш тематический файл и закрываем это окно. Сохраним проект - это будет файл с расширением hpj (Help Project). Насколько я понял, после первого запуска Help Workshop связывает себя с файлами hpj, а также - с файлами оглавления справки (cnt), так что их потом можно открывать двойным щелчком мышью. Для создания help-файла можно просто нажать кнопку "Save and Compile". Откроется новое окно с сообщением о результате компиляции. Предположим, что все в порядке, закроем это окно. Теперь в директории, где находился наш проект (.hpj), должен появиться файл справки. Однако, при двойном щелчке мышью на нем мы сможем просмотреть только первую тему. Чтобы просматривать все темы и перемещаться между ними, нужно добавить файл оглавления.

Создание оглавления справки.

Файл оглавления справки имеет простой текстовый формат, но создавать его удобно тоже в HelpWorkshop. Для этого выбираем в меню HelpWorkshop "File" -> "New" -> "Help Contents". В верхней части окна нужно вписать имя главного файла справки (файлов, вообще говоря, может быть несколько) и заголовок (title) для оглавления справки. То же можно сделать в диалоговом окне, которое открывается при нажатии кнопки Edit... .

Теперь создаем собственно оглавление. Оно состоит из элементов двух типов - разделы справки, которые включают в себя несколько тем и представлены в оглавлении справки значком книжки и сами темы - текст и картинки, представлены в оглавлении справки значком листа со знаком вопроса на нем (можно посмотреть это в оглавлении любой справки). Также в оглавление можно вставить макросы и включить файлы (include), этого я здесь касаться не буду. Справа на панели есть набор кнопок для добавления и манипуляции элементами оглавления. (Add Below - Добавить ниже, Add Above - Добавить выше, Move Right - Сдвинуть вправо, Move Left - Сдвинуть влево, Edit, Delete). При помощи них создаем нужную структуру оглавления. При добавлении раздела в диалоговом окне нужно указать только его название, при добавлении темы - название, идентификатор (тот, который мы задали ей в rtf-файле, когда вставляли концевую сноску), имя help-файла и имя окна. Если тема находится в том же help-файле, который мы указали как главный, то имя help-файла указывать не нужно. Имя окна указывать тоже не обязательно, если оно не указано, то тема откроется в окне по-умолчанию. Нужно сохранить файл оглавления (он будет иметь расширение .cnt) в той же директории, где находится help-файл лучше с тем же именем, что и help-файл. Теперь нужно снова открыть файл проекта .hpj и, нажав кнопку "Options", в открывшемся диалоговом окне на закладке "Files" указать наш файл оглавления (Contents file). Закрываем диалоговое окно, снова нажимаем "Save and Compile". Теперь при двойном щелчке мышью по значку файла справки должно открыться ее оглавление, из которого можно получить доступ ко всем темам.

Мне не удалось, похоже, это невозможно, создать такую структуру оглавления, чтобы в самом левом ряду сначала шел значок темы (например, "Общие сведения"), а под ним - значки разделов. Пришлось даже для одиночной темы создавать раздел, содержащий ее одну.

Создание последовательностей просмотра.

Удобно перемещаться в справке от темы к теме с помощью кнопок ">>" и "<<" на панели инструментов окна или при помощи клавиш "<", ">" клавиатуры. Чтобы добавить такую возможность, нужно:
Создать одну или несколько последовательностей просмотра (browse sequence) в .rtf файле текста справки, добавив соответствующую разметку.
Определить в проекте справки (файл .hpj) окно с соответствующими кнопками.

Разметка имеет следующий вид: это тоже концевые сноски, как и для идентификаторов тем, однако в данном случае знаком сноски служит не символ "#", а "+" - знак плюса. Текстом сносок может быть либо число, либо строка символов. Просмотр будет осуществляться в порядке возрастания (как при сортировке строк). Отсюда следующее - если используются номера, то нужно вставлять необходимое количество нулей перед значащими цифрами для правильной сортировки. Например, если у Вас 20 тем, то первые нужно нумеровать как 01, 02, и т.д. Возможно несколько вариантов:
Если последовательностей несколько, то каждая из них может иметь имя, а темы внутри последовательности отличаться номерами (например, GUI1, GUI2, GUI3, ...), Если номера не заданы, WinHelp сам создаст последовательность просмотра при компиляции проекта в том порядке, как расположены темы в файле .rtf.
Если не писать ничего в текстах ссылок или написать во всех ссылках "auto" (без кавычек), то WinHelp при компиляции создаст одну последовательность просмотра в том порядке, как расположены темы в файле .rtf.

Чтобы добавить кнопки навигации "<<" и ">>" в окне справки (по умолчанию их нет), нужно определить хотя бы одно окно. Для этого, открыв файл проекта в HelpWorkshop, нужно нажать кнопку "Windows..." в правой части окна. В диалоговом окне с закладками нажать кнопку "Add..." и в открывшемся окне ввести в поле названия "main", а поле типа окна очистить, после чего нажать OK. Теперь у нас определено одно окно, различные свойства которого можно изменять, перемещаясь по закладкам. На закладке "Buttons" отмечаем галочкой "Browse". Нажимаем ОК, готово. Теперь окно справки будет иметь нужные кнопки. Нажимаем "Save and Compile" внизу окна и можем проверять, что получилось в выходном help файле.

Добавление картинок и гиперссылок.

Бывает, что в справку нужно поместить изображения. Это можно сделать, просто добавив их в документ rtf обычным для MS Word способом. Если одно изображение используется в нескольких местах, то можно воспользоваться специальной разметкой, предусмотренной для вставки изображений в справку, так что изображение будет храниться в одном экземпляре. Здесь я не буду рассматривать, как это сделать (честно говоря, я этого никогда и не делал).

Обычное дело - указать адрес своего сайта и/или электронной почты в разделе "Поддержка". Как сделать, чтобы эта ссылка выглядела и функционировала как гиперссылка на Веб-страницах? Аналог гиперссылки, т.е. тега anchor (<a>) HTML в WinHelp - "hotspot". Hotspot - это область, по щелчку мыши на которой, выполняется какое-либо действие из предусмотренных в WinHelp. В данном случае нам нужно запустить один из макросов WinHelp, а именно макрос ExecFile. Этот макрос напоминает функцию WinApi ShellExecute. Синтаксис его такой:

ExecFile(program[, arguments[, display-state[, topic-ID]]])

Первый параметр, как написано в справке, может указывать на программу или файл. Однако, как и в ShellExecute, вместо имени файла можно указать URL, например "http://www.mysite.ru" или "mailto:nekto@somemail.ru".
Чтобы создать hotspot, запускающий такой макрос, нужно сделать следующее:
Сразу после текста hotspot'a ввести символ "!", а сразу за ним - текст макроса, например:

Наш сайт: www.mysite.ru!ExecFile(http://www.mysite.ru)

Примечание: URL в скобках должен быть без кавычек.
Далее, нужно отформатировать этот отрывок так: текст hotspot'a должен иметь двойное подчеркивание, а символ "!" и текст макроса после него - иметь атрибут "скрытый". И то, и другое делается через меню "Формат" -> "Шрифт" (см. рис. 2) На всякий случай, еще раз уточню: двойное подчеркивание (выпадающий список рядом с "цветом текста"), а не зачеркивание..

Теперь, если добавить такой hotspot и компилировать проект, то мы увидим в своей справке, что в строке текста

Наш сайт: www.mysite.ru - адрес выглядит и функционирует как гиперссылка.
Присоединяем справку к программе.
Чтобы справка была доступна в программе, нужно указать программе на файл .hlp. Самый простой способ размещения файла справки - в той же папке, где находится исполняемый файл. Определить для приложения файл справки можно так: открыв проект (приложения) в Delphi и выбрав меню "Project" -> "Options" -> "Application", вписать название файла справки в поле ввода "Help file". При этом нужно указать название файла без пути. Когда WinHelp пытается найти справочный файл, одна из просматриваемых директорий - та, где расположен исполняемый файл программы. Другой способ - в обработчик события OnCreate главной формы программы вставить строку:

Application.HelpFile:=ExtractFilePath(Application.ExeName) + "MyHelp.hlp";

где MyHelp.hlp - название файла справки.

Чтобы из меню в программе вызвать оглавление справки, нужно воспользоваться функцией

Application.HelpCommand(HELP_FINDER, 0);

Чтобы перейти к одной из определенных нами тем справки, нужно вызвать функцию

Application.HelpJump('MyTopic'),

где MyTopic - идентификатор темы.

Один из способов вызова справки - нажатие клавиши F1. Можно организовать вызов контекстной справки при нажатии на F1, когда активным является тот или иной элемент управления. Для этого соответствующей теме справки нужно присвоить номер, а затем этот номер присвоить свойству HelpContext элемента управления. Чтобы задать номера для тем справки, нужно открыть проект справки в HelpWorkshop и нажать кнопку "Map" в правой части окна. Нажимаем в диалоговом окне "Add", вводим идентификатор темы и произвольный номер (например, 1 :) ), повторяем это для всех нужных тем (каждой - свой номер), закрываем окно и нажимаем в очередной раз "Save and Compile". Затем в Delphi, в окне инспектора объектов, присваиваем нужные номера нужным элементам управления (напоминаю, свойство HelpContext).