Doc-To-Help

Doc-To-Help - это инструмент для технических писателей, позволяющий написать текст документации один раз, а затем сформировать на его основе множество вариантов, которые могут различаться форматами, комплектацией, целевой аудиторией и тому подобным. Такая методика подготовки документации называется Single source publishing, то есть публикация из единого источника. Для разработки технической документации существует множество других средств - Adobe RoboHelp, Help & Manual, DocBook и так далее. Важнейшим отличием Doc-To-Help является простота его использования - он не требует от пользователя знания какого-либо специального языка разметки и позволяет использовать в качестве редактора документов Microsoft Word.

Недостатки использования Microsoft Word для написания серьезной технической документации - известны. Прежде всего к ним можно отнести:

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

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

С учетом перечисленных недостатков для разработки файлов справки более предпочтительным выглядит использование других средств, например DocBook или TeX в связке с одной из систем контроля версий (SVN, CVS и так далее).

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

Разработчики Doc-To-Help постарались интегрировать свой продукт с Microsoft Word таким образом, чтобы устранить вышеперечисленные недостатки и одновременно сохранить преимущества. В итоге получился очень интересный продукт, прекрасно подходящий для решения практических задач.

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

Doc-To-Help поддерживает компиляцию файла справки в большинство общепринятых форматов: Microsoft Help 2.0, Microsoft Compiled HTML Help, JavaHelp, NetHelp (один или несколько обычных HTML-файлов), Microsoft WinHelp, а также в форматы PDF и Microsoft Word. Не поддерживаются FlashHelp и eBook (исполняемый Windows-файл, содержащий встроенную программу просмотра).

Doc-To-Help использует два формата исходных файлов - HTML и документы Microsoft Word. Разметка файлов осуществляется с помощью собственного языка разметки D2HML, представляющего собой предопределенный набор стилей. D2HML позволяет выполнить полную разметку файла справки - задать темы, ссылки, группы, задать переменные, определить условия условной компиляции и так далее.

Для редактирования документов Word в Doc-To-Help используется Microsoft Word, для редактирования HTML-файлов - Microsoft FrontPage или Adobe Dreamweaver. Во все эти редакторы Doc-To-Help встраивает собственную инструментальную панель, позволяющую выполнять всю разметку D2HML через удобный графический интерфейс. D2HML основан на стандартной HTML-разметке, поэтому в принципе исходные HTML-файлы можно также редактировать в любом другом текстовом редакторе. Однако в таких редакторах всю разметку D2HML придется выполнять вручную.

Интерфейс среды разработки Doc-To-Help 2008 построен в современной манере, с использованием технологии построения интерфейса Ribbon. Программа от этого только выиграла - панель инструментов получилась весьма лаконичной, интуитивно понятной, простой и удобной в использовании.

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

Справа отображается окно динамической справки. Следует отметить, что технология динамического отображения справки очень активно используется в Doc-To-Help 2008, что совершенно оправданно и весьма заметно ускоряет процесс обучения работы с программой. Например, все окна, открывающиеся при выборе инструментов на панели Microsoft Word, сразу отображают соответствующий раздел справки. В случае затруднений не нужно ждать, пока справка откроется, - она уже открыта. В то же время в дальнейшем такую справку легко скрыть и расширить рабочее пространство окна. Так же просто ее включить обратно.

Типичный процесс разработки файла справки в Doc-To-Help достаточно прост. Вы создаете новый проект, добавляете в него один или несколько исходных файлов, например в формате Microsoft Word. Выполняете предварительную настройку проекта, задаете необходимые переменные и параметры условной компиляции. Далее помещаете текст документации в исходные файлы и выполняете полную разметку файла справки - помечаете названия разделов, указываете темы оглавления, задаете ключевые слова, элементы глоссария и перекрестные ссылки. В итоге вы выбираете результирующий формат файла справки, указываете параметры его оформления, проводите компиляцию и получаете готовый файл.

Doc-To-Help обеспечивает возможность детальной настройки внешнего вида сгенерированных файлов справки. Для документов Word вы можете выбрать шаблон файла, для документов HTML - задать CSS-схему. Для каждого результирующего формата файла справки можно выбрать и настроить тему, задающую размещение окна, кнопок, цвет фона и так далее.

Возможность условной компиляции в Doc-To-Help позволяет элегантно решить ранее упоминавшуюся проблему профилирования файлов справки, когда из одного и того же набора исходных документов необходимо генерировать несколько вариантов документации, различающихся по содержанию. Для выбранного фрагмента текста можно задать параметры условной компиляции: платформу, целевой формат, значения атрибутов условной компиляции. При компиляции этот текст будет включен в результирующий файл справки в том и только в том случае, если заданные для него условия будут соответствовать условиям проведения компиляции. По умолчанию в проектах Doc-To-Help определен один атрибут условной компиляции - Build с возможными значениями Internal и Release, - но можно задать сколько угодно собственных атрибутов с произвольным набором значений.

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

Doc-To-Help содержит ряд возможностей, которые пригодятся непосредственно разработчикам программного обеспечения. Во-первых, Doc-To-Help поддерживает режим работы из командной строки, что может весьма пригодиться при организации автоматической сборки проекта. К сожалению, в документации к текущей версии Doc-To-Help 2008 (build 399) почему-то о данной особенности нет ни слова, поэтому довольно трудно разобраться, как эту возможность использовать. К счастью, описание режима работы командной строки есть в документации к Doc-To-Help 2007 (см. раздел Building Help Targets in Batch Mode). Во-вторых, Doc-To-Help имеет возможность интеграции с Microsoft Sandcastle, что может пригодиться при документировании библиотек классов. Наконец, Doc-To-Help позволяет конвертировать созданные файлы справки в XHTML и автоматически применять к ним заданную XSLT-трансформацию, то есть фактически проводить необходимую постобработку сгенерированного файла справки.

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

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

Программный продукт Doc-To-Help поставляется в двух различных вариантах - Doc-To-Help for Word и Doc-To-Help Enterprise. Версия for Word имеет ряд ограничений:

• в качестве исходных документов не могут использоваться HTML-файлы;
• не поддерживаются средства совместной работы;
• нет конверторов RoboHelp HTML Converter и HTML Help Converter.

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