Проектирование и создание файла содержания

Хотя многие руководства советуют начинать с файла разделов, я предпочитаю сначала задать общую структуру справочной системы в файле содержания. По-моему, на компьютере это делать удобнее, чем на бумаге (проще вносить изменения, да и бумага экономится). Ведь компьютер — всего лишь инструмент, поэтому им стоит пользоваться, как любым инструментом. Help Workshop отображает графическое представление структуры разделов (рис. 13.3) по аналогии с редактором меню Visual Basic IDE. Во время работы в Help Workshop список разделов выглядит точно так же, как и обычная вкладка Contents в справочной системе приложения. Это заметно облегчает работу над проектом справочного файла.

При проектировании файла содержания стоит записать идентификаторы и заголовки разделов. Идентификаторы разделов используются компилятором справки для «стыковки» справочного файла с приложением. Они могут пригодиться при создании сносок в файле разделов. Начнем с файла содержания:

1. Установите Help Workshop из подкаталога \Common\Tools\VB\HCW на компакт-диске Visual Basic на жесткий диск (если это не было сделано ранее).

2. Запустите Help Workshop из меню Пуск.

3. Создайте новый файл содержания командой File > New. Выберите из списка строку Help Contents и нажмите кнопку ОК.

4. Первое, что необходимо сделать, — задать имя справочного файла. Введите в поле Default Filename строку Skill13. hip.

5. В поле Default Title введите строку Создание справочного файла.

Рис. 13.3. Создание файла содержания

6. Создание структуры файла начинается с добавления в список первого заголовка. Нажмите кнопку Add Above и установите переключатель Heading. В поле Title введите строку Создание справочного файла.

7. Нажмите кнопку Add Below, чтобы добавить следующий заголовок раздела ниже текущего. Установите переключатель Heading и введите в поле Title строку Создание файла содержания. Завершив ввод, нажмите кнопку ОК.

8. Нажмите кнопку Move Right, чтобы создать в заголовке отступ. По аналогии с редактором меню Visual Basic, отступ означает, что выделенный объект находится на более низком уровне иерархии, чем объект, расположенный над ним. Теперь раздел «Создание файла содержания» является подразделом по отношению к разделу «Создание справочного файла».

9. Снова нажмите кнопку Add Below, но на этот раз установите переключатель Topic. В поле Title введите строку Создать файл содержания, а в поле Topic ID -IDH_CreateContentsFile. Поля Help File и Window Type следует оставить пустыми.

10. Тем же способом добавьте следующие разделы:

Идентификатор раздела	Заголовок раздела
IDH_AddHeadings	Добавить заголовки
IDH_AddTopics	Добавить разделы

11. Добавьте очередной заголовок кнопкой Add Below. В поле Title введите строку Создание файлов разделов и нажмите кнопку ОК.

12. Добавьте следующие подразделы в раздел Создание файлов разделов:

Идентификатор раздела	Заголовок раздела
IDH_WriteTopics	Написать текст разделов
IDH_AddFootnotes	Добавить сноски
IDH_SaveRTF	Сохранить файл

13. Добавьте последний подзаголовок — введите в поле Title строку Создание файла проекта и нажмите кнопку ОК.

14. Добавьте следующие подразделы в раздел Создание файла проекта:

Идентификатор раздела	Заголовок раздела
IDH_CreateProjectFile	Создать файл проекта
IDH_SetOptions	Задать параметры проекта
IDH_SaveRTF	Сохранить файл
IDH_AddFiles	Добавить файлы в проект
IDH_DefineWindow	Определить параметры окна
IDH_Compile	Сохранить и откомпилировать проект
IDH_Test	Протестировать полученный справочный файл

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

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

После того как будет создан файл содержания, можно переходить к файлу разделов. Он представляет собой документ RTF (Rich Text Format) и содержит текст, графику, ссылки и макросы, которые воспроизводятся в справочном файле. В этом примере я использовал Microsoft Word, но приведенные команды можно адаптировать для любого текстового редактора.

1. Запустите редактор и создайте в нем новый документ.

2. Введите в первой строке документа заголовок первого раздела: Создать файл содержания.

Введите на первой странице документа, под заголовком раздела, следующий текст:

Начинать следует с файла содержания. Help Workshop обладает специальными

графическими средствами, облегчающими эту задачу. Происходящее напоминает

работу с редактором меню в Visual Basic - вы строите иерархический список

заголовков и разделов.

Выполните в Help Workshop команду File | New.

Выберите строку Help Contents и нажмите кнопку ОК.

3. Прежде чем обращаться к этому разделу, необходимо создать в нем сноску. Она должна располагаться в самом начале раздела. Установите курсор перед заголовком Создать файл содержания.

4. Выполните команду Вставка > Сноска, в группе Нумерация установите переключатель Другая и введите знак фунта (#). Закройте диалоговое окно кнопкой ОК.

5. Когда редактор переключится на текст сноски, введите строку IDH_CreateContents File — идентификатор данного раздела.

6. Теперь необходимо задать название раздела — текст, который будет отображаться при поиске в справочном файле. Установите курсор между знаком фунта и заголовком в верхней части раздела.

7. Вставьте еще одну сноску командой Вставка > Сноска, снова установите переключатель Другая и введите знак доллара ($).

8. Когда редактор переключится на текст сноски, введите строку Создать файл содержания.

9. Наконец, создайте сноску, определяющую последовательность просмотра разделов. Установите курсор между знаком доллара и текстом заголовка. Вставьте очередную сноску (Вставка > Сноска), выберите нестандартный знак сноски (Другая) и введите знак «плюс» (+).

10. В тексте сноски введите строку auto. Тем самым вы приказываете Windows Help создать в данном файле автоматическую последовательность просмотра.

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

Давайте остановимся и посмотрим, что мы сделали. Во-первых, мы создали заголовок — по нему пользователь определяет, о чем идет речь в данном разделе. В нашем примере раздел посвящен созданию файла содержания. Затем мы ввели основной текст раздела. На этом же этапе можно создать графические изображения и ссылки (в нашем справочном файле такая возможность не используется). Если эта тема вас заинтересовала, в электронной документации по Help Workshop вы найдете более чем исчерпывающую информацию.

Наконец, мы вставили в текст несколько сносок. Они необходимы для правильной работы откомпилированного файла. В нашем примере сносок было три, однако существуют и другие сноски, используемые для других эффектов. Первая сноска определяла идентификатор раздела. После нее была добавлена сноска с названием раздела и в конце — сноска, определяющая последовательность просмотра. Если вам трудно запомнить эти символы, попробуйте рассуждать так: первой идет сноска с идентификатором, в ней используется знак фунта (#). Большинство идентификаторов имеет числовое значение, и хотя о нашем этого не скажешь, обычно идентификаторы все же ассоциируются с числами. Для названия используется знак доллара ($). Разумеется, с точки зрения программиста название является строкой, а в Visual Basic символ $ используется для обозначения строк. Наконец сноска со знаком «плюс» (+) определяет последовательность просмотра. Достаточно вспомнить, что во многих программах символы «+» и «-» используются для перебора чисел, чтобы связать знак «+» с перемещением по справочному файлу.

Рис. 13.4. Текст первого раздела

Ниже перечислены основные правила включения сносок в разделы справки:

О Сноски должны находиться в самом начале раздела, перед текстом.

О Сначала добавьте сноску для определения идентификатора (#), затем введите сам идентификатор. Присутствие сноски обязательно.

О Затем добавьте сноску для названия раздела ($) и введите ее текст. Присутствие этой сноски не обязательно, но желательно.

О Добавьте сноску для последовательности просмотра (+). В ее тексте можно ввести номер или слово auto, чтобы возложить все хлопоты на компилятор.

Сохраните файл разделов в текстовом редакторе под именем Skilll3.rtf. Проследите за тем, чтобы файл был сохранен в формате RTF.

ВНИМАНИЕОбязательно сохраняйте работу перед вводом нового раздела, потому что вам придется вводить большой объем текста. Забывая о сохранении, вы рискуете потерять свою работу!

Теперь вы знаете основные принципы использования сносок, и мы можем закончить создание справочного файла:

1. Вставьте в конце раздела «жесткий» разрыв страницы, нажав клавиши Ctrl+Enter. Перед тем как вставлять новый раздел, нужно закончить предыдущий «жестким» разрывом страницы. Благодаря этому каждый раздел будет начинаться с новой страницы.

2. Введите следующий текст:

Добавить заголовки

Для добавления заголовков применяются кнопки Add Above и Add Below. Когда на экране появится диалоговое окно Edit Contents Tab Entry, установите переключатель Heading, после чего введите описание заголовка.

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

3. Создайте следующие сноски:

# IDH_AddHeadings

$ Добавить заголовки

+ auto

4. Введите текст следующего раздела:

Добавить разделы

Для каждой темы, рассматриваемой в справочном файле, создается свой раздел. Текст, который вы набираете, является разделом. Чтобы добавить раздел, нажмите кнопку Add Below или Add Above, после чего установите в диалоговом окне Edit Contents Tab Entry переключатель Topic. Для каждого раздела необходимо указать как минимум идентификатор. Для Help Workshop желательно задавать идентификаторы разделов, начинающиеся с префикса IDH_. Обратите внимание на то, что в нашем примере были использованы именно такие имена. Префикс упрощает компиляцию файла разделов. Кроме того, для раздела необходимо задать название. Оно указывается в поле Title. В этом упражнении можно не обращать внимания на другие поля: они нужны при выполнении макросов или использовании нескольких справочных файлов с одним файлом содержания.

5. Создайте следующие сноски:

# IDH_AddTopics

$ Добавить разделы

+ auto

6. Введите текст следующего раздела:

Написать текст разделов

Следующим шагом должно стать написание текста разделов. Для этого вам понадобится редактор, который умеет сохранять текст в формате RTF (Rich Text Format).

Начните с создания нового документа.

Каждый раздел должен начинаться на отдельной странице. Если вы пишете сразу несколько разделов, разделяйте их жесткими разрывами страниц. В Word для этого используется комбинация клавиш Ctrl+Enter.

Закончив составление текста, вставьте сноски, которые служат для объединения разделов.

7. Создайте следующие сноски:

# IDH_WriteTopics

$ Написать текст разделов

+ auto

8. Введите текст следующего раздела:

Добавить сноски

Составив разделы, необходимо создать на каждой странице сноски. Обязательной является только сноска для идентификатора раздела. Чтобы задать идентификатор, следует вставить сноску и выбрать в качестве ее знака символ фунта (#).

Создание сноски для идентификатора раздела:

Установите курсор в начале страницы (сноски должны находиться перед текстом раздела). В Word выполните команду Вставка|Сноска и выберите # в качестве знака сноски. Вместо текста сноски введите идентификатор раздела с префиксом IDH_ упрощающим обработку файла компилятором.

9. Создайте следующие сноски:

# IDH_AddFootnotes

$ Добавить сноски

+ auto

10. Введите текст следующего раздела:

Сохранить файл

Подготовив все разделы и сноски, сохраните файл в формате RTF. После этого можно вернуться к работе с Help Workshop и создать файл проекта.

11. Создайте следующие сноски:

# IDH_SaveRTF

$ Сохранить файл

+ auto

12. Введите текст следующего раздела:

Создать файл проекта

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

В Help Workshop выполните команду File|New. Выберите строку Help Contents и нажмите кнопку ОК.

Введите имя справочного файла в поле Help File. В нашем примере использовано имя Skill13.hlp.

13. Создайте следующие сноски:

# IDH_CreateProjectFHe

$ Создать файл проекта

+ auto

14. Введите текст следующего раздела:

Задать параметры проекта

Нажмите кнопку Options, чтобы задать различные параметры проекта.

Вкладка General

Введите в поле Help Title описание справочного файла.

Вкладка Compression

Установите переключатель Custom и флажок Hall Compression. Это

обеспечивает также возможность поиска по ключевым словам в справочном файле.

Вкладка Files

Выберите из первого списка созданный ранее файл разделов (в формате RTF).

В поле Contents File введите имя файла содержания.

15. Создайте следующие сноски:

# IDH_SetOptions

$ Задать параметры проекта

+ auto

16. Введите текст следующего раздела:

Добавить файлы в проект

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

17. Создайте следующие сноски:

# IDH_AddRles

$ Добавить файлы в проект

+ auto

18. Введите текст следующего раздела:

Определить параметры окна

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

Нажмите кнопку Window. В диалоговом окне Window Properties нажмите кнопку Add. Введите имя стиля окна и укажите, что окно должно создаваться на базе стандартного окна Procedure.

Затем перейдите на вкладку Buttons и установите флажок Browse - тем самым вы добавляете кнопки просмотра в справочное окно.

Наконец, закройте диалоговое окно кнопкой ОК.

19. Создайте следующие сноски:

# IDH_DefineWindow

$ Определить параметры окна

+ auto

20. Введите текст следующего раздела: