Турбо Паскаль для Windows. Компилятор справочной информации [Автор неизвестен] (txt) читать онлайн
















Т У Р Б О П А С К А Л Ь

для W I N D O W S



К О М П И Л Я Т О Р С П Р А В О Ч Н О Й

И Н Ф О Р М А Ц И И


























СОДЕРЖАНИЕ

ГЛАВА 1:
ПРЕДОСТАВЛЕНИЕ ПОМОЩИ: СИСТЕМА HELP
Cоздание Help системы:
Цикл разработки программ...............................
Как Help представляется пользователю...................
Как Help представляется разработчику текста Help.......
Как Help представляется программисту...................
Резюме.................................................

ГЛАВА 2:
ПЛАНИРОВАНИЕ СИСТЕМЫ HELP
Разработка плана.......................................
Определение категории пользователей..................
Планирование содержания системы Help.................
Планирование структуры тем Help......................
Выведение на дисплей контекстно-чувствительных тем
Help.................................................
Определение структуры тематического файла..............
Выбор файловой структуры для Вашей программы.........
Конструирование представления тем Help.................
Компоновка Help текста...............................
Типы шрифтов и размеров..............................
Графические изображения..............................
Резюме.................................................

ГЛАВА 3:
СОЗДАНИЕ HELP ТЕМАТИЧЕСКИХ ФАЙЛОВ
Выбор санкционированного средства......................
Структурирование Help тематических файлов..............
Кодирование Help тематических файлов...................
Присваивание тегов построения........................
Присваивание контекстных строк.......................
Присваивание заголовков..............................
Присваивание ключевых слов...........................
Создание многочисленных таблиц ключевых слов.......
Присваивание номеров последовательностям просмотров....
Организация последовательностей просмотров...........
Кодирование последовательностей просмотров...........
Создание перекрестных ссылок между темами..............
Определение терминов...................................
Создание тем определений.............................
Кодирование определений..............................
Вставка графических изображений........................
Создание и захват растров............................
Размещение растров с использованием графических
систем подготовки текстов............................
Размещение растров посредством ссылки................
Управление тематическими файлами.......................
Отслеживание файлов и тем............................
Создание Help трассировщика..........................
Резюме.................................................

ГЛАВА 4:
ПОСТРОЕНИЕ HELP ФАЙЛА
Создание Help файла проекта............................
Определение тематических файлов: Сегмент Files.........
Определение тегов построения: Сегмент BuildTags........
Определение опций: Сегмент Options.....................
Определение сообщений об ошибках: Опция Warning......
Определение тем построения: Опция Build..............
Определение корневого справочника: Опция Root........
Спецификация индекса: Опция Index....................
Присваивание заглавия в Help системе: Опция Title....
Преобразование шрифтов: Опция Forcefont..............
Изменение размеров шрифтов: Опция Mapfontsize........
Таблица ключевых слов: Опция Multikey................
Сжатие файлов: Опция Compress........................
Определение новых контекстных строк: Сегмент Alias.....
Отображение контекстно-чувствительных тем: Сегмент Map.
Включение растров по ссылке: Сегмент Bitmaps...........
Компилирование Help файлов.............................
Использование Help компилятора.......................
Разработка программы для доступа к Help................
Вызов WinHelp из программ............................
Получение контекстно-чувствительной помощи.............
Shift+F1 поддержка...................................
F1 поддержка.........................................
Получение Help по элементу, перечисленному в меню Help.
Доступ к дополнительным таблицам ключевых слов.........
Отмена Help............................................
Резюме.................................................

ГЛАВА 5:
ПРИМЕРЫ HELP И СООБЩЕНИЯ ОБ ОШИБКАХ КОМПИЛЯТОРА
Help тематические примеры.............................
Сообщения об ошибках Help Compiler....................
Ошибки во время обработки файла проекта...............
Ошибки во время обработки RTF тематических файлов.....










ГЛАВА 1

ПРЕДОСТАВЛЕНИЕ ПОМОЩИ: СИСТЕМА HELP

Система Help обеспечивает пользователей интерактивной ин-
формацией о программе. Создание системы требует усилий как
разработчиков текстов Help, так и программистов Help. Разра-
ботчик текстов Help планирует, пишет, кодирует, создает и
отслеживает Help тематические файлы, которые являются тексто-
выми файлами, описывающими различные аспекты программы. Разра-
ботчик программы Help гарантирует, что система Help правильно
работает с программой.
В данной главе описываются следующие темы:
- Создание системы Help
- Как Help предоставляется пользователю
- Как Help предоставляется разработчику текста Help
- Как Help предоставляется программисту Help
Эта и последующие главы предполагают, что Вы знакомы с
Microsoft Windows Help. Эти главы используют примеры из учеб-
ных программ (написанных на С и Pascal), которые находятся на
Ваших дисках. Если Вы не знакомы с Windows Help, выберите мо-
мент для прогона примеров программ и используйте Helpex Help.

Создание системы Help : Цикл разработки программ

Создание системы Help для приложения Windows заключает в
себе следующие основные задачи:
1. Сбор информации для тем Help.
2. Планирование системы Help.
В главе 2 "Планирование системы Help" описываются сообра-
жения, необходимые Вам при планировании системы Help.
3. Написание текста для тем Help.
4. Введение всех требуемых кодов управления в текстовые
файлы.
Коды управления определяют, как пользователь может пере-
мещаться по системе Help. В раздел, озаглавленный "Как Help
представляется разработчику текста Help", включен пример из
нескольких управляющих кодов. В главе 3 "Создание Help темати-
ческих файлов" эти коды описываются более подробно.
5. Создание файла проекта для построения.
Help файл проекта обеспечивает информацию, которая необ-
ходима Help Compiler для построения Help файла ресурсов. В
главе 4 "Построение файла Help" описывается Help файл проекта.
6. Построение Help файла ресурсов.
Help файл ресурсов является компилированной версией тема-
тических файлов создаваемых разработчиком текста. В главе 4
"Построение файла Help" описывается как компилировать Help
файл ресурсов.
7. Тестирование и отладка системы Help.
8. Программирование приложения таким образом, чтобы она
могла иметь доступ к Windows Help.
Следующая блок - схема показывает основной рабочий поток
в концепции и разработке системы Help.

Рисунок 1.1 Диаграмма рабочего потока
┌─────────────────────────────────────────────────┐
│ Соберите данные программного продукта из: │
│ - Спецификации программного продукта │
│ - Руководства "Справочника команд" или │
│ "Справочника пользователя" │
│ - Практической работы с программой │
│ - Разрабатываемого программного обеспечения │
└────────────────────────┬────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ Перечислите темы и создайте контур Help │
└────────────────────────┬────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ Напишите программу с возможность доступа │
│ к Help. Определите контекстно- │
│ чувствительные добавочные блоки. │
└────────────────────────┬────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ Напишите и отредактируйте текстовые файлы. │
│ Введите управляющие коды для переходов и │
│ определений. Определите контекстные строки, │
│ заголовки, последовательные номера, │
│ ключевые слова и признаки построения. │
└────────────────────────┬────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ Перенесите файлы на ПВМ │
│ (если необходимо) │
└────────────────────────┬────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ Создайте Help файл проекта. │
│ Установите соответствие контекстно- │
│ чувствительных тем с контекстными номерами. │
│ Прогоните программу Build. │
└────────────────────────┬────────────────────────┘
│
┌────────────────────────┴────────────────────────┐
│ Испытайте систему Help. │
│ Выполните отладку и повторное испытание. │
└─────────────────────────────────────────────────┘

Как Help предоставляется пользователю

Для пользователя система Help представляется частью прог-
раммы, которая создается из текста и графических изображений,
выводимых в окне Help впереди программы.
На рисунке 1.2 показано окно Help, которое появляется на
экране когда пользователь запрашивает подсказку при копирова-
нии текста в Helpex.
Рисунок 1.2 Окно подсказки Helpex
╔═[■]════════════════════════════════════════════════[°][∙]═╗
║ Help Example ║
║───────────────────────────────────────────────────────────║
║ File Edit Help ║
║───────────────────────────────────────────────────────────║
║ ║
║ ║
║ ╔═[■]═════════════════════════════[°][∙]═╗ ║
║ ║ Help Example Help - helpex.hlp ° ║
║ ║────────────────────────────────────────▒ ║
║ ║ File Edit Bookmark Help ▒ ║
║ ║────────────────────────────────────────▒ ║
║ ║ Index Back Browse Browse Search ▒ ║
║ ║────────────────────────────────────────▒ ║
║ ║Copying Text ■ ║
║ ║ ▒ ║
║ ║Это объясняет как копировать текст в и ▒ ║
║ ║из clipboard. ▒ ║
║ ║(Эта тема связывается с ключевыми слова-▒ ║
║ ║ми "копировать" и "clipboard".) ▒ ║
║ ║ ▒ ║
║ ║ ∙ ║
║ ╚─┘ ║
║ ║
║ ║
╚══════════════════════════════════════════════════════════─┘
Окно Help выводит на экран один пример темы Help, частич-
ное описание того, как выполнить одну задачу. На рисунке 1.2
первое предложение включает определение слова "clipboard" (бу-
фер вырезанного изображения). Посредством нажатия кнопки мышки
в тот момент, когда курсор находится на слове (выделенном
пунктирной линией), пользователь может прочитать определение в
накладываемом окне, которое остается на экране до тех пор, по-
ка нажата кнопка мышки.
Перекрестные ссылки на соответствующие темы называются
операциями перехода.Нажав на кнопку мышки, чтобы выбрать тер-
мин перехода для соответствующей темы (отмеченной пунктирной
линией),пользователь изменяет содержание окна Help на описание
новой темы или команды. Рисунок 1.2 включает просмотр опреде-
ления "clipboard".

Как Help представляется разработчику текста Help

Для разработчика текста система Help является группой те-
матических файлов, которые представляют собой текстовые файлы,
включающие особые коды. На рисунке 1.3 показан исходный текст,
который соответствует теме, показанной на рисунке 1.2.
Рисунок 1.3 Тематический файл
╔═[■]════════════════════════════════════════════════[°][∙]═╗
║ Microsoft Word - \HELP\HELPEX.RTF ║
║───────────────────────────────────────────────────────────║
║File Edit Help View Insert Format Macro Window Help║
║───────────────────────────────────────────────────────────║
║ Font: Ptr: ║
║───────────────────────────────────────────────────────────║
║ Copying Text ║
║ ║
║ Это объясняет как копировать текст в и из clipboard. ║
║ (Эта тема связывается с ключевыми словами "копировать" и║
║ "clipboard".) ║
║───────────────────────────────────────────────────────────║
║ Deleting Text ║
║ ║
║ Это объясняет как удалить текст.(Эта тема связывается с ║
║ с ключевыми словами "копировать" и "clipboard".) ║
║───────────────────────────────────────────────────────────║
║ Exiting ║
║ ║
║ Это объясняет как выйти из HelpEx. ║
║ ║
║ ║
╚══════════════════════════════════════════════════════════─┘
Для того, чтобы раскрыть эту тему, разработчик текста
Help описывает задачу, форматирует текст и вставляет коды,
использующие зачеркнутый и подчеркнутый текст и подстрочные
примечания. Вместо зачеркнутого текста разработчик может
использовать двойное подчеркивание, если текстовый процессор
не выполняет форматирование зачеркнутого текста. Подстрочные
примечания в тексте содержат информацию о редактировании, не-
обходимую для компилятора Help. В главе 2 "Планирование систе-
мы Help" обсуждаются проблемы форматирования.В главе 3 "Созда-
ние Help тематических файлов" описывается то, как создаются
темы и вводятся особые коды, которые использует система Help.

Как Help представляется программисту Help

Для программиста Windows Help автономной программой
Windows, которую пользователь может прогонять подобно любой
другой программе. Ваша программа может вызвать функцию
WinHelp для запроса Windows о выполнении программы Help и оп-
ределить какую тему вывести на дисплей в окно Help.
Смотрите главу 4 "Построение файла Help",где дается более
подробная информация о программном интерфейсе Help программы.

Резюме

Система Help создается из тем, связанных через гипер-
текст. Темы и связи появляются на экране для пользователя в
другом виде, чем для разработчика текста в тематическом файле.
Для программиста Help является автономной программой.
Для получения дополнительной информации относительно
соответствующих тем, смотрите следующие главы:
Тема Ссылка
──────────────────── ─────────────────────────────────
Кодируемые в Help Глава 3 "Создание Help
темы тематических файлов"
Компилирование файлов Глава 4 "Построение файла Help"
Help






ГЛАВА 2

ПЛАНИРОВАНИЕ СИСТЕМЫ HELP

Первейшей задачей для разработчика текста Help является
разработка плана для создания системы. В данной главе обсужда-
ется планирование системы Help для особой программы.
В данную главу входят следующие темы:
- Разработка плана
- Разработка структуры тематического файла
- Конструирование визуального представления тем Help

Разработка плана

До того как приступить к написанию тем Help, используя
собранную Вами информацию, Вам и другим членам группы разра-
ботки Help, необходимо разработать план, учитывающий следующее:
- Категорию пользователей Вашей программы
- Содержание тем Help
- Структура тем
- Использование контекстно-чувствительных тем
Вы можете пожелать представить Ваш план в документах
конструирования, которые включают схему информации Help, диаг-
рамму структуры тем и примеры различных видов тем, которые
должна включать Ваша система.Запомните, что кон-
текстно-чувствительная Help требует дополнительного времени
разработки, особенно для разработчика программы.

Определение категории пользователей

Категория пользователей, для которой создается данная
Help система, определяет какой вид информации будет доступен в
Вашей системе и как Вы можете представить информацию.
Пользователи Help системы могут классифицироваться следу-
ющим образом:
Пользователь Данные
───────────────────────────────────────────────────────────
Начинающие Полностью незнакомые с работой на ЭВМ
программисты
Незнакомый с Некоторое знание ЭВМ,однако незнакомый
программой с Вашим видом программы.Например, если
Вы обеспечиваете Help для программы
электронной таблицы, то такой пользо-
ватель может быть знаком только с па-
кетом подготовки текстов.
Ознакомленный Хорошо осведомленный о Вашем виде
с программой программы.
на среднем уровне
Специалист Имеющий опыт работы с Вашим типом
программы.
───────────────────────────────────────────────────────────
Запомните, что каждый пользователь может иметь различные
уровни знаний. Например, специалист в области систем подготов-
ки текстов может не иметь опыта в использовании электронных
таблиц.

Планирование содержания системы Help

Вы должны разработать темы, которые весьма многочисленны
и весьма специфичны для того, чтобы обеспечить пользователей
необходимой помощью.
Начинающие пользователи нуждаются в помощи при изучении
задач и большинства определений терминов. Более опытные поль-
зователи иногда обращаются к помощи для разъяснения процедуры
или термина, однако наиболее часто для восстановления в памяти
команд и функций. Специалист обращается к помощи только в том
случае, когда ему требуется ознакомление с синтаксисом команд
и функций, эквивалентами клавиатуры и клавишами быстрого выбо-
ра.
Не существует правил для определения всего содержания Ва-
шей системы Help. Если Вы обеспечиваете Help для пользователей
всех типов, то Вы должны документировать команды, процедуры,
определения, особенности, функции и другие соответствующие
аспекты Вашей программы. Если Вы обеспечиваете помощь только
для специалистов, то Вы можете не включать темы, которые
описывают процедуры. Учитывайте категорию пользователей при
решении того, какие темы необходимо включить в Help. Помните,
что является важным решение о выполнении контекстно-чувстви-
тельной Help. Контекстно-чувствительная Help требует тесного
рабочего взаимодействия между автором Help и разработчиком
программы и, поэтому, будет увеличиваться время разработки,
необходимое для создания хорошо работающей системы Help.

Планирование структуры тем Help

Большинство систем Help имеют иерархическую структуру
тем. В верхней части иерархии находится индекс или таблица со-
держаний, или то и другое. Индекс и таблица содержаний пере-
числяет индивидуальные темы или категории тем, которые доступ-
ны для пользователя.
Сами темы могут связываться по иерархии. Каждый успешный
шаг дает возможность пользователю спуститься на один уровень
иерархии Help системы до тех пор, пока пользователь не достиг-
нет тематической информации. Иерархическое соотношение тем
Help частично определяет как пользователь проходит по системе
Help. На рисунке 2.1 показана возможная иерархия:
Рисунок 2.1 Пример иерархии Help
┌───────────┐
│Индекс Help│
└─────┬─────┘
│
┌───────────┬────────┴────┬────────────┬──────────┐
┌────┴────┐ ┌───┴───┐ ┌──────┴────┐ ┌─────┴────┐ ┌──┴──┐
│ Команды │┌─┤Словарь│ │Как выбрать│ │Клавиатура│ │Мышка│
└────┬────┘│ └───────┘ └──────┬────┘ └──────────┘ └─────┘
│ │ │
┌────┴────┐│ ┌───────┴────┐
┌─┤ Индекс ││ ┌──────┐┌─┤ Как выбрать│
│ │ команды │├>┤Тема ││ │ индекс │
│ └─────────┘│ └──────┘│ └────────────┘
│ ┌────────┐ │ ┌──────┐│ ┌─────────┐
├>┤ Тема │ ├>┤Тема │├>┤ Тема │
│ └────────┘ │ └──────┘│ └─────────┘
│ ┌────────┐ │ ┌──────┐│ ┌─────────┐
├>┤ Тема │ ├>┤Тема │├>┤ Тема │
│ └────────┘ │ └──────┘│ └─────────┘
│ ┌───────┐ │ ┌──────┐│ ┌─────────┐
├─>┤Тема │ └>┤ │└>┤ │
│ └───────┘ └──────┘ └─────────┘
│ ┌───────┐
└─>┤ │
└───┼───┘
│
└── Продолжение тем

Helpex содержит индекс, который перечисляет несколько ка-
тегорий тем. Каждая категория включает вторичный индекс, кото-
рый перечисляет темы в данной категории и сами темы.
Перемещаясь о индекса к теме, пользователь проходит от
общего к частному.
Иерархическая структура обеспечивает пользователя точкой
ссылки внутри Help. Пользователи не ограничиваются в перемеще-
нии вверх и вниз по иерархии. Они могут переходить от одной
темы к другой, перемещаясь через категории тем. Результат пе-
реходов состоит в наблюдении иерархических отношений. Напри-
мер, программа Windows Help содержит свойство поиска, которое
позволяет пользователю ввести ключевое слово в диалоговое ок-
но и искать темы, связанные с этим ключевым словом. Затем
программа Help выводит список заголовков, из которого можно
выбирать для получения доступа к информации, связанной с клю-
чевым словом.
Так как пользователи часто знают для какого свойства бу-
дут использовать Help, то они, обычно, могут обнаружить, что
они желают более быстрого использования свойств поиска, чем
при перемещении через иерархическую структуру. Для получения
более подробной информации о свойствах поиска обращайтесь к
разделу в главе 3 "Присвоение ключевых слов".
Кроме того, чтобы организовать темы иерархически, можно
организовать их в логической последовательности, которая под-
ходит Вашей категории пользователей. Логическая последователь-
ность или последовательность окон просмотра позволяет пользо-
вателю выбрать кнопку Browse для перехода от темы к теме.
Последовательности окон просмотра особенно важны для пользова-
телей, которым нравится читать несколько тем сразу, например,
темы, описывающие команды меню File. Более подробная информа-
ция о последовательности окон просмотра находится в главе 3
"Создание Help тематических файлов".
Какую бы структуру Вы не решили использовать, постарай-
тесь минимизировать количество списков, которые пользователь
должен просмотреть для того, чтобы получить информацию. Кроме
того, избегайте заставлять пользователя перемещаться через
множество уровней, чтобы достигнуть нужной темы. Для боль-
шинства функций Help систем вполне достаточно два или три
уровня.

Выведение на дисплей контекстно-чувствительных
тем Help

Windows Help поддерживает контекстно-чувствительную Help.
Написанная с учетом разработки программы, контекстно-чувстви-
тельная Help позволяет пользователю нажать F1 в открытом меню,
чтобы получить помощь с выбранным элементом меню. Альтернатив-
но пользователь может нажать Shift-F1, а затем нажать на кноп-
ку мышки, чтобы выбрать часть экрана или команду для получения
помощи по такому элементу.
Например, если пользователь нажимает Shift-F1, затем на-
жимает на кнопку мышки, чтобы выбрать пиктограмму увеличения,
когда использует пример программы Helpex, система Help выводит
информацию, показанную на рисунке 2.2:
Рисунок 2.2 Пример Help темы пиктограммы увеличения
╔═[■]════════════════════════════════════════════════[°][∙]═╗
║ Help Example ║
║───────────────────────────────────────────────────────────║
║ File Edit Help ║
║───────────────────────────────────────────────────────────║
║ ║
║ ║
║ ╔═[■]═════════════════════════════[°][∙]═╗ ║
║ ║ Help - helpex.hlp ║ ║
║ ║────────────────────────────────────────▒ ║
║ ║ File Edit Bookmark Help ▒ ║
║ ║────────────────────────────────────────▒ ║
║ ║ Index Back Browse Browse Search ▒ ║
║ ║────────────────────────────────────────▒ ║
║ ║Maximize Icon ■ ║
║ ║ ▒ ║
║ ║Для увеличения окна до его максимального▒ ║
║ ║размера: ▒ ║
║ ║ 1. Выберите окно, которое Вы хотите ▒ ║
║ ║ увеличить. ▒ ║
║ ║ 2. Нажмите и отпустите кнопку мышки ▒ ║
║ ║ для выбора пиктограммы увеличения.▒ ║
║ ║ ∙ ║
║ ╚─┘ ║
║ ║
║ ║
╚══════════════════════════════════════════════════════════─┘
Разработка контекстно-чувствительной Help требует коорди-
нации между разработчиком текста Help и разработчиком програм-
мы так, чтобы Help и программа передавали точную информацию
друг другу.
Для планирования контекстно-чувствительной Help автор
Help и разработчик программы должны согласовать список номеров
контекста. Контекстные номера - это произвольные номера, кото-
рые соответствуют каждой команде меню или части экрана в прог-
рамме и они используются для создания связей с соответствующи-
ми темами Help. Затем вы можете ввести эти номера вместе с их
соответствующими контекстно-строковыми идентификаторами в Help
файл проекта, который Help Compiler использует для создания
Help файла ресурсов. Раздел в главе 4 "Создание Help файла
проекта" дает более подробную информацию о том, как создать
Help файл проекта.
Контекстные номера, определенные в Help файле проекта
должны соответствовать контекстным номерам, которые программа
посылает во время выполнения для активизации определенной те-
мы. Смотрите раздел в главе 4 "Разработка программы для
обеспечения доступа к Help" для получения более подробной ин-
формации по назначению контекстных номеров.
Если Вы неточно определили контекстные номера для тем, то
Help Compiler генерирует значения, определенные по умолчанию
посредством преобразования строк контекста тем в контекстные
номера. Смотрите раздел в главе 4 "Отображение кон-
текстно-чувствительных тем: раздел отображения" для получения
более подробной информации о контекстно-чувствительной Help и
контекстных строках.
Для управления контекстными номерами и файловой информа-
ции, у Вас может возникнуть необходимость разработать програм-
му формирования следа в Help для перечисления контекстных но-
меров для ваших контекстно-чувствительных тем. Информация об
использовании программы формирования следа приведена в разделе
главы 3 "Разработка Help программы формирования следа".

Определение структуры тематического файла

Help структура файла остается в основном одинаковой для
всех программ, даже если отличаются контекст и количество те-
матических файлов.Тематические файлы сегментируются на различ-
ные темы посредством разрыва страниц. Когда Вы формируете
систему Help, компилятор использует эти тематические файлы для
создания информации, выводимой на экран для пользователя в ок-
не Help программы.
На рисунке 2.3 показана эта основная файловая структура.
Рисунок 2.3 Основная файловая структура системы Help

Help файлы, которые должны быть переведены
для операции создания
│
┌──────────────┬─────┴──────┬─┬─┬─────────────┐
┌────┴─────┐ ┌────┴─────┐ │ │ │ ┌─────┴────┐
│Файл слов │ │Файл слов │ Большое │Файл слов │
│ │ │ │ количество │ │
│Страница 1│ │Страница 1│ файлов │Страница 1│
├──────────┤ ├──────────┤ слов ├──────────┤
│ │ │ ... │ │ │
│ ... │ ├──────────┤ │ ... │
│ │ │Страница n│ │ │
├──────────┤ └──────────┘ │ │
│Страница n│ ├──────────┤
└──────────┘ │Страница n│
└──────────┘

Выбор файловой структуры для Вашей программы

При выборе файловой структуры для Вашей Help системы при-
мите во внимание сферу действия и содержание системы Help, ко-
торые Вы собираетесь использовать. Например, Вы могли бы по-
местить все темы Help в один большой тематический файл. Или Вы
могли бы поместить каждую тему Help в отдельный файл. Ни одна
из этих файловых структур не является приемлемой. Громадный
единичный файл или слишком большое количество индивидуальных
файлов могут вызвать трудности во время создания Help файла
ресурсов.
Количество тем связывается с количеством свойств, охваты-
ваемых системой Help. Следовательно, Вы не можете сделать
больших изменений в одном, не сделав изменений в другом. Нап-
ример, если к Help добавляется ряд дополнительных свойств
программных продуктов, то тогда должны создаваться дополни-
тельные темы для приспособления новой информации.
На рисунке 2.4 показана структура возможной системы Help.
количество тем и тематических файлов ограничивается для упро-
щения диаграммы и более четкого показа концепции связывания
тем вместе благодаря переходам, показанном на рисунке стрелоч-
ками. Рисунок не предназначен для показа количества файлов,
которые могут включаться в Help файловую систему. Кроме того,
на рисунке не показано как организуются тематические файлы с
использованием свойства просмотра.
Рисунок 2.4 Help файловая структура, показывающая
гипертекстовые переходы

ТЕМАТИЧЕСКИЙ ФАЙЛ ТЕМАТИЧЕСКИЙ ФАЙЛ
(индекс темы) (предметы тем)
┌─────────────────┐ ┌─────────────────┐
│Элемент индекса 1├─────>┤Элемент индекса 1│
│Элемент индекса 2├────┐ │Предмет 1 ─────┼─────────┐
│Элемент индекса 3├──┐ │ │Предмет 2 ─────┼──────┐ │
│ │ │ │ │Предмет 3 ─────┼────┐ │ │
│END-OF-FILE │ │ │ │Предмет 4 ─────┼──┐ │ │ │
└─────────────────┘ │ │ │ │ │ │ │ │
│ │ │PAGE BREAK │ │ │ │ │
│ │ ├─────────────────┤ │ │ │ │
│ └>┤Элемент индекса 2│ │ │ │ │
│ │Предмет 5 │ │ │ │ │
│ │Предмет 6 │ │ │ │ │
│ │Предмет 7 │ │ │ │ │
│ │ │ │ │ │ │
│ │PAGE BREAK │ │ │ │ │
│ ├─────────────────┤ │ │ │ │
└──>┤Элемент индекса 3│ │ │ │ │
│Предмет 8 │ │ │ │ │
│Предмет 9 │ │ │ │ │
│Предмет 10 │ │ │ │ │
│Предмет 11 │ │ │ │ │
│Предмет 12 │ │ │ │ │
│Предмет 13 │ │ │ │ │
│ │ │ │ │ │
│END-OF-FILE │ │ │ │ │
└─────────────────┘ │ │ │ │
┌─────────────────────────────────┘ │ │ │
│ ┌──────────────────┘ │ │
│ │ ┌───┘ │
│ │ │ ┌───┘
ТЕМАТИЧЕСКИЙ │ ТЕМАТИЧЕСКИЙ │ ТЕМАТИЧЕСКИЙ │ │ ТЕМАТИЧЕСКИЙ
ФАЙЛ (темы Help)│ФАЙЛ (темы Help)│ФАЙЛ (темы Help)│ │ФАЙЛ (темы Help)
┌───────────┐ │ ┌───────────┐ │ ┌───────────┐ │ │┌───────────┐
┌┤Тема 1 │ │ >Untitled Topic> и Browse errors.out
Намек: Используйте клавишу акселератора DOS CONTROL+PRINT
SCREEN перед тем, как начнете Вашу компиляцию для эхоошибок,
которые появляются на экране для Вашего принтера. Наберите
снова CONTROL+PRINT SCREEN для остановки посылки информации на
принтер.

Определение тем построения: Опция Build

Если Вы включили теги построения в Ваши тематические фай-
лы, используйте BUILD опцию для определения, какие темы услов-
но включаются в построение. Если Ваши тематические файлы не
имеют тегов построения, то опустите опцию BUILD из [Options]
сегмента.
Примечание. Все теги построения должны перечисляться в
[BuildTags] сегменте файла проекта, независимо от того, объяв-
ляет или нет данная условная компиляция теги.
Более подробную информацию о присвоении тегов построения
темам в Help тематических файлах смотрите в главе 3 "Создание
Help тематических фалов".
Строка опции BUILD использует следующий синтаксис:
BUILD = expression (выражение)
Выражения BUILD не могут превышать в длину 255 символов и
должны вводиться только в одну строку. BUILD выражения исполь-
зуют булеву логику для определения какие темы в пределах опре-
деленных Help тематических файлов компилятора будут включаться
в построение. Компилятор оценивает все выражения построения
слева направо. Обозначениями языка (перечисленные в порядке
старшинства от наивысших к самым низшим) являются:
Обозначение Описание
───────────────────────────────────────────────────────────
Тег построения
() Круглые скобки
~ Оператор отрицания
& Оператор И
│ Оператор ИЛИ
───────────────────────────────────────────────────────────
Например, если Вы закодировали теги построения, названные
WINENV,APP1 и TEST_BUILD в Ваших тематических файлах, то Вы
могли бы включить одно из следующих выражений построения в
сегмент [Options]:
Выражение построения Построенные темы
───────────────────────────────────────────────────────────
BUILD = WINENV Только темы, которые имеют тег WINENV
BUILD = WINENV Темы, которые имеют как WINENV, так и
&APP1 APP1 теги
BUILD = WINENV │ Темы, которые имеют либо WINENV тег,
APP1 либо APP1 тег
BUILD = (WINENV │ Темы, которые имеют либо WINENV, либо
APP1) & TESTBUILD APP1 теги и которые также имеют
TESTBUILD тег
BUILD =~APP1 Темы, которые не имеют APP1 тег
───────────────────────────────────────────────────────────

Определение корневого справочника: Опция ROOT

Используйте ROOT опцию для обозначения корневого справоч-
ника Help проекта. Компилятор ищет файлы в определенном корне-
вом справочнике.
ROOT опция использует следующий синтаксис:
ROOT = partname (имя пути)
Например, следующая корневая опция определяет, что корне-
вым справочником является \BUILD\TEST на D дисководе:
[OPTIONS]
ROOT=D:\BUILD\TEST
ROOT опция позволяет Вам ссылаться на соответствующие пу-
ти доступа из корневого справочника Help проекта. Например,
следующая запись в сегменте [Files] относится к соответствую-
щему пути из корневого справочника:
TOPIC\FILE.RTF
Для ссылки на файл в фиксированной позиции, независимо от
корневого проекта Вы должны задавать полностью квалифицирован-
ный или "абсолютный" путь, включая букву драйвера, если необ-
ходимо, как в следующей строке:
D:\HELPTEST\TESTFILE.RTF
Если Вы не включаете ROOT опцию в Ваш Help файл проекта,
то все пути являются соответствующими для текущего DOS спра-
вочника.

Спецификация индекса: Index опция

Используйте INDEX опцию для идентификации контекстной
строки Help индекса. Так как INDEX кнопка дает пользователю
доступ к индексу из любого места в Help системе, то Вы, веро-
ятно, не захотите, чтобы автор переходил к индексу. Пользова-
тели имеют доступ этому основному индексу или из Help меню
программы, или посредством выбора INDEX кнопки из Help окна.
Присваивание контекстной строки в индексной теме сегмента
[Options] позволяет компилятору узнать размещение главного ин-
декса Help тем для приложений Help файла. Если Вы не включаете
Index опцию в сегменте [Options], то компилятор предполагает,
что первая тема, которая встречается - это индекс.
Опция Index использует следующий синтаксис:
INDEX = context-string (контекстная строка)
Заданная контекстная строка должна соответствовать кон-
текстной строке, которую Вы присвоили Help индексной теме. В
следующем примере разработчик Help информирует компилятор о
том, что контекстная строка Help индекса является "главным ин-
дексом":
[OPTIONS]
INDEX=main_index
Более подробная информация о присваивании контекстных
строк приведена в разделе главы 3 "Присваивание контекстных
строк".

Присваивание заглавия в Help системе: Опция Title

Можно присвоить заглавие Вашей Help системе с помощью оп-
ции TITLE. Заглавие появляется в прямоугольнике заглавия Help
окна со словом "Help", добавляемом автоматически, за которым
следует DOS имя Help ресурсного файла.
Опция TITLE использует следующий синтаксис:
TITLE=Help-system-title-name (имя-заглавие-система-Help)
Заглавия ограничены 32 символами в длину. Если Вы не за-
даете заглавие, используя опцию TITLE, то только слово Help,
за которым следует имя файла системы Help, будет выводиться на
дисплей в прямоугольнике заглавия. Так как компилятор всегда
вставляет слово Help, то нужно это помнить, чтобы не дублиро-
вать это слово в заглавии.

Преобразование шрифтов: Опция Forcefont

Можно использовать опцию FORCEFONT для создания Help фай-
ла ресурсов, который состоит только из одного шрифта. Это по-
лезно, если Вы должны компилировать Help систему, используя
тематические файлы, которые включают шрифты, не поддерживаемы-
ми Вашими пользовательскими системами.
Опция FORCEFONT использует следующий синтаксис:
FORCEFONT = fontname (имя шрифта)
Параметр fontname - это любой шрифт системы Windows.
Windows поставляется со следующими шрифтами и размерами:
- Courier 10,12,15
- Гельветика 8,10,12,14,18,24
- Современный
- Прямой светлый шрифт
- Script
- Символьный 8,10,12,14,18,24
- Tms Rmn 8,10,12,14,18,24
Имена файлов должны записываться также, как они записаны
в Font диалоговом окне управляющей панели. Имена шрифтов не
превышают 20 символов в длину. Если Вы задаете шрифт, который
не распознается компилятором, то он генерирует сообщение об
ошибке и компиляция продолжается с использованием определенно-
го по умолчанию шрифта "Гельветика".
Примечание. Имя шрифта, используемое в опции FORCEFONT,
не может содержать пробелы. Следовательно, шрифт Tms Rmn не
может использоваться с помощью FORCEFONT.

Изменение размеров шрифта: Опция Mapfontsize

Размер шрифтов,заданный в тематических файлах,может отоб-
ражаться с различными размерами с помощью опции MAPFONTSIZE.В
этом случае Вы можете создать и отредактировать текст в разме-
ре,выбранном для более раннего просмотра в тематических фай-
лах,а затем компилятор будет определять их размер для действи-
тельного изображения в Help.Это может быть полезным,если есть
большая разница в размерах между Вашим создаваемым монитором и
предназначенным дисплейным монитором.
Опция MAPFONTSIZE использует следующий синтаксис:
MAPFONTSIZE = m[-n]:p
Параметр m - это размер исходного шрифта, а параметр p -
это размер желаемого шрифта для Help файла ресурсов. Размер
всех шрифтов в тематических файлах, которые имеют размер m,
изменяются на p. Необязательный параметр m позволяет Вам за-
дать диапазон, в котором может отображаться шрифт. Размер всех
шрифтов тематических файлов, попадающий между m и p включи-
тельно, меняется на размер p. Следующие примеры иллюстрируют
использование опции MAPFONTSIZE:
MAPFONTSIZE=12-24:16 ;делает размер шрифтов, имеющих раз-
мер от 12 до 24, равным 16.
MAPFONTSIZE=8:12 ;делает размер всех шрифтов, имеющих
размер 8, равным 12.
Заметим, что Вы можете отобразить только один размер
шрифта или диапазон с каждым MAPFONTSIZE предложением, исполь-
зуемом в сегменте Options. Если Вы используете более одного
MAPFONTSIZE в предложении, то исходный размер или диапазон
шрифта, заданные в последовательных предложениях, не могут пе-
рекрывать предыдущее отображение. Например, следующее отобра-
жение будут генерировать ошибку, когда компилятор встречает
второе предложение:
MAPFONTSIZE=12-24:16 MAPFONTSIZE=14:20
Так как второе отображение, показанное в первом примере,
содержит размер, уже отображенный в предыдущем предложении,
компилятор будет игнорировать эту строку. В файле проекта мож-
но задать максимум 5 диапазонов шрифтов.

Таблица ключевых слов: Опция Multikey

Опция MULTIKEY задает символ, который будет использо-
ваться для таблицы дополнительных ключевых слов.
Опция MULTIKEY будет использовать следующий синтаксис:
MULTIKEY = footnote-character (сноска-символ)
Параметр footnote-character является чувствительной к ре-
гистру буквой, которая должна использовать для сноски ключево-
го слова. Следующий пример иллюстрирует определение буквы L
для сноски в таблице ключевых слов:
MULTIKEY=L
Примечание. Вы должны быть уверенными в том, что Ваши
сноски в таблице ключевых слов ограничены одним регистром,
обычно используются строчные буквы. В предыдущем примере для
тем со сноской L ключевые слова будут введены в дополнительную
таблицу ключевых слов, а для тем, которым назначено l, это
происходить не будет.
Вы можете использовать любой алфавитно-цифровой символ
для любой таблицы ключевых слов, за исключением "К" и "к", ко-
торые резервируются для обычной таблицы ключевых слов Help.
существует абсолютный предел из 5 таблиц ключевых слов, вклю-
чая обычную таблицу. Однако , в зависимости от конфигурации и
структуры Help системы фактически имеет место практический
предел только из 2 или 3 таблиц. Если компилятор не может соз-
дать дополнительную таблицу, то при построении лишняя таблица
игнорируется.

Сжатие файла: Опция Compress

Вы можете использовать опцию COMPRESS , чтобы сократить
размер Help файла ресурсов, созданного компилятором.Объем сжа-
тия файла будет изменяться в зависимости от количества, разме-
ра и сложности тем, которые компилируются. В общем, чем больше
файлы Help, тем тем больше они могут быть сжаты.
Опция COMPRESS имеет следующий синтаксис:
COMPRESS = TRUE │ FALSE
Так как Help программа может загружать быстро сжатые фай-
лы, то очевидным преимуществом является создание и поставка
сжатых Help файлов с Вашей программой. Однако, компилирование
с включенным сжатием может увеличивать время компиляции из-за
дополнительного времени, необходимого для ассемблирования и
сортировки таблицы ключевых фраз. Таким образом, возможно Вы
захотите компилировать без сжатия на ранних стадиях разработки
проекта.
Опция COMPRESS заставляет компилятор сжимать систему,
посредством компилирования повторяющихся фраз, найденных внут-
ри исходного файла (файлов). Компилятор создает файл из табли-
цы фраз с расширением .PH, если такой файл еще не существует.
Если компилятор находит файл с .PH, он будет использовать этот
файл для текущей компиляции. Это используется для того, чтобы
ускорить сжатие, когда со времени последней компиляции, изме-
нилось немного текста. Удаление файла ключевых фраз перед каж-
дой компиляцией будет предотвращать использование компилятором
предыдущего файла. Максимальное сжатие будет получаться только
тогда, когда компилятор будет создавать новую таблицу фраз.

Определение новых контекстных строк: Сегмент Alias

Используйте сегмент [Alias] для присвоения одной или
нескольких контекстных строк одному и тому же тематическому
псевдоимени. Так как контекстные строки должны быть уникальны-
ми для для каждой темы и не могут использоваться для любой
другой темы в Help проекте, то сегмент [Alias] обеспечивает
способ удаления или комбинирования Help тем без записи Ваших
файлов,. Сегмент [Alias] является необязательным.
Например, если Вы создали тему, которая заменяет информа-
цию в трех других темах и Вы удаляете эти три темы, то Вам
придется искать в файлах неправильную перекрестную ссылку на
удаленные темы. Вы можете избежать этой проблемы посредством
использования сегмента [Alias] для присвоения имени новой темы
удаленным темам. Сегмент [Alias] может также использоваться,
когда Ваша прикладная программа имеет составные контекстные
идентификаторы, для которых Вы имеете только одну тему. Это
может быть регистр с контекстно-чувствительной Help.
Каждое выражение в сегменте [Alias] имеет следующий фор-
мат:
context_string=alias
В выражении псевдоимени параметр alias является альтерна-
тивной строкой или псевдоименем, а context_string параметр яв-
ляется контекстной строкой, идентифицирующей особую тему.
Строка псевдоимени имеет тот же самый формат и следует тем же
самым обычаям, что и тематическая контекстная строка. То есть,
она не чувствительна к регистру и может содержать алфавитные
символы A - Z, цифровые символы 0 - 9 и символы точки и под-
черкивания.
Следующий пример иллюстрирует сегмент [Alias]:
[Alias]
sm_key= key_shrtcuts
cc_key= key_shrtcuts
st_key= key_shrtcuts;комбинирует в сокращения клавиатуры
clskey=us_dlog_bxs
maakey=us_dlog_bxs;реализуется в использовании темы диа-
логового окна
chk_key=dlogprts
drp_key=dlogprts
lst_key=dlogprts
opt_key=dlogprts
tbx_key=dlogprts;комбинируется в части темы диалогового
окна
frmtxt=edittxt
wrptxt=edittxt
seltxt=edittxt;реализуется в редактировании темы текста
Примечание. Вы можете использовать псевдоимена в сегменте
[Map] Help файла проекта. Однако, если Вы так поступите, то
сегмент [Alias] должен предшествовать сегменту [Map].

Отображение контекстно-чувствительных тем: Сегмент Map

Если Ваша Help система обеспечивает контекстно-чувстви-
тельную Help, то используйте [Map] сегмент для ассоциации кон-
текстных строк или псевдоимен с контекстными номерами. Кон-
текстный номер соответствует значению родительской программы
при передаче Help программе для того, чтобы вывести на дисплей
определенную тему. Этот сегмент является необязательным.
При написании [Map] сегмента Вы можете сделать следующее:
- Используйте как десятичные , так и шестнадцатиричные
номера, отформатированные в стандартной С системе обозначений
для определения контекстных номеров.
- Присвойте не более, чем один контекстный номер для кон-
текстной строки или псевдоимени.
Присвоение одного и того же номера более, чем одной кон-
текстной строке будет генерировать ошибку компилятора.
- Разделите контекстные номера и контекстные строки
посредством произвольного количества пробелов, используя как
символы пробелов, так и символы табуляции.
Вы можете использовать С#include директиву для включения
других файлов в отображение. В дополнение к этому, сегмент Map
обеспечивает расширенный формат, который позволяет Вам не-
посредственно включать С файлы с расширением .H. Элементы,
использующие этот формат, должны начинаться с #define
и могут содержать комментарии в С формате, как в данном при-
мере:
#define context_string context_number /* комментарий*/
Следующий пример иллюстрирует несколько форматов, которые
Вы можете использовать в сегменте [Map]:
[Map]
1).
Edit_Window 0x0001
Control_Menu 0x0002
Maximize_Icon 0x0003
Minimize_Icon 0x0004
Split_Bar 0x0005
Scroll_Bar 0x0006
Title_Bar 0x0007
Window_Border 0x0008
2).
dcmb_scr 30;Document Control-menu Icon
dmxi_scr 31;Document Maximize Icon
dmni_scr 32;Document Minimize Icon
dri_scr 33;Document Restore Icon
dtb_scr 34;Document Title Bar
3).
#define vscroll 0x010A /* Линейка вертикальной прокрутки*/
#define hscroll 0x010E /* Линейка горизонтальной прокрутки*/
#define scrollthm 0x0111 /* Кнопка скролинга*/
#define upscroll 0x0112 /* Прокрутка вверх*/
#define dnscroll 0x0113 /* Прокрутка вниз*/
4).
#include

В примере:
1). Эти восемь записей дают шестнадцатиричные эквивален-
ты для номеров контекста.
2). Эти пять записей показывают десятичные контекстные
номера.
3). Эти пять записей показывают как Вы могли бы включить
темы, определенные в С include файл.
4). Эта запись показывает С#include директиву для некото-
рых основных тем.
Если контекстные номера используют #define директиву и
файл, содержащий #define предложения, включается как в код
программу, так и в Help файл, то тогда модификации, сделанные
в контекстных номерах разработчиками программы, будут автома-
тически отражаться в следующем Help построении.
Вы можете определить, перечисленные в [Map] сегменте, ли-
бо в Help теме, или в [Alias] сегменте. Компилятор генерирует
предупреждение, если контекстная строка, появляющаяся в [Map]
сегменте, не определяется в любом из тематических файлов или в
[Alias] сегменте.
Примечание. Если Вы используете псевдоимя, сегмент
[Alias] должен предшествовать [Map] сегменту в Help файле про-
екта.
Более подробную информацию о контекстно-чувствительной по-
мощи смотрите в разделе главы 2 "Выведение на дисплей кон-
текстно-чувствительных Help тем".

Включение растров по ссылке: Сегмент Bitmaps

Если Ваша Help система использует растры по ссылке, то
имена файлов каждого из растров должны перечисляться в
[Bitmaps] сегменте файла проекта. Следующий пример иллюстриру-
ет формат [Bitmaps] сегмента:
[Bitmaps]
DUMP01.BMP
DUMP02.BMP
DUMP03.BMP
c:\PROJECT\HELP\BITMAPS\DUMP04.BMP
Примечание. [Bitmaps] сегмент использует те же самые пра-
вила, как и [Files] сегмент для расположения растровых файлов.

Компилирование Help файлов

После того, как Вы создали Help файл проекта, Вы уже го-
товы создать Help файл, используя Help Compiler. Компилятор
генерирует бинарный Help файл ресурсов из тематических файлов,
перечисленных в Help файле проекта. Когда завершается процесс
построения, Ваша программа может иметь доступ к полученному
Help файлу ресурсов.
До инициирования операции построения для создания Help
файла, рассмотрите расположение следующих файлов:
- Help Compiler, HC.EXE. Компилятор должен быть в спра-
вочнике, из которого он может выполняться.Это может быть теку-
щий рабочий справочник на пути, установленном переменной среды
PATH или справочник, определенный полным именем пути, как по-
казано ниже:
С:\BIN\HC HELPEX.HPJ
- Help файл проекта, filename.HPJ. Файл проекта может
располагаться или в текущем справочнике, или определяться в
справочнике, определенном путем, как показано ниже:
C:\BIN\HC D:\MYPROJ\HELPEX.HPJ
- Тематические файлы, названные в Help файле проекта,
сохраняются как RTF. Тематические файлы могут располагаться в
текущем рабочем справочнике, подсправочнике текущего рабочего
справочника, определенного в [Files] сегменте, или его распо-
ложение определяется в ROOT опции.
- Файлы, включенные с помощью #include директивы в Help
файл проекта. Так как #include директива может принимать имена
пути, то тогда любое количество мест будет работать для этих
файлов.
- Все растровые файлы, перечисленные по ссылке, в темати-
ческих файлах.
Вы также должны поместить любые файлы, названные в
#include директиве, на пути корневого справочника проекта или
определить их путь, используя ROOT опцию. Компилятор ищет
только справочники, определенные в Help файле проекта. Более
подробную информацию о ROOT опции Вы можете получить в разделе
"Определение корневого справочника: Опция ROOT".
Примечание. Если Вы используете оперативную память для
рабочих файлов (установленную с помощью DOS среды переменной
TMP) , то она должна быть достаточно большой для сохранения
откомпилированного Help файла ресурсов. Если Ваш Help файл
больше, чем размер доступной оперативной памяти, то компилятор
будет генерировать сообщение об ошибке и компиляция будет
прекращаться.

Использование Help компилятора

Для прогона Help Compiler используйте HC команду. Для HC
не существует опций. Все опции определяются в Help файле про-
екта.
HC команда использует следующий синтаксис:
HCfilename.HPJ
Когда прогоняется программа компилятора, то она выводит
на дисплей последовательные точки, указывая на ее развитие в
процессе. Сообщение о ошибках выводится на дисплей, когда
встречается условие каждой ошибки. Когда Help Compiler закан-
чивает компилирование, он пишет Help файл ресурсов с расшире-
нием .HLP в текущий справочник и возвращает DOS подсказку.
Help файл ресурсов, получаемый из построения, имеет то же са-
мое имя , что и Help файл проекта.
Ошибки компилятора и сообщения о статусе могут перенап-
равляться в файл, используя стандартный DOS синтаксис переад-
ресовки. Это вполне пригодно для растянутого построения, где
Вы не в состоянии контролировать весь процесс. Переадресован-
ный файл сохраняется, как текстовый файл6 который можно
просматривать с помощью любого ASCII редактора.

Разработка программы для доступа к Help

Группа разработчиков программы должна разрабатывать прог-
рамму так, чтобы пользователь мог иметь доступ к Windows Help
программе, так и к Вашему Help файлу. Help программа - это от-
дельная Windows программа и Ваша программа может запрашивать
Windows для прогона Help программы и определять тему, которую
Help должна показывать пользователю. Для пользователя Help по-
является как часть Вашей программы, однако она действует по-
добно любой другой Windows программе.

Вызов WinHelp из программы

Программа делает Help систему доступной пользователю
посредством вызова WinHelp функции.
WinHelp функция имеет следующий синтаксис:
BOOL WinHelp (hWnd,lpHelpFile,wCommand,dwData)
Напоминаем: С и Pascal примеры находятся на диске.
Параметр hWnd идентифицирует окно, запрашивающее
Help. Windows Help программа использует этот идентификатор,
чтобы следить за тем, какие программы запрашивают Help.
Параметр lpHelpFile задает имя (с необязательным путем к
справочнику) файла Help, содержащего требуемую тему.
Параметр mCommand задает тип поиска, который Windows Help
программа использует для определения положения заданной темы,
или задает, что программе больше не нужна система Help. Этому
параметру можно присвоить одно из следующих значений:
Значение Что делает
───────────────────────────────────────────────────────────
HELP_CONTEXT Выводит на дисплей Help для определенной
темы, идентифицируемой номером контекста.
HELP_HELPPONHELP Выводит на дисплей Using Help тему индекса
HELP_INDEX Выводит на дисплей главную Help тему ин-
декса.
HELP_KEY Выводит на дисплей Help для темы, заданной
ключевым словом.
HELP_MULTIKEY Выводит на дисплей Help для темы, заданной
ключевым словом в альтернативной таблице
ключевых слов.
HELP_QUIT Информирует Help программу о том, что Help
больше не нужна. Если другие программы не
запрашивают Help, то Windows закрывает Help
программу.
HELP_SETINDEX Выводит на дисплей назначенную Help тему
индекса.
───────────────────────────────────────────────────────────
Параметр dwData задает тему, для которой программа запра-
шивает Help. Формат dwData зависит от значения mCommand, пере-
даваемого, когда Ваша программа вызывает WinHelp. Следующий
список описывает формат wdData для каждого значения mCommand.
Значение mCommand dwData формат
───────────────────────────────────────────────────────────
HELP_CONTEXT Длинное целое без знака, содержащее номер
контекста для темы. Вместо использования
HELP_INDEX, HELP_CONTEXT можно использовать
можно использовать значение -1.
HELP_HELPPONHELP Игнорируется.
HELP_INDEX Игнорируется.
HELP_KEY Длинный указатель на строку, которая со-
держит ключевое слово для требуемой темы.
HELP_MULTIKEY Длинный указатель на MULTIKEYHELP струк-
туру, как определено в WINDOWS.H. Эта
структура определяет символ сноски таблицы
и ключевое слово.
HELP_QUIT Игнорируется.
HELP_SETINDEX Длинное целое без знака, содержащее номер
контекста для темы.
───────────────────────────────────────────────────────────
Так как можно задать как номер контекста, так и ключевое
слово, то WinHelp поддерживает и контекстно-чувствительный и
тематический поиск Help файла.
Примечание. Чтобы убедиться, что правильный индекс оста-
ется установленным, программа должна вызвать WinHelp с
mCommand , равным HELP_SETINDEX (с dwData, задающим соот-
ветствующий идентификатор контекста), вслед за каждым вызовом
WinHelp с командой HELP_CONTEXT. HELP_INDEX никогда не должен
использоваться с HELP_SETINDEX.

Получение контекстно-чувствительной помощи

Контекстно-чувствительная Help должна быть доступной,
когда пользователь желает узнать о назначении определенного
окна или управления. Например, пользователь может вытолкнуть
File меню, выбрать Open команду (посредством использования
клавиши Direction), а затем нажать F1 для получения Help для
команды.
Реализация определенных типов контекстно-чувствительной
помощи требует более совершенной техники программирования.
Helpex пример программы иллюстрирует использование двух техно-
логий. Эти технологии описываются в следующих разделах.

Shift+F1 поддержка

Для реализации Shift+F1 режима, Helpex отвечает на клави-
шу акселератора Shift+F1, посредством вызова Set-Cursor для
изменения формы курсора на стрелочный указатель, дополняемый
маркером вопроса.
case WM_KEYDOWN:
if WParam == VK_F1 {

/*Если используется Shift-F1, то включается режим помо-
щи и устанавливается курсор помощи*/

if GetKeyState(VK_Shift)) {
bHelp = True;
SetCursor(hHelpCursor);
return (DefWindowProc(hWnd, message, WParam, LParam));
}

/* Если используется F1 без клавиши Shift, то тогда
вызывается тема главного индекса помощи */
else {
WinHelp(hWnd, szHelpFileName, Help_Index, 0L);
}
}

else if (wParam == vk_Escape && bHelp) {

/* Клавиша Escape во время режима помощи: отключает
режим помощи */
bHelp = False;
SetCursor(hCursor)GetClassWord(hWnd,GCW_HCursor));
}

break;

Ниже показано как Вы должны это делать в Turbo Pascal:

WM_KEYDOWN:
if WParam = vk_F1 then
{ Если используется Shift-F1, то включается режим помо-
щи и устанавливается курсор помощи }
if GetKeyState(VK_Shift) < 0 then
begin
Help := True;
SetCursor(HelpCursor);
MainWndProc := DefWindowProc(Wnd, Message, WParam, LParam);
end
{ Если используется F1 без клавиши Shift, то тогда
вызывается тема главного индекса помощи }
else
WinHelp(Wnd, HelpFileName, Help_Index, 0)
{ Клавиша Escape во время режима помощи: отключает
режим помощи }
else if (WParam = vk_Escape) and Help then
begin
Help := False;
SetCursor(hCursor(GetClassWord(Wnd, GCW_HCursor)));
end;

Пока пользователь находиться в режиме Help (то есть до
тех пор, пока он нажимает клавишу на мышке или нажимает кла-
вишу Escape), Helpex отвечает на WM_SETCURSOR сообщения
посредством переопределения курсора на комбинацию стрелочки и
маркера вопроса.
case WM_SETCURSOR:
/* В режиме помощи необходимо изменить курсор в ответ на
каждое WM_SETCURSOR сообщение. В противном случае,по
умолчанию, Windows будет изменять курсор на курсор
класса окна. */

if (bHelp) {
SetCursor(hHelpCursor);
break;
}
return (DefWindowProc(hWnd, message, wParam, lParam));
break;

case WM_INITMENU:
if (bHelp) {
SetCursor(hHelpCursor);
}
return(TRUE);

Ниже представлено как это Вы должны делать в Turbo Pascal:

WM_SETCURSOR:
{ В режиме помощи необходимо изменить курсор в ответ на
каждое WM_SETCURSOR сообщение. В противном случае,по
умолчанию, Windows будет изменять курсор на курсор
класса окна. }

if Help then
SetCursor(HelpCursor)
else
MainWndProc := DefWindowProc(Wnd, Message, WParam,
LParam);
exit;
end;

Когда пользователь находится в Shift+F1 режиме Help и на-
жимает клавишу мышки, Helpex будет получать WM_NCLBUTTONDOWN
сообщение, если нажатие произошло не в области пользователь
окна программы. Благодаря исследованию значения wParam этого
сообщения, программа может определить какой идентификатор кон-
текста послать в WinHelp.
case WM_NCLBUTTONDOWN:
/*Если мы находимся в режиме помощи (Shift+F1), то тогда
выводится на дисплей контекстно-чувствительная помощь
для непользовательской среды. */

if (bHelp) {
dwHelpContextId =
(wParam == HtCaption)?(DWORD)HelpId_Title_Bar:
(wParam == HTSIZE)? (DWORD)HelpId_Size_Box:
(wParam == HTREDUCE)?
(DWORD)HELPID_MINIMIZE_ICON
(wParam == HTZOOM)?(DWORD)HELPID_MAXIMIZE_ICON:
(wParam == HTSYSMENU)?(DWORD)HELPID_SYSTEM_MENU:
(wParam == HTBOTTOM)?
(DWORD)HELPID_SIZING_BORDER:
(wParam == HTBOTTOMLEFT)?
(DWORD)HELPID_SIZING_BORDER:
(wParam ==
HTBOTTOMRIGHT)?HELPID_SIZING_BORDER:
(mParam == HTTOP)?(DWORD)HELPID_SIZING_BORDER:
(mParam == HTLEFT)?(DWORD)HELPID_SIZING_BORDER:
(mParam == HTRIGHT)?(DWORD)HELPID_SIZING_BORDER:
(mParam ==
HTTOPLEFT)?(DWORD)HELPID_SIZING_BORDER:
(mParam == HTTOPRIGHT)?
(DWORD)HELPID_SIZING_BORDER:
(DWORD)0L

if (!((BOOL)dwHelpContextId))
return (DefWindowProc(hWnd, message, wParam,
lParam));
bHelp = False;
WinHelp(hWnd, szHelpFileName, Help_Context,
dwHelpContextId);
break;
}
return (DefWindowProc(hWnd, message, wParam,
lParam));

Ниже представлено как это Вы должны делать в Turbo Pascal:

WM_NCLBUTTONDOWN:
/*Если мы находимся в режиме помощи (Shift+F1), то тогда
выводится на дисплей контекстно-чувствительная помощь
для непользовательской среды. */

if Help then
begin
case WParam of
HtCaption: HelpContextId := HelpIdTitleBar;
HtReduce: HelpContextId := HelpIdMinimizeIcon;
HtZoom: HelpContextId := HelpIdMaximizeIcon;
HtSysMenu: HelpContextId := HelpIdSystemMenu;
HtBottom: HelpContextId := HelpIdSizingBorder;
HtBottomLeft: HelpContextId := HelpIdSizingBorder;
HtBottomRight: HelpContextId := HelpIdSizingBorder;
HtTop: HelpContextId := HelpIdSizingBorder;
HtLeft: HelpContextId := HelpIdSizingBorder;
HtRight: HelpContextId := HelpIdSizingBorder;
HtTopLeft: HelpContextId := HelpIdSizingBorder;
HtTopRight: HelpContextId := HelpIdSizingBorder;
else
HelpContextId := 0;
end;
if HelpContextId = 0 then
MainWndProc := DefWindowProc(Wnd, Message, WParam,
LParam)
else
begin
Help := False;
WinHelp(Wnd, HelpFileName, Help_Context,
HelpContextId);
end
end
else
MainWndProc := DefWindowProc(Wnd, Message, WParam,
LParam);
exit;
end;

F1 поддержка

Контекстно-чувствительная F1 поддержка для меню относи-
тельно проста для реализации в Вашей программе. Если меню от-
крыто и пользователь нажимает F1 в то время когда высвечива-
ется один из элементов меню, Windows посылает WM_ENTERIDLE
сообщение в программу для того, чтобы указать 6 что система
возвращается обратно в состояние незанятости после определения
того, что F1 не было правильным нажатием клавиши для выбора
элемента меню. Вы можете получить преимущество от того состоя-
ния незанятости, взглянув на состояние клавиатуры во время
WM_ENTERIDLE сообщения.
Ели нажата клавиша F1, то тогда вы сможете смоделировать
нажатие пользователем клавиши ENTER , посредством регистрации
WM_KEYDOWN сообщения, используя VK_RETURN. Вы действительно не
желаете, чтобы Ваша программа выполняла команды меню. То что
Вы должны сделать, так это установить флаг (bHelp=TRUE) так,
чтобы когда вы получили WM_COMMAND сообщение для элемента ме-
ню, Вы не выполняли команду. Вместо этого тема для элемента
меню выводится на дисплей посредством Windows Help.
Следующие кодовые примеры иллюстрируют F1 чувствитель-
ность для элементов меню:
case WM_ENTERIDLE:
if ((WParam == msgf_Menu) && (GetKeyState(VK_F1) &
0x8000)) {
bHelp = True;
PostMessage(hWnd, WM_KEYDOWN, VK_RETURN, 0L);
}
break;

case WM_COMMAND:
/* F1 только что нажата в меню или мы находимся в режиме
помощи (Shift+F1)? */

if (bHelp) {
dwHelpContextId =
(wParam == Idm_New)?(DWORD)HelpId_File_New:
(wParam == Idm_Open)?(DWORD)HelpId_File-Open:
(wParam == Idm_Save)?(DWORD)HelpId_File_Save:
(wParam == Idm_SaveAs)?
(DWORD)HelpId_File_Save_As:
(wParam == Idm_Print)?(DWORD)HelpId_File_Print:
(wParam == Idm_Exit)?(DWORD)HelpId_File_Exit:
(wParam == Idm_Undo)?(DWORD)HelpId_Edit_Undo:
(wParam == Idm_Cut)?(DWORD)HelpId_Edit_Cut:
(wParam == Idm_Clear)?(DWORD)HelpId_Edit_Clear:
(wParam == Idm_Copy)?(DWORD)HelpId_Edit_Copy:
(wParam == Idm_Paste)?(DWORD)HelpId_Edit_Paste:
(DWORD)0L;

if (!dwHelpContextId)
{MessageBox( hWnd, "Help not available for Help Menu
Item", "Help Example", Mb_Ok
return (DefWindowProc(hWnd, message, wParam, lParam));
}

bHelp = False;

WinHelp(hWnd, szHelpFileName, Help_Context,
HelpContextId);
break;
}

Ниже представлено как это Вы должны делать в Turbo Pascal:

WM_ENTERIDLE:
if ((WParam = msgf_Menu) and ((GetKeyState(VK_F1) and
$8000) 0)) then
begin
Help := True;
PostMessage(Wnd, WM_KEYDOWN, VK_RETURN, 0);
end;

WM_COMMAND:

{ F1 только что нажата в меню или мы находимся в режиме
помощи (Shift+F1)? }

if Help then
begin
case WParam of
IdmNew: HelpContextId := HelpIdFileNew;
IdmOpen: HelpContextId := HelpIdFileOpen;
IdmSave: HelpContextId := HelpIdFileSave;
IdmSaveAs: HelpContextId := HelpIdFileSaveAs;
IdmPrint: HelpContextId := HelpIdFilePrint;
IdmExit: HelpContextId := HelpIdFileExit;
IdmUndo: HelpContextId := HelpIdEditUndo;
IdmCut: HelpContextId := HelpIdEditCut;
IdmClear: HelpContextId := HelpIdEditClear;
IdmCopy: HelpContextId := HelpIdEditCopy;
IdmPaste: HelpContextId := HelpIdEditPaste;
else
HelpContextId := 0;
end;
if HelpContextId = 0 then
begin
MessageBox(Wnd, 'Help not available for Help Menu
Item', 'Help Example', Mb_Ok);
MainWndProc := DefWindowProc(Wnd, Message, WParam,
LParam);
exit;
end;
Help := False;
WinHelp(Wnd, HelpFileName, Help_Context,
HelpContextId);
end
Обнаружение F1 в диалоговых окнах несколько более затруд-
нено, чем в меню. Вы должны установить фильтр сообщения,
используя WH_MSGFILTER опцию функции SetWindowsHook. Ваша
функция фильтра сообщения реагирует на WH_KEYDOWN и WH_KEYUP
сообщения в VK_F1 , когда они посылаются в диалоговое окно,
как указывается MSGF_DIALOGBOX кодом. Посредством исследования
структуры сообщения, передаваемого в фильтр, Вы можете опреде-
лить контекст F1 помощи - это находится в диалоговом окне, и
определенную опцию или элемент. Вы не должны вызывать WinHelp
при обработке фильтруемого сообщения, а скорее регистрировать
сообщение, определенное программой, для Вашей программы, чтобы
вызвать WinHelp при первой доступной возможности.

Получение Help по элементу, перечисленному
в меню Help

Иногда пользователи могут пожелать получить информацию об
основной концепции в программе, а не об определенном управле-
нии или окне. В этих случаях программа должна обеспечить Help
определенной темой, которая идентифицируется ключевым словом,
а не идентификатором контекста.
Например, если Help файл для Вашей программы, содержит
тему, описывающую как используется клавиатура, Вы можете по-
местить элемент "Keyboard" ("Клавиатура") в Ваше меню Help.
Тогда, когда пользователь выбирает этот элемент, Ваша програм-
ма должна вызвать WinHelp и запросить эту тему:
case IDM_HELP_KEY_BOARD:
WinHelp (hWnd, lpHelpFile, HELP_KEY, (LPSTR)
"Keyboard");
break;

Доступ к дополнительной таблице ключевых слов

Ваша программа может иметь команды или термины, которые
соответствуют терминам в сходной, но отличающейся программе.
По данному ключевому слову программа может вызвать WinHelp и
найти темы, определенные в альтернативной таблице ключевых
слов. Эта Multikey функциональность доступна благодаря WinHelp
добавочному блоку с параметром mCommand, установленном на
HELP_MULTIKEY.
Вы определяете символ сноски для альтернативной таблицы
ключевых слов и ключевое слово или фразу через структуру
MULTIKEYHELP, которая передается в качестве параметра dwData
при вызове WinHelp. Эта структура определяется в WINDOW.H сле-
дующим образом:
typedef struct tag MULTIKEYHELP {
WORD mdSize;
BYTE mkKeyList;
BYTE szKeyPhrase[1];
} MULTIKEYHELP;

В следующей таблице перечисляются форматы полей структуры
MULTIKEYHELP:
Параметр Формат
───────────────────────────────────────────────────────────
mkSize Размер структуры, включающий ключевое слово
(или фразу) и соответствующую букву ключевой
таблицы.
mkKeyList Одиночный символ, которые определяет символ
сноски для разыскиваемой альтернативной таблицы
ключевых слов.
szKeyPhrase Ключевое слово или фраза, завершающаяся пустым
указателем, которые должны разыскиваться в аль-
тернативной таблице ключевых слов.
───────────────────────────────────────────────────────────
В следующем примере иллюстрируется поиск ключевого слова
для слова "frame" ("рамка") в альтернативной таблице ключевых
слов, обозначенном символом сноски "L":
MULTIKEYHELP mk;
char szKeyword[] = "frame";
mk.mkSize=sizeof(MULTIKEYHELP)+(WORD)lstrlen(szKeyword);
mk.mkKeylist="L";
mk.szKeyphrase=szKeyword;
WinHelp(hWnd,lpHelpfile,HELP_MULTIKEY,(LPSTR)&mk);

Отмена Help

Windows Help программа является общим ресурсом, который
доступен для всех Windows программ. В дополнение к этому, так
как это автономная программа, пользователь может выполнять ее
подобно любой другой программе. В результате этого Ваша прог-
рамма имеет ограниченный контроль над Help программой. Хотя
Ваша программа не может непосредственно закрыть Help окно
программы, Ваша программа может проинформировать Help прог-
рамму о том, что Help больше не требуется. До закрытия своего
главного окна Ваша программа должна вызвать WinHelp с исполь-
зованием mCommand параметра для установки HELP_QUIT, как пока-
зано в следующем примере, чтобы проинформировать Help програм-
му о том, что Ваша программа не будет нуждаться в ней опять.
case WM_DESTROY:
WinHelp (hWnd, lpHelpFile, HELP_QUIT, NULL);
Программа, которая вызывает WinHelp в некотором пункте во
время ее выполнения должна вызвать WinHelp c использованием
mCommand параметра для установки HELP_QUIT перед тем, как
программа выходит из WinMain (типично во время отработки
WM_DESTROY сообщения).
Если программа открывает более чем один Help файл, то
тогда она должна вызвать WinHelp для прекращения помощи для
каждого файла.
Если программа или DLL открыли Help файл, однако более не
желают, чтобы связанный пример Help средства (WINHELP.EXE)
оставался активным, то тогда программа или DLL должны вызвать
WinHelp с помощью mCommand параметра для установки HELP_QUIT,
чтобы уничтожить пример Help средства.
Ни при каких обстоятельствах программа или DLL не должны
заканчиваться без вызова WinHelp для любого из открытых Help
файлов. Help файл открывается, если любой другой WinHelp вы-
зов, сделанный ранее с использованием Help имени файла.
Windows Help программа не выходит до тех пор, пока все
окна, которые вызваны WinHelp не вызывают ее с использованием
mCommand для установки HELP_QUIT. Если программа не в состоя-
нии делать так, то тогда Help программа будет продолжать про-
гон после всех программ, которые проводят запрос о завершении
Help.
Резюме

В этой главе описывалось как создать Help файл проекта,
построить Help файл ресурса и создать программу для доступа к
Help. Более подробную информацию смотрите ниже:
Тема Ссылка
───────────────────────────────────────────────────────────
Планирование Help Средства: Глава 2 " Планирование Help
системы системы"
Написание Help Средства: Глава 3 "Создание Help тема-
тем тических файлов"
───────────────────────────────────────────────────────────












ГЛАВА 5

ПРИМЕРЫ HELP И СООБЩЕНИЯ КОМПИЛЯТОРА
ОБ ОШИБКАХ

В первой части этой главы содержатся несколько примеров
Help исходных файлов и их соответствующие темы, в том виде,
как они выводятся на дисплей в Help. Каждый пример показывает
тему (или часть темы) так, как она представляется разработчику
текста Help в системе подготовки текста, допускающей RTF и как
она представляется пользователю в Help окне. Вы можете исполь-
зовать эти примеры в качестве руководств при создании Ваших
собственных тематических файлов. Примеры должны помочь Вам в
предсказании того, как определенный тематический файл, создан-
ный в системе подготовки текста, будет представляться пользо-
вателю.
Во второй части этой главы содержится список сообщений об
ошибках Help Compiler . Каждое сообщение показано в том виде,
в котором оно появляется, когда компилятор встречается с ха-
рактерной ошибкой. Каждое сообщение сопровождает короткое
объяснение с целью помочь Вам в решении проблемы в Вашей Help
системе. Перечислению сообщений об ошибках предшествует корот-
кое описание поведения Help Compiler при сообщении об ошибке.
Понимание того, как компилятор сообщает и реагирует на ошибки,
поможет Вам отладить Ваши Help файлы.

Help тематические примеры

Рисунок 5.1 Слово для Windows темы
╔═[■]════════════════════════════════════════════════[°][∙]═╗
║ Microsoft Word - HELPEX.RTF ║
║───────────────────────────────────────────────────────────║
║File Edit Help View Insert Format Macro Window Help║
║───────────────────────────────────────────────────────────║
║ Edit Menu ║
║ Меню Edit включает команды, которые дают Вам возможность║
║ перемещать текст в и из буфера вырезанного изображения ║
║ для удаления предыдущей операции редактирования. ║
║ Для получения дополнительной информации, выберите имя ║
║ команды Edit меню. ║
║ ClearHELPID_EDIT_CLEARУдаляет текст без перемещения его ║
║ в clipboard. ║
║ CopyHELPID_EDIT_COPYКопирует текст в clipboard ║
║ DeleteHELPID_EDIT_CUTУдаляет текст и перемещает его в ║
║ clipboard. ║
║ PasteHELPID_EDIT_PASTEПеремещает текст из clipboard в ║
║ в окно редактирования. ║
║ UndoHELPID_EDIT_UNDOОтменяет предыдущую операцию. ║
║───────────────────────────────────────────────────────────║
║ # menu edit ║
║ $ Edit Menu ║
║ + commands:010 ║
║ kmenu,edit;edit;commands;clear;copy;cut;paste;undo ║
╚══════════════════════════════════════════════════════════─┘

Рисунок 5.2 Help тематический дисплей
╔═[■]════════════════════════════════════════════[°][∙]═╗
║ Help Example Help - helpex,hlp ║
║───────────────────────────────────────────────────────▒
║ File Edit Bookmark Help ▒
║───────────────────────────────────────────────────────▒
║ Index Back Browse Browse Search ▒
║───────────────────────────────────────────────────────▒
║Edit Menu ■
║Меню Edit включает команды,которые дают Вам возможность▒
║перемещать текст в и из clipboard для удаления предыду-▒
║щей операции редактирования. ▒
║Для получения дополнительной информации, выберите имя ▒
║команды Edit меню. ▒
║Clear Удаляет текст без перемещения его clipboard. ▒
║Copy Копирует текст в clipboard ▒
║Cut Удаляет текст и перемещает его в clipboard. ▒
║Paste Перемещает текст из clipboard в окно редактиро- ▒
║ вания. ▒
║Undo Отменяет предыдущую операцию. ▒
╚─┘

Рисунок 5.3 Mac Word темы
╔═══════════════════════════════════════════════════════╗
║ Untitled2 ║
║───────────────────────────────────────────────────────▒
║ Help Example Index ▒
║ Index содержит список всех Help тем, доступных Help ▒
║ Example. Индексные элементы устанавливаются в алфавит-▒
║ ном порядке в пределах каждой основной категории. Вы ▒
║ можете использовать просмотровое окно для просмотра ▒
║ записей, невидимых в текущий момент в Help окне. ■
║ Более подробную информацию о том,как использовать Help▒
║ Вы можете получить, нажав F1 или выбрав Using Help из ▒
║ меню Help. ▒
║ Commands ▒
║ Edit Menu menu edit ▒
║ Edit Menu menu file ▒
║ Glossary ▒
║ Defined Terms glossary ▒
║ Procedures ▒
║ Copying Text proc copying text ▒
║ Deleting Text proc deleting text ▒
║ Exiting proc exiting ▒
║ и т.д. ▒
╚─┘

Рисунок 5.4 Help тематический дисплей
╔═[■]════════════════════════════════════════════[°][∙]═╗
║ Help Example Help - helpex.hlp ║
║───────────────────────────────────────────────────────▒
║ File Edit Bookmark Help ▒
║───────────────────────────────────────────────────────▒
║ Index Back Browse Browse Search ▒
║───────────────────────────────────────────────────────▒
║Help Example Index ■
║ Index содержит список всех Help тем, доступных Help ▒
║ Example. Индексные элементы устанавливаются в алфавит-▒
║ ном порядке в пределах каждой основной категории. Вы ▒
║ можете использовать просмотровое окно для просмотра ▒
║ записей, невидимых в текущий момент в Help окне. ▒
║ Более подробную информацию о том,как использовать Help▒
║ Вы можете получить, нажав F1 или выбрав Using Help из ▒
║ меню Help. ▒
║ Commands ▒
║ Edit Menu ▒
║ Edit Menu ▒
║ и т.д. ▒
╚─┘

Ниже приведен Helpex (пример Help) файл проекта:
[OPTIONS]
ROOT=c:\help
INDEX=main_index
TITLE=Help Example
COMPRESS=true

[FILES]
helpex.rtf ;jump topics
terms.rtf ; look-up terms

[MAP]
main_index 0xFFFF
#define HELPID_EDIT_CLEAR 100
#define HELPID_EDIT_COPY 101
#define HELPID_EDIT_CUT 102
#define HELPID_EDIT_PASTE 103
#define HELPID_EDIT_UNDO 104
#define HELPID_FILE_EXIT 200
#define HELPID_FILE_NEW 201
#define HELPID_FILE_OPEN 202
#define HELPID_FILE_PRINT 203
#define HELPID_FILE_SAVE 204
#define HELPID_FILE_SAVE_AS 205
#define HELPID_EDIT_WINDOW 300
#define HELPID_MAXIMIZE_ICON 301
#define HELPID_MINIMIZE_ICON 302
#define HELPID_SPLIT_BAR 303
#define HELPID_SIZE_BOX 304
#define HELPID_SYSTEM_MENU 305
#define HELPID_TITLE_BAR 306
#define HELPID_SIZING_BORDER 307

Сообщения об ошибках Help Compiler

Help Compiler выводит на дисплей сообщения, когда он
встречает ошибки при построении Help файла ресурсов: Ошибки во
время отработки файла проекта нумеруются, начиная с буквы P и
появляются в следующем виде:
Error P1025: line...7 of filename.HPJ : Section heading
sectionname unrecognized.
(Ошибка Р1025: строка...7 в файле имя файла.HPJ: Заголо-
вок раздела имя раздела не распознаются.)

Warning P1039: line...38 of filename.HPJ : [BUILDTAGS]
secton missing.
(Предупреждение Р1039: строка...39 в файле имя файла.HPJ:
[BUILDTAGS] недостающий раздел.)
Ошибки, встречающиеся при обработке RTF тематического
файла (файлов) нумеруются , начиная с буквы R и представляются
в следующем виде:
Error R2025: File environment error.
(Ошибка R2025: Ошибка среды файла.)

Warning R2501: Using old key-phrase table.
(Предупреждение R2501: Использование старой таблицы клю-
чевых фраз.)
Когда возможно , компилятор будет выводить на дисплей но-
мер темы и\или имя файла, которые содержат ошибку. Хотя темы
не нумеруются, номер темы, данный с сообщением об ошибке, ссы-
лается на номер последующей позиции темы в Вашем RTF файле
(первый, второй и т.д.). Эти номера могут быть идентичными с
номером страницы, показанным Вашей системой подготовки текста
и зависящим от количества строк, которое Вы присвоили гипоте-
тической печатной странице. Помните, что темы разделяются
жесткими разрывами страниц, даже если нет такого понятия как
"страница" в Help системе.
Сообщения, начинающиеся со слова "Error" (ошибка) явля-
ются фатальными ошибками. Фатальные ошибки всегда сообщаются и
в результате построения не может быть получен допустимый для
использования Help файл ресурса. Сообщения, начинающиеся со
слова "Warning" (предупреждение) являются менее серьезными.
Построение с предупреждениями буде создавать допустимый Help
файл ресурса, который будет загружаться под Windows, однако
файл может содержать операционные ошибки. Вы можете определить
количество предупреждающей информации, которая должна сооб-
щаться компилятором. Более подробную информацию о выборе уров-
ня предупреждений, которые должны выводиться на дисплей, смот-
рите в разделе "Определение сообщений об ошибках: Опция
Warning" главы 3.
Реакция компилятора на ошибку описывается для каждой
ошибки в перечислении, которое следует дальше. Во время обра-
ботки файла проекта, компилятор игнорирует строки, которые со-
держат ошибки и пытается продолжить построение. Это означает,
что встреченные ранее в построении ошибки могут привести к го-
раздо большему количеству сообщаемых ошибок, если построение
продолжается. Аналогично будут сообщаться ошибки во время об-
работки RTF тематических файлов и, если они не будут очень
серьезными, то компилятор будет продолжать построение. Условие
одной ошибки в тематическом файле может привести к нескольким
сообщениям об ошибках, которые будут сообщаться компилято-
ром. Например, неправильно идентифицированная тема вызовет
ошибку сообщаемую каждый раз, когда термины перехода ссылаются
на правильный идентификатор темы. Такая ошибка легко исправля-
ется путем корректирования сноски, содержащей неправильную
строку контекста.

Ошибки во время обработки файла проекта

───────────────────────────────────────────────────────────
P1001 Невозможный для чтения файл с именем filename.
Файл, определенный в файле проекта является нечита-
емым. Это ошибка файла DOS.
P1003 Неправильный путь, определенный в ROOT опции.
Не можетбыть найден путь, определенный в ROOT оп-
цией. компилятор использует текущий рабочий ката-
лог.
P1005 Путь и имя файла превышают ограничение в 79 симво-
лов.
Абсолютное имя файла или комбинированное корневое и
относительное имя пути, превышают ограничение DOS в
79 символов. Файл игнорируется.
P1007 Корневой путь превышает максимальное ограничение из
66 символов.
Определенное корневое имя пути превышает ограниче-
ние DOS из 66 символов. Имя пути игнорируется, и
компилятор использует текущий рабочий каталог.
P1009 Сегмент [FILES] отсутствует.
Требуется сегмент [FILES]. Компиляция прекращается.
P1011 Опция optionname определена ранее.
Опция была определена предварительно. Компилятор
игнорирует попытку повторного определения.
P1013 Расширением файла проекта не может быть .HLP.
Вы не можете задать, чтобы компилятор использовал
файл проекта с расширением .HLP. Обычно файлы про-
екта дают .HPJ расширение.
P1015 Неожиданный конец файла.
Компилятор подошел неожиданно к концу файла проек-
та. В файле проекта может находиться открытый ком-
ментарий или включенный файл.
P1017 Параметр превышает максимальную длину из 128 сим-
волов.
Опция, контекстное имя или номер, тег построения
или другой параметр на определенной строке превыша-
ют ограничения из 128 символов. Строка игнорируется.
P1021 Контекстный номер уже использовался в [MAP] сег-
менте.
Контекстный номер на определенной строке в файле
проекта ранее отображался для другой контекстной
строки. Строка игнорируется.
P1023 Include операторы вложены слишком глубоко.
Оператор #include на определенной строке превысил
максимум из пяти уровней вложения.
P1025 Не распознается заголовок сегмента с именем secti-
onname.
Используется не поддерживаемый компилятором заго-
ловок сегмента. Строка игнорируется.
P1027 Недостающие скобки из заголовка сегмента section-
name.
Недостает правильной скобки (]) из определенного
заголовка сегмента. Вставьте скобку и повторите
компилирование.
P1029 Заголовок сегмента отсутствует.
Неполный заголовок сегмента на определенной строке.
Эта ошибка также сообщается, если первая запись в
файле проекта не является заголовком сегмента. Ком-
пилятор продолжает работу со следующей строкой.
P1030 Сегмент sectionname определен ранее.
В файле проекта обнаружен дублируемый сегмент.
Строки с дублируемым заголовком проекта игнориру-
ются, и компилятор продолжает работу со следующего
правильного заголовка сегмента.
P1031 Превышено максимальное количество тегов построения.
Максимальное количество тегов построения, которое
может быть определено, равно 30. Лишние теги игно-
рируются.
P1033 Дублируемый тег построения в [BUILDTAGS] сегменте.
Тег построения в [BUILDTAGS] сегменте повторился
лишний раз.
P1035 Длина тега построения превышает максимум.
Тег построения на определенной строке превышает
максимум из 32 символов. Компилятор игнорирует эту
запись.
P1037 Тег построения tagname содержит неправильные сим-
волы.
Теги построения могут содержать только буквен-
но-цифровые символы или символ подчеркивания (_).
Строка игнорируется.
P1039 [BUILDTAGS] сегмент отсутствует.
Опция BUILD объявляет условное построение, однако в
файле проекта нет [BUILDTAGS] сегмента. Все темы
включаются в построение.
P1043 Слишком много тегов в Build выражении.
Build выражение на определенной строке использует
более 20 (максимальное значение) тегов построения.
Компилятор игнорирует строку.
P1045 [ALIAS] сегмент находится после [MAP] сегмента.
При использовании [ALIAS] сегмент должен предшест-
вовать [MAP] сегменту в файле проекта. В противном
случае [ALIAS] сегмент игнорируется.
P1047 Контекстной строке contextname уже присвоено псев-
доимя.
Вы не должны делать: a=b, затем a=c (Вы не должны
присваивать псевдоимя псевдоимени).
Определенной контекстной строке ранее было присвое-
но псевдоимя в [ALIAS] сегменте. Попытка повторного
присвоения псевдоимени на этой строке игнорируется.
P1049 Строке псевдоимени aliasname уже присвоено псевдо-
имя.
Вы не должны делать: a=b, затем b=c (Вы не должны
присваивать псевдоимя псевдоимени).
Строка псевдоимени, в свою очередь, не может
присваиваться другому псевдоимени.
P1051 Контекстная строка contextname не может использо-
ваться как строка псевдоимени.
Вы не должны делать: a=b, затем c=a
Контекстная строка, которая была присвоена псевдои-
мени, не может использоваться позже как псевдоимя
для другой контекстной строки.
P1053 Превышено максимальное количество диапазонов шриф-
та.
Максимальное количество диапазонов шрифта, которое
может быть определено равно пяти. Остальные игнори-
руются.
P1055 Текущий диапазон шрифта перекрывает ранее опреде-
ленный диапазон.
Диапазон размера шрифта перекрывает ранее опреде-
ленное соответствие. Отрегулируйте любой диапазон
шрифта для устранения любого перекрытия. Второе
соответствие игнорируется.
P1056 Нераспознаваемое имя шрифта в Forcefont опции.
Встречается имя шрифта, не поддерживаемое компилято-
ром. Имя шрифта игнорируется , и компилятор исполь-
зует определенный по умолчанию шрифт Helvetika.
P1057 Имя шрифта слишком длинное.
Имена шрифтов не должны превышать 20 символов. В
противном случае шрифт игнорируется.
P1059 Неправильный синтаксис многократных клавиш.
Не распознается синтаксис, используемый с помощью
MULTIKEY опции. Правильный синтаксис приведен в
главе 4 "Построение Help файла".
P1061 Символ не использовался.
Определенный идентификатор таблицы ключевых слов
уже используется. Выберите другой символ.
P1063 Символы 'K' и 'k' не могут использоваться.
Эти символы резервируются для обычной таблицы клю-
чевых слов Help. Выберите другой символ.
P1065 Превышено максимальное количество таблиц ключевых
слов.
Превышено ограничение из пяти таблиц ключевых слов.
Уменьшите их количество. Лишние таблицы игнориру-
ются.
P1067 Отсутствует знак равенства.
В опции отсутствует знак равенства на определенной
строке. Проверьте синтаксис для опции.
P1069 Отсутствует строка контекста.
В определенной строке отсутствует контекстная стро-
ка до знака равенства.
P1071 Незаконченная строка в сегменте sectionname.
Не завершена запись на определенной строке. Строка
игнорируется.
P1073 Нераспознаваемая опция в [OPTIONS] сегменте.
Используется опция, которая не поддерживается ком-
пилятором. Строка игнорируется.
P1075 Неправильное выражение построения.
Синтаксис, использованный в выражении построения на
определенной строке, содержит одну или более логи-
ческих или синтаксических ошибок.
P1077 Уровень предупреждения должен быть 1, 2 или 3.
Уровень сообщения WARNING может быть установлен
равным 1, 2 или 3. Компилятор будет определять по
умолчанию полное сообщение (уровень 3).
P1079 Неправильная опция сжатия.
Опция COMPRESS может устанавливаться только равной
TRUE или FALSE. Компиляция продолжается без сжатия.
P1081 Неправильная строка заголовка.
TITLE опция определяет пустую строку или строку,
которая более чем 32 символа. Заголовок укорачива-
ется.
P1083 Неправильный идентификационный номер контекста.
Номер контекста на определенной строке пустой или
содержит неправильные символы.
P1085 Нераспознаваемый текст.
Нераспознаваемый текст, который следует за правиль-
ным текстом в определенной строке, игнорируется.
P1086 Неправильный синтаксис диапазона шрифта.
Определение диапазона шрифта на определенной строке
содержит неправильный синтаксис. Компилятор игнори-
рует эту строку. Проверьте синтаксис для
MAPFONTSIZE опции.
P1089 Нераспознаваемый порядок сортировки.
Вы определили порядок, который не поддерживается
компилятором.
───────────────────────────────────────────────────────────

Ошибки во время обработки RTF тематических файлов

───────────────────────────────────────────────────────────
R2001 Невозможно открыть файл растров с именем filename.
Определенный растровый файл является нечитаемым.
Это ошибка DOS файла.
R2003 Невозможно включить растровый файл c именем file-
name.
Определенный растровый файл не может быть найден
или является нечитаемым. Это ошибка DOS файла или
условие за пределы памяти.
R2005 Диск полный.
Help файла ресурса не может быть записан на диск.
Создайте больше пространства на дисководе назначе-
ния.
R2009 Нельзя использовать резервированное имя DOS уст-
ройства для файла с именем filename.
На файл можно ссылаться как COM1, LPT2, PRN и т.д.
Переименуйте файл.
R2013 Выходной файл с именем filename уже существует как
справочник.
В Help корне проекта есть подсправочник с тем же
самым именем, как желаемое имя Help файла ресурса.
Переместите или переименуйте подсправочник.
R2015 Выходной файл с именем filename уже существует
как доступный только для чтения.
Определенное имя файла не может быть затерто Help
файлом ресурса, потому что файл имеет атрибут -
доступен только для чтения. Переименуйте файл про-
екта или измените атрибут файла.
R2017 Путь для файла с именем filename превышает ограничение
из 79 символов.
Абсолютное имя пути или комбинированное корневое и
относительное имя пути для заданного файла превыша-
ют ограничение DOS из 79 символов. Файл игнориру-
ется.
R2019 Нельзя открыть файл с именем filename.
Заданный файл является нечитаемым. Это ошибка DOS
файла.
R2021 Файл с именем filename не может быть найден.
Заданный файл не может быть найден или является не-
читаемым. Это ошибка DOS файла или условие выхода
за пределы памяти.
R2023 Недостаточно памяти для построения Help файла.
Чтобы освободить память, выгрузите любые ненужные
программы, драйверы устройств и программы резидент-
ной памяти.
R2025 Ошибка среды файла.
Компилятор имеет недостаточные для продолжения ком-
пиляции значения параметров для обработки доступных
файлов. Увеличьте значения для FILES= и BUFFERS=
в Вашем CONFIG.SYS файле и повторите начальную за-
грузку.
R2027 Не определен тег построения с именем tagname в сег-
менте [BUILDTAGS] файла проекта.
Определенный тег построения присваивается теме, но
не объявляется в файле проекта. Тег игнорируется
для темы.
R2033 Контекстная строка в Map сегменте не определяется
ни в какой теме.
В файле проекта определены одна или более кон-
текстных строк, для которых компилятор не может
найти темы.
R2035 Отсутствует выражение построения из проектного
файла.
Темы имеют теги построения, однако в файле проекта
нет Build= выражения. Компилятор включает все темы
в построение.
R2037 Не может быть создан файл с именем filename, вслед-
ствии предыдущей ошибки (ошибок).
Help файл ресурса не может быть создан из-за того,
что компилятор не имеет тем, остающихся для обра-
ботки. Исправьте ошибки, предшествующие этой ошиб-
ке, проведите повторную компиляцию.
R2039 Нераспознаваемое форматирование таблицы в теме с
именем topicnumber файла с именем filename.
Компилятор игнорирует форматирование таблицы, кото-
рая не поддерживается в Help. Переформатируйте за-
писи как линейный текст, если это возможно.
R2041 Неразрешим переход context_string в теме с именем
topicnumber файла с именем filename.
Определенная тема содержит контекстную строку, ко-
торая идентифицирует несуществующую тему. Проверьте
орфографические ошибки настолько, чтобы желаемая
тема была включена в построение.
R2043 Текст "горячего листа" не может распространяться по
параграфам.
Термин перехода соединяет два параграфа. Удалите
форматирование из маркера параграфа.
R2045 Максимальное количество позиций табуляции достигну-
то в теме с именем topicnumber файла с именем
filename.
Ограничение из 32 позиций табуляции превышено в оп-
ределенной теме. После 32-го символа табуляции
используются определенные по умолчанию позиции та-
буляции.
R2047 Файл с именем filename не создан.
Нет тем для компиляции или выражение построения яв-
ляется ложным для всех тем. Не создается Help файл
ресурса.
R2049 Текст контекстной строки слишком длинный в теме с
именем topicnumber файла с именем filename.
R2051 Файл с именем filename является неправильным RTF
тематическим файлом.
Определенный файл не является RTF файлом. Проверьте
сохранили ли Вы тему из Вашей системы подготовки
текстов как RTF файл.
R2053 Шрифт с именем fontname в файле с именем file-
name отсутствует в RTF таблице шрифтов.
Шрифт не определен в RTF заголовке, который введен
в тему. Компилятор использует определенный по умол-
чанию шрифт системы.
R2055 Файл с именем filename не является используемым
RTF тематическим файлом.
Заданный файл содержит правильный RTF заголовок, но
содержание не является RTF или разрушается.
R2057 Нераспознаваемый графический формат в теме с име-
нем topicnumber файла с именем filename.
Компилятор поддерживает только Windows растры. Про-
верьте, чтобы не использовались метафайлы или
Macintosh форматы. Графика игнорируется.
R2059 Идентификатор контекстной строки уже определен в
теме с именем topicnumber файла с именем filename.
Есть более, чем одна сноска идентификатора кон-
текстной строки для определенной темы. Компилятор
использует определенный в первой #сноске.
R2061 Строка контекста с именем contextname уже исполь-
зовалась в файле с именем filename.
Определенная контекстная строка ранее присваивалась
другой теме. Компилятор игнорирует эту вторую стро-
ку и тема остается без идентификатора.
R2063 Неправильный идентификатор контекстной строки для
темы с именем topicnumber файла с именем filename.
Сноска контекстной строки не содержит буквенно-циф-
ровых символов или является пустой. Теме идентифи-
катор не присваивается.
R2065 Контекстная строка, определенная для индексной те-
мы, является неразрешимой.
Не может быть найдена индексная тема,определенная в
файле проекта. Компилятор использует первую тему в
построении в качестве индекса.
R2067 Текст сноски слишком длинный в теме с именем
topicnumber файла с именем filename.
Текст сноски не может превышать ограничение из 1000
символов. Сноска игнорируется.
R2069 Сноска тега построения находится не в начале темы
с именем topicnumber файла с именем filename.
Заданная тема содержит сноску тега построения, ко-
торая не является первым символом в теме. Теме не
присваивается тег построения.
R2071 Отсутствует текстовая сноска в теме с именем
topicnumber файла с именем filename.
Заданная тема содержит сноску, которая не имеет
символов.
R2073 Строка ключевого слова является пустой в теме с
именем topicnumber файла с именем filename.
Сноска ключевого слова существует для заданной те-
мы, однако она не содержит символов.
R2075 Строка ключевого слова слишком длинная в теме с
именем topicnumber файла с именем filename.
Текст в сноске ключевого слова в заданной теме пре-
вышает ограничение из 255 символов. Лишние символы
игнорируются.
R2077 Ключевое слово (слова) определены без заголовка в
теме с именем topicnumber файла filename.
Ключевое слово (слова) определено для заданной те-
мы, однако заголовок теме не присвоен. Search Topic
Found выводит на дисплей Untitled Topic < для темы.
R2079 Строка последовательности просмотра является пус-
той в теме с именем topicnumber файла с именем
filename.
Сноска последовательности просмотра для заданной
темы не содержит символов последовательности.
R2081 Строка последовательности просмотра слишком длинная
в теме с именем topicnumber файла с именем filename.
Сноска последовательности просмотра для заданной
темы превышает ограничение из 128 символов. После-
довательность игнорируется.
R2083 Отсутствует номер последовательности в теме с име-
нем topicnumber файла с именем filename.
Для заданной темы номер последовательности просмот-
ра заканчивается двоеточием (:). Удалите двоеточие
или введите "младший" номер последовательности.
R2085 Номер последовательности уже определен в теме с
именем topicnumber файла с именем filename.
Уже существует сноска последовательности просмотра
для заданной темы. Последняя из них последователь-
ность игнорируется.
R2087 Тег построения слишком длинный.
Тег построения для определенной темы превышает
максимум из 32 символов. Этот тег игнорируется для
темы.
R2089 Пустая строка заголовка для темы с именем topic-
number файла с именем filename.
Сноска на заголовок для заданной темы не содержит
символов. Заголовок теме не присваивается.
R2091 Заголовок слишком длинный в теме с именем topic-
number файла с именем filename.
Заголовок для заданной темы превышает ограничение
из 128 символов. Лишние символы игнорируются.
R2093 Заголовок titlename в теме с именем topicnumber
файла с именем filename использовался ранее.
R2095 Заголовок, определенный более одного раза, в теме
с именем topicnumber файла с именем filename.
Существует более чем одна сноска заголовка в задан-
ной теме. Компилятор использует первую строку заго-
ловка.
R2501 Использование строкой таблицы ключевых слов.
Максимальное сжатие может быть получено только
посредством удаления .PH перед каждой перекомпиля-
цией Help тем.
R2503 Выход за пределы памяти во время сжатия текста.
Компилятор встретил ограничение памяти во время
сжатия. Компиляция продолжается с использованием
несжатого Help файла ресурсов. Выгрузите любые не-
нужные программы, драйверы устройств и программы
резидента памяти.
R2505 Ошибка среды файла во время сжатия текста.
Компилятор имеет недостаточные для сжатия значения
параметров, задающих допустимое количество обраба-
тываемых файлов. Компиляция продолжается с несжатым
Help файлов ресурсов. Увеличьте значения FILES=
и BUFFERS= в Вашем CONFIG.SYS файле и повторите на-
чальную загрузку.
R2507 Ошибка DOS файла во время сжатия текста.
Компилятор столкнулся с проблемой доступа к диско-
вому файлу во время сжатия. Компиляция продолжается
с несжатым Help файлом ресурса.
R2509 Ошибка во время сжатия текста.
Имеет место одна из трех ошибок сжатия - R2503,
R2505 или R2507. Компиляция продолжается с несжатым
Help файлом ресурса.
R2701 Внутренняя ошибка.
R2703 Внутренняя ошибка.
R2705 Внутренняя ошибка.
R2707 Внутренняя ошибка.
R2709 Внутренняя ошибка.
───────────────────────────────────────────────────────────