Как создать файл-справку

Как создать справку в формате CHM

Формат HTML Help или CHM был разработан компанией Microsoft в 1997 г. Сегодня CHM остается стандартом справки для приложений, работающих в ОС Windows. Средство для просмотра CHM-файлов есть во всех версиях Windows 10. Более того, наличие справки в приложении часто рассматривается как один из показателей качества приложения. В этой статье я расскажу о том, как создать справку в формате CHM.

Справка в формате HTML Help (CHM) представляет собой скомпилированный HTML — автономный веб-сайт, сжатый и упакованный в файл формата CHM. Наряду со стандартным функционалом, таким как динамическое оглавление, указатель и полнотекстовый поиск, HTML Help может содержать и дополнительный функционал, например, избранное и т.д. Подробное описание формата можно посмотреть в статье Формат HTML Help. Создать CHM справку можно при помощи специальных программ, как платных, так и бесплатных.

Бесплатные программы для создания CHM-справки

MS HTML Help Workshop

Компания Microsoft, разработчик формата CHM, предоставила для создания справки бесплатный инструмент, HTML Help Workshop. Его можно свободно скачать с сайта компании по данной ссылке. В составе программы имеется максимально подробный файл справки на английском языке. На сайте есть подробное описание формата, также в оригинале.

Не буду приводить пошаговые инструкции по работе с данной программой. С 1997 года их прилично накопилось в сети Интернет. Ссылки на несколько описаний вы найдете в конце статьи. В печатном виде с пошаговыми инструкциями можно ознакомиться в книге А. Гультяева «Help. Разработка справочных систем» на страницах 187-208.

Очевидный, и, на мой взгляд, единственный плюс программы HTML Help Workshop — бесплатность. Создание более-менее серьезной справки в HTML Help Workshop — очень трудоемкая задача, выполнение которой растягивается на многие месяцы. При этом вы получите справку с базовыми возможностями формата CHM: текст, рисунки, ссылки. Регулярное обновление справки на базе проекта, созданного в HTML Help Workshop, практически нереально. Я пользуюсь данной программой исключительно для компиляции / декомпиляции CHM-файлов. В более продвинутых бесплатных и профессиональных программах, предназначенных для разработки справочных систем, HTML Help Workshop используется в качестве компилятора. Это говорит о солидном потенциале формата, скрывающемся под непростым пользовательским интерфейсом инструмента.

Рассмотрим еще несколько более продвинутых программ, при помощи которых можно создать справку в формате CHM: HelpNDoc и Help+Manual.

HelpNDoc

HelpNDoc — это условно-бесплатная программа от французского разработчика, компании IBE Software. Пользовательский интерфейс программы выполнен в стиле MS Office, поэтому работу с программой можно быстро и легко освоить. Для работы с текстом, рисунками, таблицами, ссылками и другим контентом в HelpNDoc используется простой и интуитивно понятный визуальный редактор. HelpNDoc работает по принципу единого источника и поддерживает экспорт проекта в ряд форматов справки, в том числе, CHM. Подробное описание программы на русском языке можно посмотреть здесь.

На момент написания статьи выпускается 3 редакции программы:

  • Standard — платная редакция, позволяющая генерировать CHM и Web-Help в коммерческих целях. Выходные файлы в остальных форматах (DOCX, PDF, EPUB и др.) будет содержать отметку о том, что они созданы некоммерческой версии программы.
  • Professional — платная редакция без отметок во всех выходных форматах.
  • Personal — полнофункциональная программа, бесплатная для личного, некоммерческого использования. Во всех выходных форматах в нижней части всех страниц добавляется отметка о том, что файл создан с использованием некоммерческой версии HelpNDoc.

Существует множество пошаговых инструкций, как при помощи HelpNDoc создать справку в формате CHM. Они есть и в текстовом формате, и в формате видеоуроков на английском и на русском языках. Так, канал разработчика HelpNDoc на YOUTUBE содержит порядка 60 обучающих видео с пошаговыми инструкциями на английском языке. На русском языке можно рекомендовать работы Стремнева А.Ю., например, статью «Разработка электронных учебных пособий в системе HelpNDoc» (Высшее образование в России, №11, 2015 г.) и другие.

По опыту использования HelpNDoc в течение 2 лет могу поделиться только положительными впечатлениями. HelpNDoc позволяет быстро написать с нуля и оперативно обновлять справку в различных форматах. Во время работы с программой не хватает возможности вставки в документацию элементов, характерных для электронных форматов: раскрывающихся блоков с контентом (аккордеон), адаптивных изображений, размер которых автоматически подстраивается под размер окна и т.п. Разумеется, все это можно реализовать, используя готовые или написанные самостоятельно стили и скрипты, но это отрывает технического писателя от главной задачи: разработка и обновление справки.

Как создать профессиональную справку в формате CHM

Несмотря на то, что первой профессиональной программой для разработки справки, с которой я познакомился в 2003 году, был RoboHelp Х4 (в связке с RoboDemo 4 они использовались в проекте локализации библиотеки пользовательской документации, включая справку и электронный обучающий видеокурс), с 2005 года я предпочитаю работать с Help&Manual. Сегодня это программный комплекс Help+Manual 7, в котором, на мой взгляд, есть всё необходимое для автора пользовательской документации.

Help+Manual 7 Pro — это самый популярный программный комплекс для создания справки, пользовательской и различной технической документации. Он предназначен для разработки и локализации профессиональных справочных систем, руководств пользователя, баз знаний, электронных книг и другой документации в форматах CHM, WebHelp, PDF, DOCX, EPUB, MOBI и др. для настольных и мобильных приложений, iOS и Android, Windows и Linux.

Бесплатная книга по Help+Manual 7 Pro на русском языке

Большинство обучающих материалов и инструкций по Help&Manual написано на английском и немецком языках. Предлагаемая вашему вниманию книга на русском. В ней изложены основы работы с Help&Manual. Какая версия программного комплекса подходит для работы с кириллицей? Где взять Help&Manual? Как установить? Что и как настроить для начала работы? Ответы на эти и многие другие вопросы вы найдете в данной книге.

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

  • установить и подготовить Help+Manual к работе;
  • создать проект с нуля и импортировать все необходимые материалы;
  • наполнить проект контентом: текстом, рисунками, таблицами и т.д.;
  • создать справку в формате CHM.

Предварительный просмотр книги:

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

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

Cоздание справочной системы или руководства пользователя в Dr.Explain

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

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

Сам иногда занимаюсь help-файлами и не понаслышке знаю, что создание справочной системы занимает время и является кропотливой и нудной работой, особенно документирование интерфейса. Однако пару месяцев назад открыл для себя инструмент, который значительно ускоряет этот процесс. Речь идет о программе Dr.Explain от самарской компании Индиго Байт Системз. Она мне понравилась продуманным интерфейсом и возможностью документировать интерфейс ПО в полуавтоматическом режиме.

Dr.Explain vs. Help and Manual

Итак, Dr.Explain позволяет создавать help-файлы в формате CHM для поставки вместе с приложением, справочные системы в HTML для размещения на сайте продукта, а также руководства пользователя в RTF и в PDF с оглавлениями и ссылками. Справочная система генерируется в разных форматах из единого источника, что позволяет быстро обновлять документацию при выходе новых версий ПО. В этом плане Dr.Explain ничем не отличается от Help and Manual, которой я давно пользуюсь.

Интерфейс состоит из двух областей. Первая – это панель навигации с древовидной структурой содержания проекта. А вторая – редактор страниц.

В дереве задается вся структура help-файла, включая заголовки папок и страниц. Редактор страниц состоит из стандартных инструментов для написания и форматирования текста, а также имеются инструменты для вставки гиперссылок, картинок, таблиц и переменных. Все это есть и в Help and Manual, но панель инструментов в Dr.Explain скомпонована, на мой взгляд, более продуманно.

Рисунок 1. Панель инструментов Dr.Explain

Рисунок 2. Панель инструментов Help and Manual

Главная фишка Dr.Explain – это автоматизация самого трудоемкого процесса документирования – создание аннотаций пользовательского интерфейса. Да, вы правильно меня поняли. Больше не нужно делать снимки экрана самому, рисовать выноски и стрелки, вставлять все это хозяйство в проект вручную – программа сама сделает снимок любой части интерфейса по вашему выбору, проанализирует и найдет (сама!) все значимые элементы (кнопки, элементы управления, списки), вставит снимок в проект справки и автоматически расставит стрелки и пояснительные выноски к изображениям. Пользователю остается всего лишь ввести краткое пояснение к каждой выноске и все.

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

Такое полуавтоматическое документирование интерфейса значительно ускоряет и облегчает создание справочной системы, т.к. разработчику остается всего лишь добавить свои описания в выноски. В Help and Manual я все это тоже могу сделать – правда, придется делать это вручную. Обычно я делаю снимки окон в Snagit, обрабатываю края снимка, добавляю тень, рисую стрелки. А для документирования элементов окна вручную создаю табличку, нарезаю снимки кнопок и контролов, обрабатываю их края и вставляю в проект, а затем пишу описания каждой выноски. На это тратится уйма времени и усилий.

Читайте также  Как описать здание
Кое-что еще…

В Dr.Explain есть и другие полезные возможности, которых, к сожалению, нет в Help and Manual. Например, есть удобный режим просмотра проекта – одним кликом по соответствующей кнопке можно быстро посмотреть, как будет выглядеть справка в формате CHM или HTML после компиляции. Превью открывается прямо в окне редактора. Поверьте, это очень удобно. Однако нет PDF-превью – это минус. В Help and Manual чтобы посмотреть, как выглядит справка, нужно постоянно компилировать проект.

Также в программе есть возможность интегрировать контекстно-зависимую справку прямо в приложение (F1), управление деревом навигации, набор шаблонов оформления, поддержка CSS, возможность быстрого обновления документации при выходе новой версии программы путем замены иллюстраций, но с сохранением выносок, аннотаций, описаний; функция поиска и индексации в онлайн-справке без программирования (PHP, ASP) или баз данных на стороне сервера.

Создание справки на основе XML с помощью PlatyPS

При создании модуля PowerShell всегда рекомендуется включать подробную справку по созданным командлетам. Если командлеты реализованы в компилированном коде, необходимо использовать справку на основе XML. Этот формат XML известен как язык разметки Microsoft Assistance (MAML).

В устаревшей документации по пакету SDK PowerShell содержатся сведения о создании справки по командлетам PowerShell, упакованным в модули. Однако PowerShell не предоставляет средства для создания справки на основе XML. В документации по пакету SDK описывается структура справки MAML, но вы должны сами создать сложное содержимое MAML с множеством вложенных разделов.

В этом вам поможет модуль PlatyPS.

Что такое PlatyPS?

PlatyPS — это инструмент с открытым кодом, который был придуман в рамках хакатона, чтобы упростить создание и обслуживание MAML. PlatyPS документирует синтаксис наборов параметров и отдельных параметров для каждого командлета в модуле. PlatyPS создает структурированные файлы Markdown, содержащие сведения о синтаксисе. Он не может создавать описания или предоставлять примеры,

зато создает заполнители для описаний и примеров. После добавления необходимой информации PlatyPS компилирует файлы Markdown в файлы MAML. Справочная система PowerShell также допускает файлы справки в виде обычного текста (разделы общих сведений). В PlatyPS есть командлет для создания структурированного шаблона Markdown для нового файла общих сведений, но эти файлы about_*.help.txt необходимо обслуживать вручную.

В модуль можно включить файлы справки MAML и текстовые файлы. Можно также использовать PlatyPS для компиляции файлов справки в пакет CAB, который можно разместить для реализации функции обновления.

Начало работы с PlatyPS

Сначала необходимо установить PlatyPS из коллекции PowerShell.

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

Создание содержимого Markdown для модуля PowerShell

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

Выполните следующую команду для импорта модулей.

Используйте PlatyPS для создания файлов Markdown для страницы модуля и всех связанных командлетов в модуле. Повторите этот шаг для каждого модуля, который необходимо задокументировать.

Если папка выходных данных не существует, New-MarkdownHelp создаст ее. В этом примере New-MarkdownHelp создает файл Markdown для каждого командлета в модуле. Он также создает страницу модуля в файле с именем .md . Эта страница модуля включает список командлетов, содержащихся в модуле, и заполнители для краткого описания. Метаданные на странице модуля берутся из манифеста модуля и используются PlatyPS для создания XML-файла HelpInfo (как описано ниже).

New-MarkdownAboutHelp создает новый файл общих сведений с именем about_topic_name.md .

Обновление существующего содержимого Markdown при изменении модуля

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

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

Выполните следующую команду для импорта модулей.

Используйте PlatyPS для обновления файлов Markdown для целевой страницы модуля и всех связанных командлетов в модуле. Повторите этот шаг для каждого модуля, который необходимо задокументировать.

Update-MarkdownHelpModule обновляет командлет и файлы Markdown модуля в указанной папке. Файлы about_*.md не обновляются. Файл модуля ( ModuleName.md ) получает новый текст краткого описания, добавленный в файлы командлетов. Обновления файлов командлетов включают следующие изменения.

  • Наборы новых параметров
  • Новые параметры
  • Обновленные метаданные параметра
  • Обновленные сведения о типах входных и выходных данных

Дополнительные сведения см. в разделе Update-MarkdownHelpModule.

Изменение новых или обновленных файлов Markdown

PlatyPS документирует синтаксис наборов параметров и отдельных параметров. Он не может создавать описания или предоставлять примеры, а конкретные области, в которых требуется содержимое, содержатся в фигурных скобках. Пример: << Fill in the Description >>

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

Подробные сведения о записи содержимого PowerShell см. в следующих статьях.

В PlatyPS существует определенная схема, которая используется для ссылки на командлет. Эта схема допускает только определенные блоки Markdown в определенных разделах документа. Если содержимое размещено в неправильном расположении, шаг сборки PlatyPS завершается ошибкой. Дополнительные сведения см. в документации по схеме в репозитории PlatyPS. Полный пример справки по командлетам с правильным форматом см. в разделе Get-Item.

Предоставив необходимое содержимое для каждого командлета, необходимо обновить целевую страницу модуля. Убедитесь, что модуль имеет правильные значения Module Guid и Download Help Link в метаданных YAML файла .md . Добавьте отсутствующие метаданные.

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

Теперь, когда все содержимое введено, вы можете создать файлы справки MAML, отображаемые Get-Help в консоли PowerShell.

Создание внешних файлов справки

На этом шаге создаются файлы справки MAML, которые отображаются Get-Help в консоли PowerShell.

Чтобы создать файлы MAML, выполните следующую команду.

New-ExternalHelp преобразует все файлы Markdown командлета в один файл MAML (или несколько). Файлы с общими сведениями преобразуются в обычные текстовые файлы со следующим форматом имени: about_topic_name.help.txt . Содержимое Markdown должно соответствовать требованию схемы PlatyPS. New-ExternalHelp завершается с ошибками, если содержимое не соответствует схеме. Чтобы устранить нарушения схемы, необходимо изменить файлы.

PlatyPS не очень хорошо преобразует файлы about_*.md в обычный текст. Чтобы получить приемлемые результаты, используйте очень простой Markdown. Файлы можно хранить в обычном текстовом формате about_topic_name.help.txt , чтобы PlatyPS не пришлось их преобразовывать.

После завершения этого шага вы увидите файлы *-help.xml и about_*.help.txt в целевой выходной папке.

Дополнительные сведения см. в разделе New-ExternalHelp.

Тестирование скомпилированных файлов справки

Вы можете проверить содержимое с помощью командлета Get-HelpPreview.

Командлет считывает скомпилированный файл MAML и выводит содержимое в том же формате, что и Get-Help . Это позволяет проверить результаты, чтобы убедиться, что файлы Markdown скомпилированы правильно и дают нужные результаты. Если обнаружена ошибка, снова измените файлы Markdown и перекомпилируйте MAML.

Теперь все готово для публикации файлов справки.

Публикация справки

Теперь, когда файлы Markdown скомпилированы в файлы справки PowerShell, вы можете представить их пользователям. Существует два варианта предоставления справки в консоли PowerShell.

  • Упаковка файлов справки с помощью модуля.
  • Создание обновляемого пакета справки, который пользователи устанавливают с помощью командлета Update-Help .

Упаковка справки по модулю

Файлы справки можно упаковать в собственный модуль. Дополнительные сведения о структуре папок см. в разделе Написание справки для модулей. Необходимо включить список файлов справки в значение ключа FileList в манифесте модуля.

Создание обновляемого пакета справки

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

  1. Поиск веб-сайта для размещения файлов справки.
  2. Добавление ключа HelpInfoURI в манифест модуля.
  3. Создание XML-файла HelpInfo.
  4. Создание CAB-файлов.
  5. Отправка файлов.

PlatyPS помогает выполнить некоторые из этих действий.

HelpInfoURI — это URL-адрес, указывающий на расположение, где файлы справки размещаются в Интернете. Это значение настраивается в манифесте модуля. Update-Help считывает манифест модуля для получения этого URL-адреса и загрузки обновляемого содержимого справки. Этот URL-адрес должен указывать только на расположение папки, а не на отдельные файлы. Update-Help создает имена файлов для загрузки на основе других сведений из манифеста модуля и XML-файла HelpInfo.

HelpInfoURI должен заканчиваться символом прямой косой черты ( / ). Без этого символа Update-Help не сможет создать правильные пути к файлам для скачивания содержимого. Кроме того, большинство файловых служб на основе HTTP учитывают регистр. Метаданные модуля в XML-файле HelpInfo должны содержать правильный регистр букв.

Командлет New-ExternalHelp создает XML-файл HelpInfo в выходной папке. XML-файл HelpInfo строится с помощью метаданных YAML, содержащихся в файлах Markdown модуля ( ModuleName.md ).

Командлет New-ExternalHelpCab создает ZIP- и CAB-файлы, содержащие скомпилированные файлы MAML и about_*.help.txt . CAB-файлы совместимы со всеми версиями PowerShell. В PowerShell 6 и более поздних версий можно использовать ZIP-файлы.

После создания ZIP- и CAB-файлов отправьте файлы ZIP, CAB и XML HelpInfo на файловый сервер HTTP. Разместите файлы в расположении, указанном HelpInfoURI.

Дополнительные сведения см. в разделе New-ExternalHelpCab.

Другие варианты публикации

Markdown — это универсальный формат, который легко преобразовать в другие форматы для публикации. С помощью такого средства, как Pandoc, можно преобразовать файлы справки Markdown в различные форматы документов, включая обычный текст, HTML, PDF и Office.

Кроме того, командлеты ConvertFrom-Markdown ConvertFrom-Markdown] и Show-Markdown в PowerShell 6 и более поздних версий можно использовать для преобразования Markdown в HTML или создания цветового отображения в консоли PowerShell.

Известные проблемы

Для PlatyPS очень важна схема структуры создаваемых и компилируемых файлов Markdown. Допустимый Markdown вполне может нарушать эту схему. Дополнительные сведения см. в руководстве по стилю PowerShell и разделе о редактировании справочных статей.

Как создать файл-справку

Справочная система (далее в тексте также — «справка») — важная составная часть любой более-менее сложной (и даже простой) программы. Существуют разные форматы справочных систем. Справка в формате WinHelp — о ней в статье и пойдет речь, Html-help — как, например, справка к ОС Windows или к программам MS Office. В качестве справки может выступать набор связанных html-файлов, например так организована справка к СУБД MySQL. Из достоинств WinHelp можно назвать ее надежность и меньшие, чем у HTML-help, требования к ресурсам. Существуют различные программы для создания справочных систем названных типов. Однако, для создания несложной справки вполне достаточно стандартной программы MS Help Workshop, которая поставляется с Delphi. Потребуется еще редактор rtf файлов, в данной статье описывается работа со знакомым всем MS Word’ом. Все действия, которые будут описаны — несложные, но мне в свое время потребовалось определенное количество усилий и времени, чтобы разобраться по справке к Help Workshop, как все это делать. Надеюсь, что статья сможет облегчить этот путь для других. Расчитана она на начинающих. В статье описывается создание простой справки, оглавления к ней, создание последовательностей просмотра, вставка рисунков и гиперссылок, а также подключение справки к программе. Рассматривается только техническая сторона, вопрос о том, что написано в справке, оставлен в стороне.

Читайте также  Как сделать колорирование дома

Общие сведения

В состав справки к программе обычно входит несколько файлов:

  • Файлы содержащие собственно информацию — имеют расширение .hlp
  • Файлы оглавления — .cnt (от апглийского content)
  • После первого вызова справки WinHelp создает файл .gid
  • Также другие типы файлов, например, для полнотекстового поиска, о чем в статье речь не идет.

Создание тематических файлов.

Обычно справка содержит несколько тем и оглавление, из которого можно перейти к этим темам. Самый простой вариант: если тема — одна и оглавления нет. В таком случае просто пишем то, что нужно и сохраняем это в файле с расширением «.rtf». Для создания нескольких тем процесс усложняется ненамного:

  • Каждая тема должна заканчиваться жестким переходом на новую станицу. Для этого после окончания темы нужно в меню (напомню, что речь идет о MS Word) «Вставка» выбрать «Разрыв»->»Начать новую страницу».

Для того, чтобы тема были доступна из оглавления к справке, нужно задать ей идентификатор. Для этого нужно в то место текста, куда будет впоследствии происходить переход из оглавления (начало темы или, если нужно, другое место), вставить специальную разметку, а именно: концевую сноску. Символом сноски нужно выбрать «#». Идентификатором темы служит текст сноски. Например, создадим тему «Поддержка», отделим ее от других тем разрывами страниц и зададим ей идентификатор «support». Для этого поместим каретку ввода около заголовка темы и выберем в меню «Вставка»->»Сноска. «. В диалоговом окне (рис.1) выбираем вид сноски — «концевая», нумерация — «другая», в окошке для ввода символа пишем «#» (без кавычек, понятное дело). Нажимаем ОК, ссылка добавлена и каретка автоматически переведена к тексту ссылки. Пишем «support». Готово.
Повторяем то же самое для всех тем справки. Сохраняем файл. Теперь можно попробовать создать свой хелп.

Рис.1. Добавление концевой сноски.

Запускаем программу HelpWorkshop. Это — файл Hcw.exe в директории DelphiHelpTools. Создаем новый проект через меню «File»->»New»->»Help Project». Справа на панели есть ряд кнопок, нажимаем «Files. «. В диалоговом окне добавляем наш тематический файл и закрываем это окно. Сохраним проект — это будет файл с расширением hpj (Help Project). Насколько я понял, после первого запуска Help Workshop связывает себя с файлами hpj, а также — с файлами оглавления справки (cnt), так что их потом можно открывать двойным щелчком мышью. Для создания help-файла можно просто нажать кнопку «Save and Compile». Откроется новое окно с сообщением о результате компиляции. Предположим, что все в порядке, закроем это окно. Теперь в директории, где находился наш проект (.hpj), должен появиться файл справки. Однако, при двойном щелчке мышью на нем мы сможем просмотреть только первую тему. Чтобы просматривать все темы и перемещаться между ними, нужно добавить файл оглавления.

Создание оглавления справки.

Теперь создаем собственно оглавление. Оно состоит из элементов двух типов — разделы справки, которые включают в себя несколько тем и представлены в оглавлении справки значком книжки и сами темы — текст и картинки, представлены в оглавлении справки значком листа со знаком вопроса на нем (можно посмотреть это в оглавлении любой справки). Также в оглавление можно вставить макросы и включить файлы (include), этого я здесь касаться не буду. Справа на панели есть набор кнопок для добавления и манипуляции элементами оглавления. (Add Below — Добавить ниже, Add Above — Добавить выше, Move Right — Сдвинуть вправо, Move Left — Сдвинуть влево, Edit, Delete). При помощи них создаем нужную структуру оглавления. При добавлении раздела в диалоговом окне нужно указать только его название, при добавлении темы — название, идентификатор (тот, который мы задали ей в rtf-файле, когда вставляли концевую сноску), имя help-файла и имя окна. Если тема находится в том же help-файле, который мы указали как главный, то имя help-файла указывать не нужно. Имя окна указывать тоже не обязательно, если оно не указано, то тема откроется в окне по-умолчанию. Нужно сохранить файл оглавления (он будет иметь расширение .cnt) в той же директории, где находится help-файл лучше с тем же именем, что и help-файл. Теперь нужно снова открыть файл проекта .hpj и, нажав кнопку «Options», в открывшемся диалоговом окне на закладке «Files» указать наш файл оглавления (Contents file). Закрываем диалоговое окно, снова нажимаем «Save and Compile». Теперь при двойном щелчке мышью по значку файла справки должно открыться ее оглавление, из которого можно получить доступ ко всем темам.

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

Создание последовательностей просмотра.

Разметка имеет следующий вид: это тоже концевые сноски, как и для идентификаторов тем, однако в данном случае знаком сноски служит не символ «#», а «+» — знак плюса. Текстом сносок может быть либо число, либо строка символов. Просмотр будет осуществляться в порядке возрастания (как при сортировке строк). Отсюда следующее — если используются номера, то нужно вставлять необходимое количество нулей перед значащими цифрами для правильной сортировки. Например, если у Вас 20 тем, то первые нужно нумеровать как 01, 02, и т.д. Возможно несколько вариантов:

  • Если последовательностей несколько, то каждая из них может иметь имя, а темы внутри последовательности отличаться номерами (например, GUI1, GUI2, GUI3, . ), Если номера не заданы, WinHelp сам создаст последовательность просмотра при компиляции проекта в том порядке, как расположены темы в файле .rtf.
  • Если не писать ничего в текстах ссылок или написать во всех ссылках «auto» (без кавычек), то WinHelp при компиляции создаст одну последовательность просмотра в том порядке, как расположены темы в файле .rtf.

Чтобы добавить кнопки навигации » >» в окне справки (по умолчанию их нет), нужно определить хотя бы одно окно. Для этого, открыв файл проекта в HelpWorkshop, нужно нажать кнопку «Windows. » в правой части окна. В диалоговом окне с закладками нажать кнопку «Add. » и в открывшемся окне ввести в поле названия «main», а поле типа окна очистить, после чего нажать OK. Теперь у нас определено одно окно, различные свойства которого можно изменять, перемещаясь по закладкам. На закладке «Buttons» отмечаем галочкой «Browse». Нажимаем ОК, готово. Теперь окно справки будет иметь нужные кнопки. Нажимаем «Save and Compile» внизу окна и можем проверять, что получилось в выходном help файле.

Добавление картинок и гиперссылок.

Первый параметр, как написано в справке, может указывать на программу или файл. Однако, как и в ShellExecute, вместо имени файла можно указать URL, например «http://www.mysite.ru» или «mailto:nekto@somemail.ru».
Чтобы создать hotspot, запускающий такой макрос, нужно сделать следующее:
Сразу после текста hotspot’a ввести символ «!», а сразу за ним — текст макроса, например:

Примечание: URL в скобках должен быть без кавычек.
Далее, нужно отформатировать этот отрывок так: текст hotspot’a должен иметь двойное подчеркивание, а символ «!» и текст макроса после него — иметь атрибут «скрытый». И то, и другое делается через меню «Формат» -> «Шрифт» (см. рис. 2) На всякий случай, еще раз уточню: двойное подчеркивание (выпадающий список рядом с «цветом текста»), а не зачеркивание..

Теперь, если добавить такой hotspot и компилировать проект, то мы увидим в своей справке, что в строке текста

Наш сайт: www.mysite.ru — адрес выглядит и функционирует как гиперссылка.

Присоединяем справку к программе.

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

Чтобы перейти к одной из определенных нами тем справки, нужно вызвать функцию где MyTopic — идентификатор темы.

Один из способов вызова справки — нажатие клавиши F1. Можно организовать вызов контекстной справки при нажатии на F1, когда активным является тот или иной элемент управления. Для этого соответствующей теме справки нужно присвоить номер, а затем этот номер присвоить свойству HelpContext элемента управления. Чтобы задать номера для тем справки, нужно открыть проект справки в HelpWorkshop и нажать кнопку «Map» в правой части окна. Нажимаем в диалоговом окне «Add», вводим идентификатор темы и произвольный номер (например, 1 :) ), повторяем это для всех нужных тем (каждой — свой номер), закрываем окно и нажимаем в очередной раз «Save and Compile». Затем в Delphi, в окне инспектора объектов, присваиваем нужные номера нужным элементам управления (напоминаю, свойство HelpContext).

Как создать файл-справку

Файл справки CHM — это скомпилировнные в единое целое файлы HTML. Начну с того, что если редактировать файл, то сначала нужно его разобрать, а потом его собрать. Для этого нужно скачать бесплатную программу-компилятор MS HTMLHelp WorkShop (3500 KB). Лучше всего не отделываться общими фразами, а сразу описать все в примере.

Начнем. Нужно отредактировать к примеру файл help.chm , создайте папку, например chmhelp , и скопируйте его туда. Запусите MS HTMLHelp WorkShop и выберите меню File — Decompile. . В появившемся окне нажмите первую кнопку Browse. , найдите и укажите вашу папку chmhelp . Нажмите вторую кнопку Browse. , появится еще одно окно, найдите и укажите декомпилируемый файл help.chm . Нажмите ОК и через некоторое время у вас появятся много файлов в формате HTML.

Понятное дело, что без знания HTML-кода такие файлы редактировать тяжело. Для этих целей я написал небольшой патч Mode Edit IE , который из обозревателя Internet Explorer превращает его в редактор HTML. Но не просто превращает его в обычный редактор, а позволяет полностью проследить процесс редактирования, т.е. процесс правки будет полностью визуальный, примерно такой, как если бы вы правили такие файлы в MS Word. Можно тут возразить, а зачем нужно патчить IE, если есть текстовый процессор Word? Могу сказать, что после сохранения HTML-файла в Word, такой файл распухнет до безобразия. Можете поэкспериментировать. А редактирование в Internet Explorer позволяет сохранить код, в котором файл был создан изначально. Патч лишен многих возможностей, но основные операции с текстом и объектами HTML-файла может делать. Можно вставить или изменить гиперссылку, удалить или вставить рисунок. Нет возможности изменить шрифт или назначить фон. Обо всем об этом можно будет узнать из справки, которую можно будет вызвать из меню Сервис — Справка по режиму редактирования. Этот пункт появится в Internet Explorer после пропатчивания. Не буду описывать здесь Mode Edit IE , т.к. статья вообще-то по созданию справок CHM. А для более детального изучения кода HTML рекомендую учебник по HTML Алленовой Натальи , расположенном на ее сайте по адресу http://www.postroika.ru/news2.html

Читайте также  Как определить тип речи

После редактирования файлов HTML, нужно их снова запихать в формат СНМ. После декомпиляции у вас будут файлы с расширением HTM или HTML, или другое расширение, но будет один файл с содержанием, т.е. тот файл, который отвечает за окошко слева главного окна справки, на рисунке ниже отмечен красным.

Его расширение будет СНН , в нашем случае help.chh . Но без файла проекта собрать все же не удастся, поэтому запустите MS HTMLHelp WorkShop, выберите File — New, в появившемся окне выберите Project и нажмите ОК.

Появится окно мастера, нажмите кнопку Next (Далее). На следующей странице (рис. ниже) введите вручную путь к вашей папки и имя без расширения — Next (Далее). На следующей странице мастера никаких галок не ставьте — Next (Далее), и появится последняя страница, на которой нужно нажать кнопку Finish (Готово). В вашей папке chmhelp появится файл с расширением HPP, т.е. help.hhp, а главном окне MS HTMLHelp WorkShop слева, как и в файле справки, этот файл отобразится (на рис. ниже отмечен красным).

Нажмите на панели инструментов MS HTMLHelp WorkShop слева кнопку (Add/Remove topic fies) и в новом окне Topic Files нажмите кнопку Add и найдите начальный файл HTML (обычно такие файлы имеют имя index или default , хотя не исключено и другое имя, в этом вы должны были разобраться при редактировании страниц). В MS HTMLHelp WorkShop перейдите на вкладку Contenst , при этом появится окошко (рис. ниже), в котором нужно установить переключтель в пункт Open an existing contents file и нажать ОК. Выберите файл help.chh , который тоже откроется в MS HTMLHelp WorkShop на вкладке Contenst .

Здесь нужно будет отредактировать, используя кнопку (Edit Selection), темы справки. Эти темы правятся в окне Table of Contents Entry в поле Entry title (рис. ниже) — ОК. Так нужно поступить с каждой из тем.

После всех этих манипуляций нажмите кнопку (Compile HTML file) и дождитесь компиляции вашего справочного файл help.chm . На разного рода сообщения отвечайте положительно.

Обзор Help&Manual — программы для создания файлов справочной системы

Итак, вы создали программное обеспечение, которое собираетесь продать и неплохо на этом заработать. Программа, скомпилирована, отлажена и протестирована. Единственное, чего ей не хватает, — это файла помощи. Ни одно серьезное программное обеспечение не обходится без модуля справочной информации и руководства пользователя. Это придает программе законченный вид и показывает заботу о пользователе. В этом обзоре будет рассмотрена программа Help&Manual от компании EC Software, способная генерировать help-файлы самых различных форматов.

Главным преимуществом программы является ее универсальность. С ее помощью можно получить файл справочной информации в любом из наиболее распространенных на сегодняшний день форматов (CHM, HLP, HXS, HTML, PDF, RTF, EXE, XML). Интуитивно понятный интерфейс делает программу простой в освоении. Основной блок программы составляет текстовый редактор, мало отличимый от MS Word как по интерфейсу, так и по количеству возможностей.

Интерфейс программы

Интерфейс состоит из двух областей. Первая – это панель Navigation с древовидной структурой содержания файла. Вторая – редактор страниц.

В дереве задается вся структура файла содержания, так как его будет видеть пользователь. Здесь задаются заголовки папок и страниц. Для каждого элемента дерева можно задать собственную иконку и статус. В зависимости от статуса элемент выделяется своим цветом (желтый — редактируется, голубой — требует доработки, белый — готов), тем самым делая работу по наполнению страниц более наглядной.

Редактор страниц состоит из трех закладок: Topic Options (опции), Page Editor (редактор страницы), XML Source Code (исходник в формате XML).

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

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

Третья закладка – это исходный текст страницы в формате XML. При желании пользователь имеет возможность редактировать страницу прямо в исходнике или добавлять сюда код, который невозможно ввести с помощью редактора (хотя такое трудно себе представить).

Рассмотрим некоторые важные инструменты редактора.

Якоря

Якорем в программе называется невидимая метка в тексте страницы, к которой будет осуществляться переход по ключевому слову или по гиперссылке. Добавляя якорь, мы указываем для него идентификатор и ключевые слова. Все ключевые слова, указанные как целиком для страниц, так и для якорей, будут выводиться на странице «Указатель (Предметный указатель, Index) сгенерированных файлов помощи». Щелкнув по выбранному ключевому слову, будет осуществлен переход к объекту, на который то ссылается: страницу или якорь.

Гиперссылки

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

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

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

Условия

Если есть необходимость добавить в проект текстовый блок, который должен отображаться только в избранных форматах файлов помощи, то на помощь придет инструмент «Условие».

В параметрах этого инструмента выбираются форматы компилируемых файлов и ставится логическое условие IF, IFNOT или ELSE (если, если не, иначе). После применения этого инструмента выделенный текстовый блок заключается в красные маркеры.

Текстовые переменные

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

Комментарии

При написании помощи нередко ее автору требуется вставить на страницу текст, интересный только ему. Эту роль в программе выполняет инструмент «Комментарий». Он вставляет на страницу текстовый блок желтого цвета, который при компиляции файла игнорируется.

Свойства проекта

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

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

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

Следующие семь групп содержат индивидуальные настройки для каждого формата файла помощи. Например, параметры страницы для RTF или доступность текста для выделения и копирования в файле eBook(EXE).

Внешние компоненты

Из дополнительных средств Help&Manual хочется обратить внимание на три внешние компоненты, помогающие в написании инструкции.

Первая – это мощный фотограф скриншотов Screen Capture. Данная утилита позволяет делать снимка произвольной области экрана и даже отдельных элементов интерфейса: панелей инструментов, областей ввода и прочего. Более подробно, в качестве самостоятельного приложения, она описана в статье «Фотографируем окна».

Второй инструмент – это редактор шаблонов Print Manual Designer для будущих файлов в формате PDF. Здесь можно задать разметку страниц и с помощью текстовых переменных определить, как будет выводиться исходный текст в будущем файле. Шаблон, созданный в этом редакторе, сохраняется в файле MNL и в свойствах проекта подключается к настройкам формата PDF.

И последнее приложение, на которое следует обратить внимание, — это графический редактор Impict. Это довольно простой (но не примитивный) и удобный графический редактор, достаточный для нужд написания документации. Оперируя небольшим набором графических примитивов, данная утилита позволяет с легкостью создавать схемы, рисунки и диаграммы, а накладываемые эффекты позволяют сделать каждый объект изображения по-своему уникальным. Из объектов, создаваемых редактором, особо хочется выделить объект «Лупа», позволяющий увеличить изображение, на которое он накладывается. Этот инструмент будет очень полезен при работе со скриншотами с большим количеством мелких деталей.

Компиляция файла помощи

Когда текст справки набран, содержание наполнено, ссылки, якоря и изображения расставлены, можно приступить к компиляции конечного файла. В окне компиляции нужно выбрать формат конечного файла, указать его имя и расположение. После чего нажать кнопку «OK». И все! Через несколько секунд готовый файл будет перед вами.

Удобной особенностью режима компиляции является возможность включения в скомпилированный файл опций файлов других форматов. Например, в исходном тексте у вас присутствуют условия, выводящие текстовые блоки только для файлов HLP. Но однажды вам понадобилось собрать файл в формате PDF и включить туда упомянутые текстовые блоки. Для этого вам не понадобится переписывать исходный текст проекта, достаточно в окне компиляции выбрать формат файла PDF и поставить галочку Classic Winhelp (.HLP). Cледует заметить, что для компиляции файлов CHM и HLP понадобятся собственные компиляторы. Если они не установлены в системе, их можно скачать здесь.

Резюме

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

Понравилась статья? Поделиться с друзьями:
Добавить комментарий

;-) :| :x :twisted: :smile: :shock: :sad: :roll: :razz: :oops: :o :mrgreen: :lol: :idea: :grin: :evil: :cry: :cool: :arrow: :???: :?: :!: