КомпанияУслугиОбучениеСервисы

Технология DITA: обзор возможностей и основные преимущества

Версия для печати

Технология DITA: обзор возможностей и основные преимущества

Мария Корьевкина, «Философт»

Тезисы доклада на конференции «Документирование сегодня», 2008 г.

Введение

DITA — это такая технология разработки технической документации. Она популярна сегодня, во многие специализированные среды и XML-редакторы встроена ее поддержка. Однако, несмотря на то, что этой технологии посвящено немало публикаций, представление о ней у многих разработчиков по-прежнему смутное. Произносится много всяких “buzzwords”, сообщаются разнообразные технические подробности, говорится, как там все здорово, а что же именно здорово, остается непонятным.

Задача этого доклада — объяснить сущность технологии DITA. Вкратце, но так, чтобы стало понятно, зачем она нужна, и чем она выгодно отличается от остальных технологий разработки технической документации. Наверняка после этого доклада у заинтересованной аудитории возникнет много вопросов. Ответы на них можно будет получить на форуме «Философта» (http://forum.philosoft.ru) и, конечно, на специализированных ресурсах, ссылки на которые приведены в конце.

Мария Корьевкина делает доклад о технологии DITA

Мария Корьевкина делает доклад на конференции «Документирование сегодня»

История развития и современное состояние. Краткий обзор

Название DITA представляет собой акроним полного названия этой технологии: Darwin Information Typing Architecture. Технология была разработана в корпорации IBM в 1999–2000 г., объявлено о ней было в 2001 г. В 2005 г. консорциум OASIS выпустил первый официальный релиз DITA. В настоящее время технология развивается силами OASIS DITA Technical Committee и IBM. Технология DITA применяется для разработки технической документации в ряде крупных корпораций, в том числе, IBM, Adobe, Nokia. Во многих средствах разработки технической документации и XML-редакторах имеется встроенная поддержка языка разметки DITA.

Что общего между DITA и другими технологиями?

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

Общая схема создания документа такова:

  1. Автор пишет текст документации, размечая его в соответствии с синтаксисом используемого языка разметки. В результате получается текстовый файл, в котором как таковой текст перемежается условными обозначениями, отражающими функции отдельных фрагментов внутри этого текста.
  2. К полученному на первом этапе текстовому файлу применяется программа-конвертор. На выходе получается документ в том или ином формате, например, PDF или HTML. Оформление текста в этом документе определяется стилями, которые были подготовлены заранее самим автором или кем-то другим.

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

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

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

И TeX, и DocBook, и DITA это могут. В чем же особенность последней?

Чем DITA принципиально отличается от других технологий?

Мы уже говорили о том, что в авторском коллективе приходится прикладывать усилия к тому, чтобы части, написанные разными авторами, были унифицированы. То же самое, если автор один, но объем документации достаточно объемен и делается на протяжении достаточно долгого времени. При этом имелась в виду унификация оформления: все термины печатать курсовом, все названия элементов полужирным шрифтом, все врезки располагать с таким-то отступом и т.п. Это важно, но требования к унифицированности текста технической документации этим не ограничиваются.

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

Предположим, некая среда разработки приложений включает в себя глобальные переменные, встроенные функции и объекты, классы. В таком случае все, например, классы должны быть описаны по одному и тому же плану. Если один автор, документируя класс, будет описывать сначала свойства, а потом методы, а другой, наоборот, сначала методы, а потом свойства, пользоваться такой документацией программисту будет, как минимум, неудобно. Хуже того, если один автор будет описывать связанные с этими классами исключительные ситуации (exceptions), а второй будет в принципе забывать это делать, то работа программиста с этими классами будет сильно осложнена. Каждая функция тоже должна быть описана по унифицированному плану, но для функций этот план, конечно, не такой, как для классов.

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

В общем, при описании однотипных предметов мы должны:

  • придерживаться определенной последовательности изложения материала;
  • не забыть сказать о критически важном (своего рода обязательные поля в документации).

Когда мы используем TeX или DocBook (а также Microsoft Word, AuthorIT, H&M и многое другое) мы можем в этом отношении только полагаться на дисциплину авторов и настырность их начальника. Технология DITA позволяет поддерживать унификацию текста на этом уровне технически, принуждая авторов соблюдать заданный начальником план. В этом и состоит ее принципиальное отличие от других технологий.

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

О типизации топиков в DITA можно сказать еще кое-что, но мы пока на этом остановимся и посмотрим, как технически обеспечивается соблюдение авторами «законов жанра» в зависимости от типа топика.

Расширяемый язык разметки DITA

В двух словах об XML

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

Часто приходится слышать, что XML — это такой формат данных. Это и так, и не так. Как таковой XML представляет собой нечто более общее: язык описания языков разметки. Например, мы можем составить описание, приведенное на следующем листинге.

Листинг 1. Пример формального описания синтаксиса очень простого языка разметки

<!ELEMENT section (title, section*)>
<!ELEMENT title (#PCDATA)>

Приведенные выше две строки означают, что:

  • элемент section обязательно содержит ровно один элемент title;
  • в элемент section допускается включать другие элементы section в любом количестве;
  • в элемент title допускает включать обычный текст;
  • все остальное не допускается.

Такое описание называется описанием типа документов, DTD (document type definition). Предположим, мы сохранили его в файле с именем structML.dtd. Составив это DTD, мы описали язык разметки, довольно бедный, который, тем не менее, можно было бы использовать для описания структур документов. Например, структуру известной песенки мы можем на этом языке описать следующим образом.

Листинг 2. Пример XML-документа, составленного с использованием языка разметки, описание синтаксиса которого показано на листинге 1

<?xml version="1.0">
<!DOCTYPE section SYSTEM "structML.dtd">

<section>
   <title>Сказка про серенького козлика<title>

   <section>
      <title>Жизнь серенького козлика у бабушки</title>
   </section>

   <section>
      <title>Козлик отправляется в путешествие</title>
   </section>

   <section>
      <title>Смерть козлика</title>
      <section>
            <title>Общие сведения о волках</title>
      </section>
      <section>
            <title>Встреча козлика с волком</title>
      </section>
      <section>
            <title>Что осталось от козлика</title>
      </section>

   </section>

</section>

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

Листинг 3. Пример XML-документа, составленного с ошибкой (относительно языка разметки, описание синтаксиса которого показано на листинге 1)

<?xml version="1.0">
<!DOCTYPE section SYSTEM "structML.dtd">

<section>

   <section>
      <title>Как заводить друзей</title>
   </section>

   <section>
      <title>Как оказывать влияние не людей</title>
   </section>

   <title>Как стать успешным человеком</title>
</section>

Ошибка в том, что элемент title корневого элемента section оказался последним из трех, что запрещено составленным нами DTD.

Тут возникает вопрос: правила правилами, но как заставить авторов их соблюдать, ведь бумага, как говорится, все стерпит? Бумага да, и текстовый редактор тоже, а XML-редактор — нет. Обратите внимание, что в начале документа присутствует ссылка на файл с DTD. XML-редактор считывает из него DTD и следит за тем, чтобы автор соблюдал записанные в нем правила. Разные XML-редакторы делают это по-разному: одни при нарушении автором правил выводят сообщения об ошибке, другие изначально не допускают нарушения автором правил: автоматически вставляют в документ обязательные элементы и не дают вставлять элемент, если он недопустим текущем контексте (рис. 1).

Рисунок 1. XML-редактор Serna компании Syntext. Между двумя элементами setp допустим только элемент step. Редактор позволяет вставить внутрь процедуры только его

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

Типы топиков. Специализация типов

Техническая возможность унификации описаний обеспечивается следующими мерами:

  • каждый тип («жанр») топиков описан в DTD;
  • все участвующие в проекте авторы имеют доступ к этим DTD;
  • все участвующие в проекте авторы пользуются XML-редакторами для ввода текста.

Изначально в DITA описаны четыре типа топиков:

  • topic — фрагмент произвольного назначения;
  • concept — концепция или, иначе говоря, информация общего назначения;
  • task — последовательность действий, предназначенных для решения какой-либо задачи;
  • reference — справочная информация.

На следующем листинге приведены примеры топиков типа concept и task.

Листинг 4. Пример топика типы concept

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE concept 
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">

<concept id="intro" 
         xml:lang="ru-ru" 
         xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/">

   <title>Введение</title>

   <prolog>
      <author> М. М. Корьевкина</author>
      <copyright>
         <copyryear year="2007"/>
         <copyrholder>PhiloSoft</copyrholder>
     </copyright>
   </prolog>

   <conbody>
       <p>Документ содержит сведения об установке, 
          настройке и применении программы PhiloSoft Mail.</p>
   </conbody>

</concept>

Листинг 5. Пример топика типы task

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "../../dtd/task.dtd">

<task id="installprogram" 
      xml:lang="ru-ru"
      xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/">

   <title>Установка программы</title>

   <prolog>
      <author>М. Ю. Острогорский</author>
      <copyright>
         <copyryear year="2007"/>
         <copyrholder>PhiloSoft</copyrholder>
     </copyright>
   </prolog>

   <taskbody>

      <p>Для того чтобы установить программу на компьютер:</p>

      <steps>

         <step>
            <cmd>
               Распакуйте архив <filepath>install.zip</filepath> 
               в произвольный каталог.
            </cmd>
         </step>

         <step>
            <cmd>
               Запустите программу <filepath>install.exe</filepath>.
            </cmd>
         </step>

         <step>
            <cmd>
               Следуйте указаниям, выводимым программой установки на экран.
            </cmd>
         </step>

      </steps>

   </taskbody>

</task>

В случае необходимости вы можете описать в виде DTD собственные типы топиков, например, form для документирования экранных форм и report для отчетов. Процедура создания собственных типов топиков называется специализацией, а сами новые типы топиков — специализированными типами.

И тут снова возникает вопрос: для чего нам нужна какая-то особая технология, если мы сами можем написать любое DTD и писать по нему текст? Конечно, мы это можем. Однако не будем забывать, что текст необходимо не только набирать, но и оформлять. Поэтому для каждого придуманного нами типа топика мы должны будем еще разработать стиль оформления, в котором для каждого элемента задан способ обработки. Под обработкой здесь понимается и визуальное оформление (заголовки крупным шрифтом, термины курсивом), но и логика компиляции документов, например, формирование оглавления или разбивка документа на HTML-страницы, каждая из которых соответствует разделу определенного уровня.

В комплекте инструментария DITA уже есть готовые стили, реализующие все наиболее важные функции формирования документов примерно на том же уровне, на котором это делают стили DocBook XSL. Технология DITA позволяет, с одной стороны, создавать новые типы топиков, а с другой, использовать для их обработки уже имеющиеся стили. Это достигается благодаря приему, который в объектно-ориентированном программировании известен как наследование.

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

Рассмотрим такой пример. Тип (и, соответственно, элемент) concept в числе прочего содержимого имеет подчиненный элемент title, предназначенный, как вы наверно догадались, для разметки заголовка топика. Допустим, на основе типа concept мы решили создать новый тип screen-form. Мы хотим, чтобы у него тоже был заголовок, однако, указывать это явно в описании типа screen-form мы не обязаны. Заголовком новый тип будет обладать, поскольку таковой имеется у базового типа.

Напомним, что речь только что шла не о конкретных топиках, а о типах топиков. Что же касается самих топиков, то с ними будет происходить следующее:

  • При создании в XML-редакторе нового топика типа screen-form в него автоматически будет вставляться обязательный элемент title.
  • При сборке документа заголовки топиков типа screen-form будут правильно оформлены и включены в оглавление.

Специализация не подразумевает обязательного сохранения имен наследуемых элементов. Мы можем принять решение о том, что в топиках типа screen-form заголовок размечается элементом под названием caption, а не title. Тогда при создании типа screen-form мы указываем, что внутри элемента screen-form должен присутствовать ровно один элемент caption, и что он соответствует элементу title базового типа.

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

Специализация допускается для любого типа топиков, а не только для базовых, т.е. в сложных проектах типы топиков могут образовывать довольно «ветвистое» дерево. Таким образом, язык разметки DITA в отличие от языка разметки DocBook/XML предполагает расширение для нужд конкретного проекта.

Словари

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

Архитектура документа в DITA

Когда мы набираем документ в обычном текстовом процессоре (для простоты будем говорить о Microsoft Word) текст как таковой и его оформление слиты в одном файле. Что в этом плохого, давно известно: такой документ сложно (читай, дорого) сопровождать.

Технология DocBook проводит четкую, насколько это возможно, границу между текстом и оформлением: текст хранится в XML-файлах, оформление задано XSLT-стилями. В остальном докбуковский документ, если прибегать специальным трюкам, устроен примерно так же, как вордовский. Он делится по иерархическому принципу на структурные элементы (главы, разделы подразделы и т.д.), а в самом низу этой иерархии находится т.н. сплошной текст. Правда, за счет тегового синтаксиса в DocBook иерархия обозначена более четко, чем в большинстве текстовых процессоров.

В докбуковском документе, как и в вордовском, автор с самого начала придает тексту определенную структуру. Что в этом плохого? При создании крупных комплектов документации фрагменты, повторяющиеся в разных документах, приходится размножать методом «copy-paste», что не только трудоемко само по себе, но опять-таки усложняет сопровождение, поскольку при внесении в документацию изменений приходится тщательно отслеживать все копии исправленного фрагмента.

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

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

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

Листинг 6. Пример карты документа

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "../dtd/map.dtd">

<map xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"
     title="Руководство пользователя"
     xml:lang="ru-ru" toc="yes">

  <!-- Вводный раздел. Вложение тем является 
       типичным способом построения карты документа-->
   <topicref href="concept/intro.xml">
      <topicref href="concept/functionality.xml"/>
       <topicref href="topic/symbolicnotation.xml"/>
   </topicref>

   <!--Установка программы -->
   <topicref href="concept/install.xml">
      <topicref href="concept/complect.xml"/>
      <topicref href="task/installprogram.xml"/>
      <topicref href="concept/copyright.xml"/>
   </topicref>

   <!-- Интерфейс пользователя -->
   <topicref href="concept/userinterface.xml" type="concept"/>

   <!-- Работа с почтой-->
   <topicref href="concept/correspondence.xml">
      <topicref href="task/correspondence_messagelist.xml"/>
      <topicref href="task/correspondence_createmessage.xml"/>
      <topicref href="task/correspondence_receive.xml"/>
      <topicref href="task/correspondence_reply.xml"/>
      <topicref href="task/correspondence_forward.xml"/>
   </topicref>

   <!-- Ведение адресной книги -->
   <topicref href="concept/addressbook.xml">
      <topicref href="task/addressbook_cards.xml"/>
      <topicref href="task/addressbook_add.xml"/>
      <topicref href="task/addressbook_change.xml"/>
      <topicref href="task/addressbook_delete.xml"/>
      <topicref href="task/addressbook_search.xml"/>
   </topicref>

   <!-- Настройка -->
   <topicref href="concept/settings.xml">
      <topicref href="task/settings_messageeditor.xml"/>
      <topicref href="task/settings_addressbook.xml"/>
      <topicref href="task/settings_messahearchive.xml"/>
      <topicref href="task/settings_crypto.xml" audience="professional"/>
      <topicref href="task/settings_spam.xml" audience="professional"/>
   </topicref>

   <!-- Приложения -->
   <topicref href="reference/dialogwindows.xml" type="reference"/>
   <topicref href="reference/netrules.xml" type="reference"/>
   <topicref href="reference/symbolicsigns.xml" type="reference"/>

</map>

Формирование документов. DITA Open Toolkit

Исходный документ

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

Технически все файлы топиков и все карты мы можем поместить в один каталог. На практике в хоть сколько-нибудь сложных проектах топики распределяют по некоторому дереву каталогов в соответствии с их содержанием.

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

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

Инструментарий

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

Для формирования документов требуется следующее программное обеспечение:

  • комплект программ и XSLT-стилей и документации DITA Open Toolkit;
  • SUN Java Developer Kit версии не ниже 1.4.2;
  • Microsoft HTML Help Workshop (для формирование CHM-файлов);
  • RenderX XEP (для формирования качественных PDF-документов).

Кроме RenderX XEP весь инструментарий бесплатный.

В состав DITA Open Toolkit входят следующие компоненты:

  • DTD языка разметки DITA;
  • XSLT-стили для обработки дитовских документов;
  • FO-процессор FOP (предназначен для формирования PDF);
  • среда для управления обработкой ANT;
  • документация и примеры.

Порядок формирования документа

Для каждого документа необходимо сформировать следующие файлы:

  • Конфигурационный файл, содержащий параметры, управляющие формированием документа. К таковым относятся, в частности, имя файла карты, расположение и имя конечного документа, формат конечного документа.
  • Командный файл, непосредственно выполняющий формирование документа. Этот файл, как правило, состоит из одной строки: вызова исполняемого файла ant с указанием имени конфигурационного файла в качестве параметра.

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

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

Примеры конфигурационных и командных файлов входят в состав DITA Open Toolkit.

Ссылки

Общая информация

Инструментарий

Примеры

Ответы на вопросы

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG