Создание help файлов в Delphi

СОЗДАНИЕ ВСТРОЕННОЙ СПРАВОЧНОЙ СИСТЕМЫ
Для реализации процесса вам понадобятся :
текстовый RTF-редактор Microsoft Word, поддерживающий расширенный текстовый формат RTF
компилятор Help-файлов (hcsi.exe или в версиях 4 и 5 Microsoft Help Workshop (файл hcw.exe из каталога help | tools каталога размещения Delphi).

ЭТАПЫ РАЗРАБОТКИ
Планирование системы справок: составляется перечень разделов справочной службы и необходимых перекрестных ссылок.
Создание текстовых файлов, содержащих описания справочных разделов. В них включаются специальные управляющие символы для создания перекрестных ссылок и подключения растровых изображений.

ЭТАПЫ РАЗРАБОТКИ
Разработка проектного файла, содержащего специальные команды для Help-компилятора. Каждому разделу присваивается уникальный целочисленный идентификатор.
Разработка файла содержания. Содержание активизируется при запуске HLP-файла, а также после щелчка по кнопке содержание в окне справочной службы.

ЭТАПЫ РАЗРАБОТКИ
Компиляция Help-файлов.
Тестирование и отладка Help-службы.
Связь программы с разделами Help-службы.

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

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

Рекомендации при создании текстовых файлов
В пределах одного файла каждый раздел отделяется от другого служебным символом конца страницы (Ctrl+Enter).
Любой раздел, доступный с помощью перекрестных ссылок или индексных указателей, должен иметь связанный с ним идентификатор - уникальную текстовую строку.
Раздел может иметь название и связанный с ним список ключевых слов.

Управляющие символы
Сноска “#” Перечеркнутый или дважды подчеркнутый текст
Указывает идентификатор раздела. Определяет отображение связанного с текстом раздела.
Подчеркнутый текст
Определяет отображение раздела перекрестной ссылки в окне пояснений (“всплывающем” окне)

Управляющие символы
Скрытый текст
Определяет идентификатор раздела, связанного с перекрестной ссылкой
Сноска “$”
Задает название раздела
Сноска “К”
Указывает список ключевых слов для поиска раздела
Сноска “/\”
Определяет условие компиляции раздела

Управляющие символы
Сноска “+”
Задает порядковый номер раздела в списке просмотра связанных разделов
Сноска “>”
Определяет тип дополнительного окна, в котором будет отображаться раздел
Сноска “!”
Указывает макрокоманду, которая будет выполняться при открытии окна с разделом

Идентифицирующая строка может содержать любые символы, кроме #, @, !, *, =, >, % и пробелов. Разница в высоте латинских букв (но не кириллицы!) игнорируется. Длина строки - до 255 символов.
В качестве идентификаторов имеет смысл использовать текст заголовка раздела, в котором пробелы заменены символами подчеркивания.

Символы “*” и “%” вставляются непосредственно перед идентификатором раздела и, так же как и он, оформляются скрытым текстом
ГИПЕРТЕКСТ%НУРЕRТЕХТ

Символы “@” и “>” вставляются в конце скрытого текста и за ними должны следовать:
маршрут доступа и имя HLP-файла - для символа “@”;
имя типа окна, в котором следует отобразить раздел - для символа “>”; это окно должно определяться в файле проекта
Если раздел hypertext расположен в файле c:\proba\proba.hlp и должен показываться в дополнительном окне типа wind, соответствующая ссылка будет такой: ГИПЕPTEKCT HYPERTEXT@C:\PRQBA\PROBA.HLP> WIND

Для определения ключевого слова в начале раздела (до первого символа текста раздела) ставится сноска, помеченная латинской буквой “К” или “k”. Например:
к открыть;текст файл;ASCII;текст

Помимо основной таблицы ключевых слов в Help-службе может быть определена дополнительная таблица. Слова из дополнительной таблицы не показываются в окне Поиск. Для вставки ключевых слов в дополнительную таблицу используется сноска, помеченная латинской буквой “А”:
А таблица/слово

В тексте сноски “*” можно указать одно или несколько управляющих слов (следующие друг за другом слова в тексте сноски разделяются символом “;”). Раздел будет включен в Help-файл, если хотя бы одно из связанных с ним управляющих слов указано в секции include файла проекта (если раздел не имеет сноски “*”, он всегда включается в результирующий файл). Управляющие слова могут содержать любые символы, кроме “;” и пробелов.
Например: Test_Build; AppVersionI; DebuggVer

Кнопки просмотра связанных разделов появляются в справочном окне автоматически, только от одного факта указания сноски “+” в текущем разделе.
Чтобы связать с разделом код для указания порядка просмотра раздела, необходимо вставить сноску “+”:
+гл_меню:010

Файлы с графикой должны соответствовать формату bmp.
Чтобы вставить в текст графический образ, необходимо поместить на предназначенное для размещения графики место специальную директиву в одном из следующих форматов:
{bmc filename.bmp}
{bml filename.bmp}
{bmr filename.bmp}
Здесь filename - имя вмр-файла; bmc, bml, bmr - команды, управляющие положением картинки относительно текста.

Для вставки в инструментальную панель кнопок просмотра связанных разделов сноска имеет такой вид:
!BrowseButtons ( )

Помимо основного окна в справочной службе можно определить множество дополнительных окон, каждое из которых будет иметь свой цвет, заголовок, размеры и т. д.
Дополнительные окна описываются в секции [windows] проектного файла.
Чтобы указать, что раздел справки должен по умолчанию отображаться в дополнительном окне, используется ссылка “>”
В тексте ссылки указывается тип окна так, как он определен в проектном файле, например:
>wind

Разработка проектного файла
Проектный файл служит основным управляющим документом для Help-компилятора. В Windows 32 он создается с помощью утилиты Microsoft Help Workshop (MS HW) и представляет собой ASCII-текстовый файл, содержащий несколько секций.
Секция - это фрагмент текста, состоящий из заголовка и одной или нескольких следующих за ним строк (опций) вида
ИМЯ_ПАРАМЕТРА = ЗНАЧЕНИЕ

Для запуска MS HW следует загрузить файл help | tools | hcw.exe из папки размещения Delphi\Help\Tools.
Для создания нового проектного файла выберите File | New и в дополнительном диалоговом окне - Help project.

Секция Options
Options - создается или изменяется с помощью кнопки options, содержит общие для всей справочной службы установки : определяет умалчиваемую тему, заголовок основного окна, используемый в текстах язык и т. п.

Страница General
Default topic - идентификатор умалчиваемого раздела;
Help title - заголовок основного окна справочной службы; заголовок можно также изменить при создании файла содержания
Notes - если переключатель выбран, компилятор сообщает о возникающих проблемах, если не выбран - только общее количество предупреждений и ошибок;

Страница General
Progress - если переключатель выбран, компилятор сообщает о транслируемом -RTF-файле;
Errors - открывает окно для указания кодов ошибок, о которых компилятор не будет сообщать;
Display this text... - определяет текст, который будет помещен
if users paste... - определяет текст, который будет добавляться в конце копируемой через Clipboard или печатаемой справочной информации.

Страница Compession
Эта страница управляет сжатием результирующего файла.
None - результирующий файл не сжимается;
Maximum - результирующий файл максимально сжимается;
Custom - выбирает алгоритм сжатия результирующего файла.

Страница Sorting
Задает язык и способ сортировки ключевых слов.
Language of Help file - определяет используемый для сортировки ключевых слов язык;
Other - определяет язык сортировки по его индексу;
Non-spacing marks - если переключатель выбран, при сортировке игнорируются кавычки и апострофы; Symbols - если переключатель выбран, при сортировке игнорируются пробелы и знаки препинания; separate index... - содержит перечень символов, которые используются для указания нижних уровней сортировки.

Страница File
Определяет расположение используемых в проекте файлов и папок.
Help File - имя результирующего нlр-файла; это имя должно быть указано обязательно;
Log File - имя ASCII-текстового файла, в который компилятор будет помещать свою информацию (может не указываться);
RTF-files - определяет имена исходных файлов с текстами справок; замечу, что изменение имен файлов фактически приводит к изменению секции [Files]

Страница File
contents file - указывает имя файла содержания, если такой файл создан
тмр folder - определяет папку для хранения временных файлов компилятора;
substitute path prefix - указывает имя маршрута доступа к rtf и вмр-файлам; используется при перемещении этих файлов в другую папку, чтобы не исправлять множество ссылок во всей справочной информации.

Страница FTS
Управляет созданием индекса для быстрого поиска по отдельным словам или фразам справочного текста. Этот индекс создается при первом обращении к окну поиск.
Опции этой страницы имеют значение только для сжатых файлов. Переключатели Enable могут существенно влиять на объем результирующего файла и время поиска информации.

Страница FTS
Generate full text search index - Создавать индекс по всем словам справочных фалов;
Include untitled topics in index - включает в индекс разделы без названия
Enable search for word only - разрешить поиск только по словам;
Enable search for phrase - разрешить поиск по фразам;
Enable display of matching phrase - разрешить поиск по списку выделенных фраз;
Enable search for similar topics - разрешить поиск по альтернативным словам.

Страница Macros
Определяет макрокоманды, автоматически выполняемые при выборе того или иного ключевого слова.
Keywords - содержит список ключевых слов, для которых определены макрокоманды;
Title that appears... - указывает заголовок окна Найденные разделы при выборе соответствующего слова;
Macro (s) associated with... - связанная со словом макрокоманда;

Страница Macros
Add - позволяет добавить слово к списку Keywords;
Remove - удаляет слово из списка Keywords;
Edit - изменяет определение макрокоманды или заголовка для указанного слова

Страница Build Tags
Содержит список условий, включающих разделы в результирующий файл (верхний список) или исключающих их из него (нижний список). Условия касаются только тех разделов, которые помечены ссылкой “*”

Страница Fonts
Определяет шрифты, используемые в справочной системе.
character set - определяет используемый в результирующем файле набор символов (он может отличаться от набора символов на инструментальной машине);
Font in winHelp Dialog boxes - определяет шрифт, используемый в диалоговых окнах справочной службы;
substitute this fonts.. - содержит перечень подстановок, указывающих, какой шрифт в исходном RTF-файле будет заменен при отображении в окне справки и на какой шрифт он будет заменен.

Секция FILES
С помощью этой секции определяются RTF-файлы, содержащие текст, справочной системы. Для нормальной работы компилятора необходимо определить хотя бы один файл в этой секции.

Секция WINDOWS
Секция [windows] определяет используемый в справочной службе набор дополнительных окон. Каждое указанное в секции окно характеризуется своим типом, цветом, размерами, заголовком. Только имена перечисленных в секции окон могут указываться в ссылках и сносках “>” RTF-файлов.

С помощью списка Based on this standard window можно выбрать один из трех возможных стандартных типов окна:
procedure - окно предназначено для вывода текстов процедур; оно позиционируется в правом верхнем углу экрана и при значительной ширине может своим правым краем выйти за пределы экрана;

Reference - обычное справочное окно; позиционируется в левом верхнем углу, занимает приблизительно 2/3 экрана по высоте и ширине;
Error message - окно предназначено для вывода сообщений об ошибках, позиционируется по центру экрана, занимает почти всю высоту экрана и 3/4 его ширины.

Страница General
window type - позволяет выбрать одно из ранее определенных окон; все дальнейшие установки на странице General будут осуществляться для указанного в этой строке окна; подобные строки есть на всех других страницах окна window Properties;
Add - вызывает окно рис. 21.8 для добавления нового окна к списку окон;
Remove - удаляет окно из списка;
include - включает ASCII-текстовьгй файл со списком окон;
Title bar text - определяет заголовок окна;

Страница General
comment - содержит произвольный комментарий; здесь, например, можно указать функциональность окна; текст комментария не включается в результирующий файл;
Auto-size height - если переключатель выбран, окно автоматически изменяет высоту в зависимости от разрешения экрана;
Maximize window - окно максимизируется по размеру экрана;
Keep Help window on top - окно всегда появляется поверх остальных окон.

Страница Position
Определяет положение и размеры окна в момент его появления на экране. тор - отступ левого верхнего угла от верхнего края экрана;
Left - отступ левого верхнего угла от левого края экрана;
Height - высота окна;
width - ширина окна;
Adjust for user screen resolution - если переключатель выбран, координаты задаются относительно виртуального экрана с разрешением 1024х1024; если не выбран, координаты указываются в пикселях;

Страница Position
Auto-sizer - после щелчка по этой кнопке появляется окно с кнопками ОК и Cancel для визуальной настройки его размеров и положения;
Default position - после щелчка по этой кнопке окну задаются умалчиваемые размеры.

Страница Buttons
Определяет состав включаемых в окно инструментальных кнопок. Если выбран указанный ниже переключатель, в окно вставляется соответствующая кнопка.
Contents - кнопка Содержание;
Index - кнопка Индекс;
Find - кнопка Поиск;
Help Topics - кнопка Разделы;
Print - кнопка Печать;
Back - кнопка Назад;
Options — кнопка Параметры;
Brows - кнопки просмотра связанных тем.

Страница Color
Позволяет изменять цвет фиксированной (Nonscrolling area) и основной (Topic area) зоны окна. Изменения становятся доступны после щелчка по соответствующей кнопке Add.

Страница Macros
С помощью этой страницы можно указать макрокоманды, которые будут автоматически выполняться при появлении окна на экране.

Секция BITMAPS
Эта секция определяет список папок, в которых компилятор будет искать графические файлы, встроенные в текст справки директивами bmc, bmi, bmr
Если ни одна папка не определена, компилятор сможет подключить только те файлы, которые располагаются в том же каталоге, где создается hlр-файл.

Секция MAP
В этой секции следует определить числовые идентификаторы разделов, которые будут автоматически вызываться кнопками Help и клавишей F1 в работающей программе.
Только разделы, указанные в секции [map] , могут быть контекстно-доступными из работающей программы.
Остальные разделы можно просмотреть после вызова справки с помощью выбора ключевых слов, кнопками просмотра связанных разделов или по содержанию справочной службы.

В списке Map topics IDs to numeric values указываются уже определенные разделы в формате
идентификатор_темы=Неlр Сontext
Здесь идентификатор_темы - идентификатор, определенный сноской # в RTF-файле; HelpContext -присвоенный разделу числовой идентификатор, который можно помещать в свойство HelpContext визуального компонента

При разработке файлов справочной службы, включающих множество разделов, приходится запоминать многочисленные идентификаторы разделов, чтобы поставить им в соответствие числовые идентификаторы.
Можно вызвать опцию File | Report, в появившемся диалоговом окне указать имя hlр-файла и имя файла для отчета, установить режим вывода названий (отметить переключатель Titles) и щелкнуть по кнопке Report - MS HW создаст текстовый файл с перечнем названий всех тем.

Секция ALIASES
В этой секции можно указать псевдонимы идентификаторов разделов, с помощью которых можно модифицировать секцию Map без изменения RTF-файлов. Назначение кнопок Add, Remove, Include и Edit такое же, как и в секции мар. После назначения псевдонима он может использоваться в секции мар вместо идентификатора раздела. Эта возможность облегчает модификацию справочной службы.

Секция Config
Секция [Config] предназначена для указания макрокоманд, которые будут выполняться в момент открытия справочной службы. С ее помощью можно также зарегистрировать подпрограммы из библиотеки) DLL, которые после этого могут использоваться наравне с макрокомандами.

Секция BAGGAGE
Кнопкой Data Files окна MS HW открывается диалоговое окно определения файлов, которые будет использовать справочная служба. Список этих файлов содержит секция [Baggage] проектного файла. Помимо RTF-файлов, которые обычно вставляются в секции [Files], здесь можно также указать файлы библиотек DLL, подпрограммы которых после этого могут использоваться как макрокоманды.

Файл содержания справочной службы
Чтобы создать файл содержания, запустите MS HW, выберите File \ New и затем Help Contents
В строках Default filename (and window) и Default title в верхней части окна нужно указать соответственно имя hlp-файла, для которого создается содержание, и тип окна для отображения оглавлений, а также заголовок основного окна справочной службы.
HelpTest.hlp>WIND

Тип вставляемого элемента
Heading - вставляется тема; при выборе этого переключателя все расположенные ниже строки, кроме Title, становятся недоступными;
Topic - вставляется раздел;
Macro - вставляется макрокоманда; эта макрокоманда будет выполняться при выборе элемента в окне содержания;
Include - вставляется ASCII-текстовый файл с элементами содержания.

Четыре строки ниже переключателей используются только при вставке раздела. При вставке темы или включаемого файла доступна только первая строка, при вставке макрокоманды - первая и вторая, которая в этом случае снабжается надписью Macro.
В строке Title вводится произвольный текст длиной до 127 символов, который будет представлять элемент в окне содержания. В этой строке также указывается имя включаемого файла, если выбран переключатель Include. Во второй строке указывается идентификатор раздела или имя макрокоманды.
В строке Help file нужно указать hlp-файл, если справочная система использует несколько файлов, а в строке window type - тип окна для отображения раздела.

Компиляция

Тестирование
Для тестирования скомпилированного справочного файла используется одна из опций меню Test:
contents File - тестирует файл содержания;
close All Help - закрывает все ранее открытые нlр-файлы;
send a macro - посылает в winHelp нужную макрокоманду;
WinHelp api - вызывает нужный раздел справочной службы по присвоенному ему в секции map числовому идентификатору.

Связь с программой
Связь с программой реализуется с помощью свойств HelpContext видимых компонентов, в которые следует поместить числовые идентификаторы нужных разделов справочной службы так, как они определены.
В секции MAP кроме того, в свойство Application HelpFile нужно поместить имя hlp-файла. Обычно эта связь устанавливается в обработчике события ОnCreate главной формы программы.

После такой настройки пользователь программы сможет с помощью клавиши F1 получить контекстно-чувствительную справку, т. к. при нажатии F1 автоматически вызывается раздел, числовой идентификатор которого помещен в свойство HelpContext компонента с фокусом ввода.
Если Helpcontext компонента с фокусом ввода содержит 0, вызывается раздел, указанный в HelpContext его владельца, а если и у того это свойство не определено, используется HelpContext активной формы (если во всей цепочке владельцев, включая активную форму, свойство HelpContext не определено, нажатие F1 игнорируется).

Для смещения элемента оглавления на один уровень иерархии вниз используется клавиша Move Right, а на один уровень вверх -Move Left. Элемент сдвигается вместе со всеми другими элементами, расположенными ниже него. Максимальное количество уровней иерархии - 9.
Следует заметить, что файл содержания представляет собой ASСII-текстовый файл, каждая строка которого соответствует элементу содержания. В начале строки указывается цифра, определяющая уровень иерархии, на котором располагается элемент.

МАКРОКОМАНДЫ WINHELP
Макрокоманды могут выполняться в следующих случаях:
при открытии справочного файла (определяются в секции Соnfig);
при открытии окна с разделом (определяются сноской “!”);
при выборе ключевого слова (определяются на странице Macros окна options).