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

В результате должна получиться примерно такая страничка со вставленным изображением:

Надеюсь, смысл вы уловили, и правильно сделали все 8 html-файлов (у меня есть ещё 9-й файл - изображение MyText.jpg).

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

C:\Education\18-01\Help

Я поместил туда 8 html-файлов:

и картинку MyText.JPG, которую я вставлял в страничке Coder.html (см. рис 28.4).

Теперь все приготовления сделаны, можно загружать программу HTML Help Workshop и заняться, наконец, созданием CHM-файла. Загрузив программу, выберите команду меню "File -> New", или щелкните кнопку "New" на Панели управления. Перед вами появится следующее окошко:

Итак, здесь вы можете выбрать для создания следующие объекты:

Создание Таблицы содержания

Как говорилось выше, вначале нужно будет сделать Таблицу содержания, поэтому выбирайте объект Table of Contents.

В окне HTML Help Workshop будет открыт объект TOC (Table Of Contents):

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

Нажмите кнопку "Insert a page" (названия кнопок появляются, если некоторое время подержать над ними указатель мыши) для добавления страницы. В поле "Entry title" требуется указать то название раздела, которое будет отображаться в таблице. У нас это будет "Назначение программы" (без кавычек, конечно). Затем нужно нажать кнопку "Add/Edit", чтобы указать соответствующий разделу HTML-файл. Откроется еще одно окно "Path or URL", в котором требуется ввести имя HTML-файла или его Интернет-адрес. Можно воспользоваться кнопкой "Browse" для выбора файла, но тогда файл будет указан вместе с его относительным адресом, например, так:

..\..\Education\18-01\Help\Naznachenie.html

У нас с вами все файлы проекта справочника будут находиться в одной папке, поэтому относительный адрес тут не нужен. Удалите его, оставив в строке "File or URL" только имя соответствующего разделу HTML-файла, у меня это:

Naznachenie.html

Нажмите кнопку "ОК", и тогда окно добавления раздела Таблицы содержания будет выглядеть так:

Нажмите "ОК", и раздел будет добавлен в Таблицу содержания.

Теперь нажмите кнопку "Insert a heading", потому что в этот раз нам нужно добавить не страницу, а книгу "Команды меню". На запрос уверены ли вы, что желаете добавить книгу в таблицу содержания, ответьте утвердительно. Процесс добавления книги абсолютно такой же, как и страницы. Укажите название раздела "Команды меню" и укажите HTML-файл, соответствующий этому разделу. Не забудьте удалить относительный адрес, если вы воспользовались кнопкой "Browse" для выбора файла.

Когда вы укажите всё, что нужно, и подтвердите все запросы, книга будет добавлена в Таблицу содержания, но окажется ВЫШЕ предыдущей страницы! А в нашей древовидной структуре она должна быть во второй строчке. Тут на помощь приходят четыре кнопки со стрелками. Первые две позволяют перемещать объект выше и ниже, а вторые - влево и вправо. Таким образом, мы можем не только установить раздел на нужную строчку Таблицы, но и передвинуть его на нужную позицию древовидной структуры. Ведь в третьей строчке у нас должна быть страница "Файл", которая будет вложенной в книгу "Команды меню", а стало быть, должна быть сдвинута вправо.

Проделав эту операцию нужное количество раз, добавьте все остальные страницы в Таблицу содержания:

Не забывайте убирать относительный адрес HTML-страниц.

Когда закончите работу, нажмите нижнюю кнопку "Save file" на левой панели инструментов для сохранения Таблицы содержания. Имя таблицы можете оставить без изменения, "Table of Contents.hhc", но убедитесь, что сохраняете его в ту же папку, где уже находятся HTML-файлы справки. Впрочем, эта самая папка уже должна быть указана в окне сохранения Таблицы, если вы добавляли HTML-страницы кнопкой "Browse".

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

Командой главного меню "File -> Close all" закройте созданную ранее Таблицу разделов. Затем выберите команду "File -> New" или нажмите кнопку "New" на Панели инструментов, чтобы начать создание нового объекта. В этот раз мы создаем Проект, поэтому в окне выбора объекта укажите Project.

Появится окно мастера создания проекта, и вначале вам будет предложено конвертировать существующий проект устаревшего формата WinHelp. Мы с вами создаём проект "с нуля", поэтому флажок "Convert WinHelp project" не устанавливаем, а сразу нажимаем "Далее".

На следующем шаге вам будет предложено ввести имя файла проекта или выбрать существующий файл. Тут проще всего нажать кнопку "Browse", убедиться, что открыта папка "Help", в которой у нас хранятся все файлы проекта справки, в поле "Имя файла" указать имя файла проекта. Тут есть одно замечание: результирующая справка будет иметь такое же имя, как и файл проекта, а имена справочных файлов обычно совпадают с именами программы. Файл программы у нас называется CodeBook.exe, значит, вписываем имя CodeBook и нажимаем "Открыть". Вы вернетесь в окно с именем файла, это имя будет указано вместе с адресом, а имя файла проекта автоматически получит расширение HHP (Hyper Help Project). У меня получилось так:

C:\Education\18-01\Help\CodeBook.hhp

Нажимаем "Далее", и откроется следующее окно мастера. Тут нам будет предложено указать, какими файлами проекта мы уже располагаем. У нас с вами есть HTML-файлы с разделами и файл Таблицы содержания, устанавливаем соответствующие флажки:

Нажимаем "Далее". На следующем шаге будет предложено указать файл Таблицы содержания. Нажмите "Browse" и выберите файл таблицы (Table of Contents.hhc). Нажимаем "Открыть", адрес и имя файла Таблицы попадет в поле мастера. Нажимаем "Далее".

На следующем шаге нам предлагается ввести все HTML-файлы проекта. Можно добавлять их по очереди, а лучше все файлы разом. Нажмите кнопку "Add", откроется окно открытия файлов. По умолчанию, должна быть открыта папка "Help". В окне вы увидите 8 HTML-файлов. Выделите первый из них, затем, удерживая кнопку <Shift>, щелкните по последнему. Все 8 файлов окажутся выделенными. Нажмите "Открыть", и все эти файлы попадут в окно мастера:

Нажимаем кнопку "Далее", затем "Готово". Всё, проект создан.

Создание индексов

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

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

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

В окне HTML Help Workshop открыт файл проекта, в левой части окна вы видите три вкладки: "Project", "Contents" и "Index". Чтобы начать создание индексов, нужно перейти на вкладку "Index". Поскольку индексный файл в проекте еще не указан, то будет выведен запрос - создаем ли мы новый индексный файл, или подключаем существующий? Мы создаем новый файл, поэтому оставьте выделенной радиокнопку "Create a new index file" и нажмите "ОК". Вам будет предложено ввести имя индексного файла, причем по умолчанию будет предложено имя Index.hhk. Не вижу особого смысла менять это имя. Убедитесь только, что в поле "Папка" по-прежнему открыта наша папка "Help", индексный файл нам нужно сохранять тоже в неё. Нажмите "Сохранить", и индексный файл будет создан.

Пока еще он пустой - индексов нет. Займемся их созданием. Вообще, следует продумать заранее, какие ключевые слова к какому разделу справки привязать. У меня получилось так:

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

Со списком разобрались, приступаем к созданию индексов. В окне HTML Help Workshop должна быть открыта вкладка "Index". Обратите внимание на кнопки левой боковой панели инструментов, они почти такие же, как у Таблицы содержания. Нас интересует вторая кнопка "Insert a keyword", на ней изображен ключ.

Нажмите на неё. Откроется окно добавления индекса. Ключевое слово или фразу нужно вписать в поле "Keyword", затем нажать кнопку "Add". Будет открыто окно, в котором нужно выбрать раздел, на который будет ссылаться данное ключевое слово. Если это слово встречается в разных разделах, то придется создавать несколько индексов: с одним ключевым словом, но разными ссылками на разделы. Для больших справочных систем та ещё работа!

Итак, ключевое слово указали, раздел справки в поле "HTML titles" выбрали - поля "File or URL" и "Title" должны заполниться автоматически. Нажмите "ОК", и новый индекс появится в окне добавления индекса:

Ещё раз нажмите "ОК", и на вкладке "Index" появится ключевое слово "кодирование". Ничего сложного, кроме того, что подобную операцию придется повторять многократно, для каждой пары "Ключевое слово - Ссылка на раздел". Так что запаситесь терпением, и введите все ваши ключевые слова и фразы.

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

Не знаю, как у вас, а у меня получилось 46 ключевых слов и фраз! Не мешало бы рассортировать их в алфавитном порядке. Для этого служит третья снизу кнопка "Sort keywords alphabetically" с буквами A и Z и стрелкой вниз - нажмите её, и список будет отсортирован. Если вам доведется работать с большой справкой, индексы можно создавать не за один подход, а добавлять их время от времени. Но потом всё же не забывайте их снова сортировать, иначе индексы будут выглядеть неряшливо.

Всё, работу с индексами закончили, нажмите нижнюю кнопку "Save file" для сохранения индексного файла.

Создание полнотекстового поиска

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

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

Включить полнотекстовый поиск очень просто. В окне HTML Help Workshop откройте вкладку "Project". Самая верхняя кнопка левой боковой панели инструментов - "Change project options" (Изменить параметры проекта). Нажмите её, перейдите на вкладу "Compiler" и включите флажок "Compile full-text search information":

Кроме того, стоит прямо сейчас указать, какая страница справки будет открываться по умолчанию. Для этого перейдите на вкладку "General", и в поле "Default file" выберите нужный файл. Я, например, выбрал Naznachenie.html. Не забудьте нажать кнопку "ОК", чтобы подтвердить изменения.

Создание вкладки "Избранное"

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

На вкладке "Project" HTML Help Workshop, на левой боковой панели инструментов, третья кнопка сверху - кнопка "Add/Modify window definitions" (Добавить/Изменить определение окна). Справка ведь выводится в окне, мы своё окно пока не создавали, пользовались тем, что создается по умолчанию, а потому к настройкам окна доступа не имеем. Вот нам и нужно создать своё окно справки. Нажмите на эту кнопку. Вам будет предложено ввести имя нового окна. Имя может быть любое, например, Favorites.

Как только вы введете имя и нажмете "ОК", откроется окно Window Types с настройками нашего нового окна. Для добавления вкладки "Избранное" нам нужно перейти на вкладку "Navigation Pane" и включить флажок "Favorites tab":

Кроме того, перейдите на вкладку "Files" и в поле "Default" также укажите файл справки, который будет открываться по умолчанию.

Нажмите "ОК", и на этом наша работа с проектом завершена. Не забудьте сохранить проект командой меню "File -> Save project" или кнопкой с изображением дискетки.

Компиляция справки

Наш проект закончен, осталось скомпилировать саму справку - файл CodeBook.chm. Делается это очень просто: выберите команду главного меню "File -> Compile…". Вам будет предложено выбрать файл проекта, для которого компилируется справка, по умолчанию будет открыт наш проект

C:\Education\18-01\Help\CodeBook.hhp

Это нам и нужно. Рекомендую включить флажок "Save all files before compiling" (Сохранить все файлы перед компиляцией). После чего можете нажать кнопку "Compile".

Если вы всё сделали правильно, в правой части окна выйдет отчет о проделанной компиляции:

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

Также указано, что был создан файл CodeBook.chm размером 99,386 байт. На этом работа с проектом завершена, можете закрыть HTML Help Workshop.

Затем можете в Проводником или файловым менеджером открыть папку Help с проектом справки, и запустить файл CodeBook.chm прямо оттуда:

Как видите, справка открывается, на ней присутствуют все 4 вкладки: "Содержание", "Указатель", "Поиск" и "Избранное". Можете поэкспериментировать с этими вкладками.

Есть пару замечаний. Первое: для показа этой справки система задействует инструменты программы MS Internet Explorer, но на каждой Windows эта программа установлена, так что беспокоиться тут нечего. Второе: справка самостоятельно запоминает последнее положение и размеры, которые установил пользователь. При последующем запуске справки эти положение и размеры будут восстановлены, что сильно облегчает нам работу.

Включение справки в проект Lazarus

Надо сказать, механизм подключения справочной системы к проекту в Lazarus ещё сыроват, и информации по этому вопросу немного. Одни советуют использовать несколько десятков строк кода, другие говорят, что это не помогает… В официальной документации (на английском языке) Lazarus советуют использовать компоненты THTMLHelpDatabase и THTMLBrowserHelpViewer с вкладки System. В качестве примера предлагают проект

C:\lazarus\examples\helphtml

Этот пример, почему то, выводит справку в браузере, установленном в системе по умолчанию. Затем мне всё же удалось запустить справку, однако справка открылась в окне просмотра Lazarus, а не системы. Это окно, как оказалось, с кириллицей "не дружит" - вместо русских букв выходили прямоугольнички.

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

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

Далее, откройте проект программы в Lazarus - запустите файл CodeBook.lpi из папки с проектом, у меня это C:\Education\18-01. Откроется Lazarus с проектом программы. В Редакторе кода убедитесь, что открыта вкладка "Main" - вкладка главного окна. Перейдите на редактор форм. Откройте редактор главного меню (дважды щелкните по компоненту MainMenu1).

Нам нужно добавить еще один элемент в раздел меню "Справка". Выделите этот раздел, выделите его элемент "О программе", щелкните правой кнопкой мыши и выберите команду "Вставить новый пункт (перед)". Появится новый пункт меню. Выделите его, свойство Name переименуйте в HelpHelp, в свойстве Caption напишите Справка, а в свойстве ShortCut выберите горячую клавишу <F1>.

Сгенерируйте для этого пункта меню событие OnClick, код которого будет довольно простой:

procedure TfMain.HelpHelpClick(Sender: TObject);
begin
  //вызываем справку:
  WinExec('hh.exe CodeBook.chm',SW_SHOW);
end;
    

Процедура WinExec вызывает внешнее системное приложение hh.exe (системный просмотрщик справок) с загруженным файлом справки CodeBook.chm. Однако WinExec сразу же работать не будет - эта процедура прописана в модуле Windows, который нужно добавить в раздел uses. Добавьте, сохраните проект, перекомпилируйте его и запустите. Нажмите <F1> или выберите команду меню "Справка -> Справка" - наша справка должна загрузиться.

Если вы захотите распространять эту программу, вам для этого будет достаточно двух файлов: CodeBook.exe (сама программа) и CodeBook.chm (справка).