Операционная система Microsoft Windows 3.1 для программиста. Дополнительные главы

4.2. Создание справочной системы

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

Подготовка разделов

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

{\rtf1\ansi \deff0\deflang1024{\fonttbl{\f0\froman Times New Roman;}
{\f1\froman Symbol;}
{\f2\fswiss Arial;}{\f3\fswiss Sans Serif PS;}{\f4\fmodern Courier;}
{\f5\fmodern Sans Serif 20cpi;}{\f6\fmodern Roman Cyrillic;}
{\f7\fmodern Courier Cyrillic;}{\f8\fswiss Helv Cyrillic;}}
{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;
\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255;

К счастью, текстовый процессор Microsoft Word for Windows позволит вам создать справочную систему в режиме "почти WYSIWYG", когда внешний вид редактируемых разделов почти совпадает с тем, что увидит пользователь, запустивший справочную систему.

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

Атрибуты разделов

Перечислим атрибуты, которые может иметь раздел справочной системы. Только один из них должен быть указан всегда (контекст), остальные являются необязательными.

В справочной системе не может быть двух разделов с одинаковым контекстом. Если же по ошибке вы сделаете такие разделы, компилятор Help Compiler выведет сообщение об ошибке.

Для строки контекста (context string) вы можете использовать алфавитно-цифровые символы от A до Z, числа от 0 до 9, точку и знак подчеркивания (но не символы пробела). Максимальная длина строки - 255 символов, но не увлекайтесь длинными названиями, так как они создают дополнительные трудности при вводе текста.

Заголовок раздела (title of the topic) появляется в окне поиска и просмотра закладок, поэтому в хорошей справочной системе все разделы имеют заголовок. Максимальная длина текстовой строки заголовка составляет 128 символов.

Что же касается ключевых слов (keyword), то здесь вы можете использовать для каждого ключевого слова максимально 255 символов. Если для раздела используется несколько ключевых слов, их нужно разделить символом точка с запятой ";".

Теперь займемся последовательностями просмотра (browse sequences).

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

Рис. 4.13. Номера последовательностей просмотра

На рис. 4.13 определены четыре последовательности просмотра. Первая имеет отношение к главному меню. В ней находятся три раздела, которые описывают, соответственно, временные меню "File", "Edit" и "Help". Нажимая кнопки со значками и , пользователь сможет последовательно переходить к просмотру описаний этих меню.

Для каждого временного меню определена своя последовательность просмотра, так как, изучая меню, пользователь, скорее всего, захочет последовательно ознакомится со всеми строками этого меню.

Обозначение номера последовательности меню состоит из имени и числа, разделенного символом двоеточия ":". Каждому имени соответствует отдельная последовательность просмотра. Что же касается чисел, то можно использовать любые целые значения, причем они не обязательно должны идти подряд. Более того, для облегчения вставки в последовательность новых разделов рекомендуется нумеровать их с некоторым интервалом, как когда-то нумеровались строки в программе на языке Бейсик.

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

Тегом компиляции (build tag) отмечаются разделы, которые включаются или не включаются в справочную систему на этапе компиляции в зависимости от содержимого одного из разделов файла проекта справочной системы (файл проекта будет рассмотрен позже). Тег компиляции удобно использовать при отладке.

Назначение атрибутов разделам справочной системы

Для назначения атрибутов разделам справочной системы вам необходимо освоить технику вставки подстрочных сносок в текстовом процессоре Microsoft Word for Windows.

О том, как работать с текстовым процессором Microsoft Word for Windows вы можете прочитать в нашей книге "Введение в MS-DOS, MS Windows, MS Word for Windows", которая вышла первым томом в серии "Персональный компьютер - шаг за шагом". Здесь мы приведем лишь самые минимальные сведения, необходимые для работы со сносками.

Подстрочная сноска - это текст, который располагается в нижней части страницы и обычно отделяется от основного текста горизонтальной чертой. В тексте сноска оформляется в виде специального символа, такого как "*", или числа.

Для вставки сноски вы должны выбрать из меню "Insert" текстового процессора Word for Windows строку "Footnote...". На экране появится диалоговая панель "Footnote" (рис. 4.14).

Рис. 4.14. Вставка сноски

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

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

В процессе назначения атрибута вам нужно вставить сноску, указав в поле "Custom Footnote Mark" (рис. 4.14) нужный символ.

Как только вы вставите сноску, экран текстового процессора окажется разделен на две части - в нижней части появится окно редактирования сносок, озаглавленное "Footnotes" (рис. 4.15).

Рис. 4.15. Окно редактирования сносок

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

При помощи кнопки "Close" вы можете закрыть окно редактирования сносок. Для того чтобы вновь открыть это окно, выберите из меню "View" строку "Footnotes".

Создание перекрестных ссылок

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

Любая ссылка состоит из двух частей. Первая часть - это текст, который виден пользователю и отображается, как правило, зеленым цветом с подчеркиванием сплошной или пунктирной линией. Для выполнения перехода пользователь должен сделать щелчок левой клавишей мыши по выделенному таким образом тексту. Вторая часть не видна пользователю. Это строка контекста раздела, на который выполняется переход.

Если выполняется переход на обычный раздел, в исходном тексте справочной системы первая часть ссылки оформляется как перечеркнутая или подчеркнутая двойной чертой строка текста. Если же выполняется переход во временное окно (рис. 4.3), используется однократное подчеркивание.

Строка контекста всегда оформляется скрытым текстом.

На рис. 4.16 показан фрагмент окна текстового процессора Word for Windows, в котором видны две ссылки.

Рис. 4.16. Ссылки на временное окно и обычный раздел

Строка "графических изображений" содержит ссылку на раздел с контекстом "graphics". Обратите внимание, что первая часть ссылки подчеркнута одной чертой, а вторая оформлена скрытым текстом (показан как подчеркнутый линией, состоящей из точек). Так как строка "графических изображений" подчеркнута один раз, это ссылка на временное окно.

Вторая ссылка состоит из строк "Описание команд" и "cmd". Здесь мы видим ссылку на обычный раздел, имеющий контекст "cmd".

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

Для того чтобы выделить строку текста подчеркиванием или оформить как скрытый текст, используйте строку "Character" меню "Format" текстового процессора Word for Windows.

Создание вторичного окна

При создании ссылки на раздел можно указать, что его содержимое должно отображаться во вторичном окне. Для этого после строки контекста в тексте ссылки необходимо расположить символ > и имя окна:

SmartPadedit_wnd>edwindow

Ссылка на другой hlp-файл

Можно создать ссылку на раздел, расположенный в другом hlp-файле. Для этого после строки контекста, оформленной скрытым текстом, надо расположить символ @ и сразу вслед за ним путь к файлу:

SmartPadcontents@c:\windows\smartpad.hlp

В этой строке все символы, расположенные после строки "SmartPad" необходимо оформить скрытым текстом.

Раздел, отображаемый при помощи ссылки на другой файл, можно показать во вторичном окне:

SmartPadcontents@c:\windows\smartpad.hlp>contwindow

Создание исходного текста для файла hlpfile.hlp

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

Запустите текстовый процессор Microsoft Word for Windows. Вы можете использовать версию 2.0 или 6.0, но мы будем рассматривать приемы использования Microsoft Word for Windows версии 2.0.

Если вы приобрели дискету, которая продается вместе с книгой, загрузите из каталога hlpfile файл hlpfile.rtf, содержащий готовый исходный текст справочной системы (рис. 4.17). Если у вас нет дискеты, вам придется набрать исходный текст самостоятельно. Рассмотрим этот процесс.

Вначале создайте новый документ. Сразу после создания документ будет содержать одну строку, имеющую стиль Normal. Наберите в этой строке заголовок первого раздела, а именно, раздела оглавления справочной системы. На рис. 4.17 это строка "Текстовый редактор".

Выберите шрифтовое оформление заголовка. Учтите, что приложение winhelp.exe при отображении текста в системе пользователя подберет наиболее подходящий шрифт из числа установленных шрифтов. Для достижения максимального соответствия старайтесь выбирать только те шрифты, которые входят в стандартную поставку Windows. При этом следует также учесть, что не во всех шрифтах есть символы кириллицы.

После завершения оформления выделите весь первый параграф и в списке стилей выберите стиль "heading 1", изменив его по вашему образцу. Теперь вы сможете использовать этот стиль для оформления всех заголовков справочной системы и тогда все заголовки будут выглядеть одинаково.

Если вам нужно, чтобы в процессе просмотра раздела заголовок всегда оставался на видном месте, задайте для стиля "heading 1" атрибут оформления параграфа "Keep With Next" (располагать строки параграфа на одной странице со следующей строкой). В этом случае в верхней части окна просмотра раздела образуется дополнительное окно, содержащее заголовок.

Рис. 4.17. Первые два раздела справочной системы

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

Для того чтобы задать контекст, выполните следующие шаги:

расположите текстовый курсор в начале строки заголовка (в нашем случае курсор должен находится в начале первой строки)

вставьте подстрочную сноску (footnote) с идентификатором #

наберите в качестве текста сноски строку контекста

Затем, после определения контекста, укажем заголовок раздела, под которым он будет появляться при поиске (для поиска используется кнопка "Search", расположенная в окне Toolbar приложения winhelp.exe).

Заголовок раздела задается точно также, как и строка контекста, но в качестве идентификатора сноски следует использовать символ $.

Задайте список ключевых слов, по которым пользователь сможет найти раздел. Список ключевых слов задается как сноска с идентификатором K. Вы можете задать несколько ключевых слов, разделив их символом точка с запятой.

В заключение задайте номер последовательности просмотра как сноску с идентификатором +, указав строку "cont:010".

Окно сносок для первого и второго разделов должно выглядеть следующим образом:

$ Редактор текста Small Edit
# cont
+ cont:010
K оглавление
$ Описание команд
# cmd
+ cont:020
K команды

Аналогичным образом подготовьте остальные разделы справочной системы (рис. 4.18 и 4.19).

Рис. 4.18. Третий, четвертый и пятый разделы справочной системы

Рис. 4.19. Шестой, седьмой, восьмой и девятый разделы справочной системы

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

$ Использование клавиатуры
# key
+ cont:030
K клавиатура
$ Работа с мышью
# mouse
+ cont:040
K мышь
$ Графические изображения
# graphics
K графика;битовые изображения
$ Меню File
# file
+ cmd:010
K File; загрузка документа
$ Меню Edit
# edit
+ cmd:020
K edit; редактирование
$ Меню View
# view
+ cmd:030
K view
$ Отсутствующий раздел
# missing

Подготовив текст, сохраните его в формате RTF. Для этого из меню "File" выберите строку "Save as..." и в появившейся диалоговой панели в списке "Save File as Type" выберите строку "Rich Text Format (*.rtf)".

Затем вы можете сохранить файл и в естественном формате Word for Windows, хотя это и не обязательно.

Создание файла проекта справочной системы

Итак, на данный момент вы создали (или, что лучше и быстрее, переписали с дискеты) файл hlpfile.rtf, содержащий исходный текст разделов справочной системы. Следующим шагом будет подготовка файла проекта hlpfile.hpj, необходимого для работы компилятора Help Compiler.

Готовый файл hlpfile.hpj вы можете найти на дискете, которая продается вместе с книгой. Если дискеты нет, наберите файл самостоятельно, пользуясь листингом 4.1.

Для набора файла проекта вы можете выбрать любой текстовый редактор, сохраняющий файл без шрифтового оформления. Подойдет редактор Notepad или редактор, входящий в систему разработки Borland C++ for Windows. Можно использовать даже встроенный в Norton Commander текстовый редактор или аналогичное средство MS-DOS. И пусть вас не смущает, что вы не сможете использовать символы кириллицы из-за различий в кодировке для MS-DOS и Windows, так как... вы не сможете их использовать в любом случае. В файле проекта символы кириллицы недопустимы.

Листинг 4.1. Файл hlpfile/hlpfile.hpj

[OPTIONS]
errorlog = hlpfile.err
title = Text Editor Help
contents = cont
compress = 1
warning = 3
report = 1

[FILES]
hlpfile.rtf

[WINDOWS]
main = "Text Editor Help",,,, (255,255,192 )

[CONFIG]
BrowseButtons()

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

Рассмотрим назначение секций файла проекта нашей справочной системы.

OPTIONS

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

Перечислим некоторые параметры, значения которых задаются в секции OPTIONS:

FILES

В этой секции перечисляются файлы разделов *.rtf, из которых создается справочная система. В простейшем случае все разделы могут находиться в одном rtf-файле, однако для сложных и разветвленных справочных систем такой подход затрудняет процесс отладки.

WINDOWS

Параметры секции определяют внешний вид окон приложения winhelp.exe.

Характеристики окна определяются следующим образом:

wndname="caption",(horizposition,vertposition,width,height),
  sizing,(clientRGB),(nonscrollingRGB),topmost

Для определения характеристик главного окна приложения winhelp.exe в качестве wndname следует указать строку "main":

main = "Text Editor Help",,,, (255,255,192 )

Разработчик справочной системы может создавать дополнительные (вторичные) окна, имеющие уникальные имена. Для определения внешнего вида такого вторичного окна вместо wndname следует указывать имя этого окна.

Параметр caption задает заголовок окна.

Параметры horizposition, vertposition, width и height предназначены, соответственно, для определения горизонтального положения, вертикального положения, ширины и высоты окна. При этом следует использовать значения в диапазоне от 0 до 1024. Действительные размеры окна будут пересчитаны в соответствии с текущим разрешением экрана.

С помощью параметра sizing можно указать начальные размеры вторичного окна при его появлении на экране. Если этот параметр указан как 1, устанавливаются максимальные размеры окна. Если же значение параметра равно 0, размеры окна определяются параметрами horizposition, vertposition, width и height.

Параметры (clientRGB) и (nonscrollingRGB) задаются как тройки чисел, разделенных запятыми. Эти числа определяют, соответственно, красную, зеленую и голубую компоненту цвета для внутренней области главного окна приложения winhelp.exe и для несворачиваемого окна заголовка раздела, располагающегося в верхней части главного окна.

Если для вторичного окна указать параметр topmost, равный 1, это окно будет всегда располагаться над другими окнами, превратившись в "непотопляемое".

Неиспользуемые параметры можно не указывать, однако в строке параметров должны присутствовать все запятые до последнего указанного параметра.

CONFIG

Эта секция нужна в том случае, если разработчик справочной системы использовал дополнительные возможности приложения winhelp.exe, такие как дополнительные кнопки, макрокоманды, вызовы функций из внешних DLL-библиотек и т. п.

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

BrowseButtons()

Компиляция исходных файлов проекта

Последний шаг на пути к созданию hlp-файла - компиляция исходных файлов, описанных в файле проекта *.hpj. Это самый простой шаг, который сводится к вызову компилятора Help Compiler:

hc31 helpprj

где helpprj - имя файла проекта справочной системы (расширение имени .hpj можно не указывать).

Для того чтобы у вас не было проблем с нехваткой оперативной памяти и совместимостью с Windows версии 3.1, используйте компилятор Windows Help Compiler версии 3.10.504 или более свежей версии. Лучше всего запускать компилятор из DOS-окна в среде Windows, так как в этом случае ему будет доступна расширенная память.

Сделайте текущим каталог hlpfile и запустите компилятор hc31.exe, передав ему в качестве параметра имя файла hlpfile.hpj. В результате работы компилятора при условии отсутствия грубых ошибок в исходных файлах будет создан файл справочной системы hlpfile.hlp.

Запустите приложение winhelp.exe и выберите при помощи меню "File" только что созданный файл hlpfile.hlp. Вы увидите раздел оглавления справочной системы (рис. 4.20).

Рис. 4.20. Раздел оглавления файла hlpfile.hlp

Проверьте работу кнопок просмотра последовательностей разделов и ссылки, убедившись в том, что все работает правильно. Если что-то не так, скорее всего, вы допустили ошибку при подготовке исходных файлов.