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

Служба помощи MS Windows позволяет для ссылок на другие разделы использовать различные зоны растрового рисунка. Для создания таких зон используется отдельная программа Hotspot Editor с именем файла Shed.exe. Она позволяет для готового рисунка в BMP-формате произвести задание чувствительных зон и определить их свойства:

• Context string – задает для ссылок типа Jump или Pop-Up имя раздела для перехода;

– задает для ссылок типа Macro имя макрокоманды;

– задает тип ссылки (jump, pop-up или macro);

– задает стиль контура вокруг области (visible

или invisible);

• Hotspot ID – задает необязательное имя области;

• Bounding box – задает координаты прямоугольника для чувствительной области.

Задание зон производится буксировкой прямоугольной области мышкой с нажатой левой кнопкой. Вызов диалогового окна для настройки свойств производится правой кнопкой или двойным щелчком левой кнопки мыши.

После задания зон и их свойств результаты необходимо сохранить в том же каталоге, где размещаются текст файла помощи или BMP-файлы с картинками. Расширение сохраняемого файла по умолчанию – SHG. Вставка зонированного рисунка в файл помощи производится предложением {bmx filename.shg}, описанным в разделе 1.2.

2.СОЗДАНИЕ ПРОЕКТА И КОМПИЛЯЦИЯ ФАЙЛА ПОМОЩИ

2.1.Средства пакета Help Workshop

Для компиляции файла помощи должен быть создан проект, содержащий задание на трансляцию. Файл проекта сохраняется с расширением HPJ и содержит несколько секций. Для создания проекта необходимо выбрать из меню File команду New. В диалоговом окне выбрать пункт для создания файла проекта (Help Project) и задать имя проекта. Help Workshop для нового проекта создает минимальный набор секций и значений ключей по умолчанию. Остальные секции проекта автор должен создать самостоятельно в зависимости от целей проекта.

12

Минимально необходимой секцией является «Files» для указания перечня файлов с исходными текстами в формате RTF. Для задания секции необходимо нажать кнопку «Files», далее кнопку «Add» и в диалоге выбрать имя файла с расширением RTF. Проект должен содержать ссылку хотя бы на один файл с исходным текстом помощи. Автор для удобства работы может разбить содержание помощи на несколько исходных файлов. Каждый файл может содержать произвольное количество разделов. Компилятор производит механическое соединение информации всех исходных файлов.

Если автор использует ссылки на BMP-файлы, то необходимо задать каталог, где они расположены. По умолчанию компилятор производит поиск таких файлов в каталоге проекта и текущего RTFфайла. Если файлы располагаются в другом каталоге, его необходимо задать в секции «Bitmaps». Для этого следует нажать кнопку «Bitmaps», далее кнопку «Add» и задать имя папки в диалоговом окне. Удаление папки производится кнопкой «Remove».

При программировании приложений с использованием компонент Delphi разработчик может связать раздел помощи с визуальным компонентом, задав свойство «Helpcontext». Значением этого свойства является целое число, определяющее номер раздела. Для установления связи имени раздела (Topic ID) и номера служит секция «Map» проекта. Для формирования секции необходимо нажать кнопку «Map», добавить кнопкой «Add» новые описания соответствия имен разделов и номеров контекста. По желанию можно вставить заголовочный файл в формате языка программирования Си кнопкой «Include», который должен содержать готовые строки соответствия в синтаксисе файлов проекта. Эта возможность удобна при большом числе разделов помощи, для которых соответствие не меняется в диалоге с Help Workshop.

Часто в целях отладки или будущего расширения числа разделов помощи необходимо иметь возможность трансляции файлов, еще не содержащих нужных разделов. Тогда можно ввести дополнительные имена для существующих разделов, заменив ими несуществующие. Это выполняется в секции «Alias», где можно доба-

вить новые псевдонимы. В окне «Whenever this topic ID appears»

указывается новое имя раздела, а в окне «Use this topic ID instead» – старое.

Чтобы задать заголовок для окна помощи, следует нажать кноп-

ку «Options» и в окне «Help Title» на странице «General» задать текст заголовка длиной не более 127 символов. Здесь же в окне

«Display this text in the Version dialog box» можно задать информацию о версии файла помощи, в окне «If user paste or print Help text,

13

display:» можно задать текст обязательной вставки для печатаемого или вставляемого фрагмента файла помощи, например, для напоминания об авторских правах. В окне «Default topic» задается имя раздела по умолчанию, который первым показывается пользователю при запуске службы помощи. Можно произвести настройку режимов компиляции, указав состав отображаемой информации

(Notes, Progress, Errors).

На странице «Build Tags» можно задать идентификаторы разделов для включения (Include) и исключения (Exclude) из файла помощи при компиляции разделов со сносками Build Tag (*).

На странице «Files» можно задать имя файла оглавления (Contents), связанного с создаваемым файлом помощи. По умолчанию служба помощи использует имя файла помощи.

На странице «Sorting» можно задать правила сортировки ключевых слов для поиска разделов по указателю. На странице «Compression» задается степень сжатия, позволяющая управлять размером файла помощи. Доступны две степени сжатия при выборе пользователем: Hall и Zeck. Если выбрано только сжатие Zeck, то дополнительно можно задать необходимость построения файла фраз (.ph). При выборе варианта Hall сжатие производится более эффективно при размере файла помощи более 100 килобайт. При этом компиляция производится с большой скоростью. При выборе сжатия типа Zeck в комбинации с типом Hall достигается наибольшая эффективность сжатия. Если при этом выбирается опция Phrase, то строится дополнительный файл фраз, что позволяет получить хорошую эффективность для файлов помощи менее 100 килобайт.

На странице «Fonts» можно задать шрифты, используемые в диалоговых окнах указателя, оглавления и поиска разделов. Здесь же можно задать правила замены шрифтов при отображении разделов, если на машине пользователя таких не окажется.

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

На странице «Macros» можно задать связи ключевых слов с макросами, исполняемыми при открытии разделов, содержащих эти ключевые слова.

Для задания параметров окон демонстрации разделов помощи используется секция «Windows». Диалоговое окно этой секции содержит несколько страниц, позволяющих задать те или иные свойства окон. На странице «General» в выпадающем списке можно выбрать нужное окно для просмотра и корректировки его свойств. До-

14

бавление описания нового окна производится кнопкой «Add», запрашивающей имя нового создаваемого окна и его базовый тип: Procedure, Reference, Error. Процедурный тип окна используется для отображения замещающих разделов, может автоматически изменять размеры, имеет три кнопки и устанавливается в правом верхнем углу экрана. Ссылочный тип используется для демонстрации ссылочного материала, автоматически выбирает размер в 2/3 экрана, имеет три кнопки и устанавливается в левом верхнем углу экрана. Окно для диагностики ошибок автоматически выбирает размер, не имеет кнопок и устанавливается в правой нижней части экрана.

Следует иметь в виду то, что имя «main» связывается с главным окном помощи, и автор может установить его свойства по своему усмотрению, например, добавив кнопки управления последовательностями просмотра разделов. Всего можно определить до 255 различных окон.

Страница «Position» позволяет задать положение и размеры окна, страница «Color» – цвета неподвижной и подвижной частей окна. На странице «Buttons» автор может изменить набор кнопок меню создаваемого окна.

Компиляция файла помощи производится нажатием кнопки «Compile», расположенной на кнопочном меню программы Help Workshop или кнопки «Save and Compile». По результатам компиляции создается протокол, выдаваемый в окно системы. После анализа содержимого протокола его можно уничтожить, закрыв окно. Протокол содержит информацию об ошибках и предупреждениях компилятора, итоги компиляции и статистику. Характер сообщений позволяет отыскать неверный фрагмент исходного текста помощи и наметить план ликвидации причин сообщения.

При успешной компиляции можно просмотреть результат, вызвав службу помощи для созданного файла кнопкой «Run WinHelp». В диалоговом окне можно настроить требуемые режимы показа и используемые файлы и нажать кнопку «View Help».

2.2. Структура файла проекта помощи

Файл проекта помощи, используемый при компиляции, включает в свой состав следующие секции:

[ALIAS] – переопределение имен для существующих разделов;

[BAGGAGE] – задание списка файлов, размещаемых внутри файла помощи;

[BITMAPS] – задание имени папки для хранения рисунков;

15

[BUILDTAGS] – задание разделов для включения в файл помощи; [CONFIG] – задание последовательности макрокоманд при

открытии помощи для установки пользовательского меню и кнопок, используемых в файле помощи, регистрации библиотечных макрокоманд (DLL);

[CONFIG:name] – задание макрокоманд для настройки окон;

[WINDOWS] – задание конфигурации окон для просмотра помощи.

Ниже кратко приведен синтаксис секций проекта помощи.

[ALIAS] context_string=alias-topic_id

где context_string задает новый идентификатор раздела; alias-topic_id задает ранее определенное в сноске «#» имя раз-

дела.

Каждая строка задает одно соответствие имен, например: [ALIAS]

sm_key=key_shrtcuts cc_key=key_shrtcuts

[BAGGAGE] filename

где filename определяет файл, например, содержащий видеоклип, для включения в файл помощи (.HLP). Использование предложения {mci} автоматически включает файл в секцию [BAGGAGE].

[BITMAPS]

filename.bmp

Эта секция устарела и служит только для совместимости с предыдущими версиями. В новых версиях используется кнопка Bitmaps в Help Workshop, которая добавляет одно или несколько предложе-

ний BMROOT в секцию OPTIONS.

[BUILDTAGS] tag

Секция позволяет задавать флаги построения файла помощи. Для использования этой секции в исходном тексте разделов должны

16

иметься сноски типа «*». Следующий пример секции задает перечень помеченных разделов для включения в помощь.

[CONFIG] macro

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

[CONFIG]

RegisterRoutine(bmp, CopyBmp, S) CreateButton(btn_copyart, Copy Art, CopyBmp(`myart.bmp'))

[CONFIG:name] macro

Секция позволяет задавать только один макрос, исполняемый при открытии заданного параметром «name» окна. Например, следующий макрос закрывает все вторичные окна, когда пользователь раскрывает окно с именем «proc4»:

[CONFIG:proc4]

CloseSecondarys()

[FILES] filename

Секция перечисляет все файлы с исходным текстом разделов помощи (.rtf), используемых для создания файла помощи. Хотя бы один файл должен быть задан перед компиляцией проекта. В этой секции можно использовать список файлов, подготовленный в текстовом файле. В этом случае используется предложение #include filename. Файл должен находиться в той же папке, что и файл проекта помощи, или его имя должно содержать полный путь.

17

Help Workshop ищет файлы в папке проекта, в пути, указанном в имени файла, или в папках, заданных в предложении ROOT секции

[OPTIONS].

[MACROS]

keyword[;keyword1]

macro[;macro1] title

Секция [MACROS] связывает макросы с ключевыми словами. Макросы исполняются, когда пользователь выбирает эти ключевые слова при поиске в указателе. Параметрами этой секции являются:

•keyword – задает одно или несколько ключевых слов, связываемых с макросом;

•macro – задает одну или несколько макрокоманд, связанных с ключевыми словами.

• title – задает заголовок диалогового окна, появляющегося, когда выбранное слово связано с несколькими разделами помощи.

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

[MAP]

[#define] topic-id numeric value

Секция [MAP] связывает имена разделов (topic-id) с контекстными номерами (numeric value). Каждая строка задает одну связь. Разделителем параметров может быть произвольное число пробелов и символов табуляции. Предложение #define можно опускать. Номер задается десятичным числом, большим нуля, шестнадцатеричным числом в формате 0xnnnn или восьмеричным в формате 0nnnn, где nnnn – цифры числа.

Состав секции может быть подготовлен в отдельном Си-файле и подключен предложением

#include filename.h

[OPTIONS] option

Секция [OPTIONS] включает задание режимов компиляции файла помощи и является обязательной для каждого файла проекта. Каждая строка задает один из следующих режимов:

•BMROOT задает папку с рисунками, упоминаемыми в предложениях {bmc}, {bml} и {bmr} исходного текста помощи (.rtf);

•BUILD определяет разделы для включения в компиляцию;

•CHARSET задает набор символов по умолчанию;

18

•CITATION определяет текст, сопровождающий копируемый или печатаемый фрагмент файла помощи;

•COMPRESS задает степень сжатия файла помощи;

•CONTENTS задает имя начального раздела помощи по умолчанию;

•CNT задает имя файла с оглавлением (.cnt);

•COPYRIGHT задает текст об авторских правах, используемый в диалоговом окне о версии продукта;

•DBCS задает возможность использования двухбайтового набора символов;

•DEFFONT задает предопределенный шрифт текстовых окон помощи;

•ERRORLOG задает необходимость сохранения сообщений компилятора в файле протокола;

•FORCEFONT заставляет использовать все авторские шрифты при отображении разделов помощи;

•FTS определяет уровень информации для включения в указатель для полнотекстового поиска;

•HCW зарезервировано для использования Help Workshop;

•HLP задает имя создаваемого файла помощи (.hlp);

•INDEX_SEPARATORS определяет символ для отделения уровней пунктов указателя;

•LCID задает язык для файла помощи;

•MAPFONTSIZE задает соответствие размеров шрифтов в исходном и компилированном файлах помощи;

•MULTIKEY задает таблицу альтернативных ключей для использования в секции [MAP];

•NOTES определяет необходимость появления замечаний в протоколе трансляции;

•OLDKEYPHRASE определяет необходимость использования старой или новой таблицы ключевых фраз;

•REPLACE определяет путь для замены путей файлов. Если используется, то должен стоять перед опциями ROOT или BMROOT;

•REPORT управляет отображением сообщений при компиляции;

•ROOT задает папку с исходными файлами помощи;

•TMPDIR задает папку для временных файлов;

•TITLE задает текст заголовка окна помощи.

[WINDOWS]

window-name="caption", (x-coord, y-coord, width, height), state&buttons, (scrolling-RGB), (nonscrolling-RGB), state

19

Секция [WINDOWS] определяет размер, положение и цвета первичного и вторичных окон для просмотра разделов файла помощи. Параметры окон имеют следующий смысл:

•window-name – определяет имя окна (для первичного окна это main);

• caption – заголовок окна длиной не более 50 символов;

•x-coord – горизонтальная координата в системе координат от 0

до 1023;

•y-coord – вертикальная координата в координатной системе от 0

до 1023;

•state&buttons – состояние и набор кнопок окна. Задаются как поразрядная сумма следующих констант:

0x0001 – максимизировать окно;

0x0004 – отключить основные кнопки (только для главного окна); 0x0100 – добавить дополнительные кнопки;

0x0200 – добавить кнопки для просмотра последовательностей;

0x0400 – добавить кнопку для вызова оглавления;

0x0800 – добавить кнопку для вызова указателя;

0x1000 – добавить кнопку для вызова помощи;

0x2000 – добавить кнопку для печати раздела;

0x4000 – добавить кнопку для возврата назад;

0x8000 – добавить кнопку для поиска;

•scrolling-RGB – установка цвета перемещаемой области окна;

•nonscrolling-RGB – установка цвета неперемещаемой области окна;

•state определяет расположение окна относительно других:

1 – установить поверх остальных окон;.

2 – автоматически устанавливать вертикальный размер в соответствии с длиной раздела (только для вторичных окон).

Всего может быть определено до 255 вторичных окон в файле проекта. Если не заданы заголовки окон, то WinHelp помещает там первый, который найдет среди:

–заголовков в файле оглавления (.cnt);

–заголовков, заданных в опции TITLE проекта;

–заголовка "Windows Help" (в главном окне) или без заголовка (для вторичных окон).

20