Стандарт DITA

DITA (Darwin Information Typing Architecture) – стандарт на базе XML, предназначенный для разработки, структурирования и публикации технической документации. Создан IBM с целью упрощения повторного использования и фильтрации контента.

Основные идеи:

• каждый информационный объект (карта документа, топик) существует в единственном экземпляре;

• если информационный объект включают в несколько документов, у всех включений должен быть только один источник (принцип единого источника).

Сущности DITA:

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

• Карта документа. Фактически представляет собой оглавление, где каждый пункт – это включающая ссылка на топик. Помимо топиков карта документа может иметь собственное текстовое наполнение.

• Включающая ссылка. Гиперссылка на топик в карте документа. Кроме топиков можно ссылаться на отдельных блоки внутри них с помощью ключей (любому блоку можно задать свой id).

• Фильтр. В карте документа можно использовать профилирование – это условные конструкции, которые будут отображать или скрывать топики в конечном документе в зависимости от заданных обстоятельств. Если выходной документ поставляется с помощью DITA-OT, необходимо создать файл ditaval.xml, в котором указываются профилирующие атрибуты.

• Выходной формат. Поставка документа осуществляется в xml, html, pdf и других форматах. Механизм публикации DITA может включать форматирование текста, разметку страницы и т.д. Это зависит от конкретного инструмента (пример ниже).

Концептуальная визуализация

Пример карты документа

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map title="Как понять своего кота?" xml:lang="ru-ru">
   <topicmeta>
      <author>PhD Eleanor Abernathy</author>
      <publisher>Catnip ltd.</publisher>
      <othermeta content="Руководство пользователя" name="doctype"/>
      <othermeta content="1" name="docedition"/>
   </topicmeta>
   <topicref href="food.dita">
      <topicref href="morning_ceremony.dita"/>
      <topicref href="sauce_taste.dita"/>
      <topicref href="eat_or_sleep.dita"/>
   </topicref>
   <topicref href="objects.dita">
      <topicref href="door_open_request.dita"/>
      <topicref href="robot_vacuum_cleaner.dita"/>
      <topicref href="bird_watching.dita"/>
      <topicref href="scratching.dita"/>
   </topicref>
</map>

Пример топика

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conceptId" xml:lang="ru-ru">
   <title>Запрос на открытие двери</title>
   <shortdesc>Если долго вопить на закрытую дверь, то она обязательно откроется.</shortdesc>
   <prolog>
      <author>PhD Eleanor Abernathy</author>
      <publisher>Catnip ltd.</publisher>
   </prolog>
   <conbody>
      <section>
         <p>Для отправки уведомления о необходимости прохода в закрытую комнату кот выполняет следующие действия:</p>
         <ol>
            <li>Садится перед закрытой дверью.</li>
            <li>Начинает передавать периодические сигналы определённой амплитуды.</li>
         </ol>
         <p>После предоставления прохода отправка уведомления прекращается.</p>
         <note>Кот обычно теряет интерес к комнате после того, как дверь открыта.</note>
      </section>
   </conbody>
</concept>

Типы топиков:

• Concept. Простой текст на любую тему. Например, «Кот – общие сведения».

• Reference. Справочная информация. Например, «Варианты мяу верхней октавы».

• Task. Последовательность действий, которые нужно выполнить для решения поставленной задачи. Например, «Как выманить кота из-под дивана».

Можно создать кастомный тип топика. Стандартные топики жёстко структурированы (это же XML), но не обязательно использовать все предписанные регламентом блоки (например, вполне можно обойтись без блока prolog).

Примеры инструментов:

• Adobe FrameMaker. Популярное решение, включает WISIWIG редактор, может сразу публиковать документ в pdf.

• Oxygen XML Author. Легче, интуитивнее и функциональнее, чем FrameMaker. Единственный минус – не может сам публиковать документ в pdf.

• DITA Open Toolkit. Позволяет разрабатывать топики и карты хоть с помощью блокнота. Главная особенность – встроенные плагины и возможность добавления новых плагинов (папка plugins в директории установки). Например, встроенный плагин org.dita.pdf2 трансформирует файл .dita в файл .pdf. Параметры форматирования задаются в xsl файлах в директории плагина.

Важное для трансформирования .dita в .pdf с помощью DITA-OT

• Трансформируем файла .dita в файл .pdf с использованием предустановленного плагина org.dita.pdf2.

dita --input=C:\[расположение файла]\название файла.ditamap --format=pdf --output= C:\[куда сохраняем итоговый документ]\название документа.pdf --transtype=pdf2

• Меняем размер основного шрифта в получаемом файле pdf.

Открываем файл dita-ot-4.2.3\plugins\org.dita.pdf2\cfg\fo\attrs\basic-settings. Находим строчку <xsl:variable name="default-font-size">10pt</xsl:variable>. Меняем размер шрифта (абзац, элемент «p») на нужный.

• Меняем отступ основного текста в получаемом файле pdf.

Открываем файл dita-ot-4.2.3\plugins\org.dita.pdf2\cfg\fo\attrs\basic-settings. За отступы отвечает строчка <xsl:variable name="side-col-width">0pt</xsl:variable>.

• Меня стиль шрифта в получаемом файле pdf.

Открываем файл dita-ot-4.2.3\plugins\org.dita.pdf2\cfg\fo\font-mappings. В нём есть строки <font-face>AdobeSongStd-Light, Arial Unicode MS, Batang, SimSun</font-face> для разных типов шрифтов. Можно удалить лишние или поставить в начало тот, который нужно использовать. Однако в этом случае сбрасывается выделение жирным и курсивом (?).

• Меняем размер заголовков в получаемом файле pdf.

Открываем файл dita-ot-4.2.3/plugins/org.dita.pdf2/cfg/fo/attrs/topic-attr.xsl. В нём есть наборы атрибутов для заголовков. Например, набор <xsl:attribute-set name="topic.title" отвечает за заголовки первого уровня. Здесь можно изменить размер шрифта и другие параметры. Заголовок второго уровня<xsl:attribute-set name="topic.topik.title", с другими уровнями аналогично.