Стандарт 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.
XMLmind XML Editor Personal Edition. Простой и удобный XML-редактор, поддерживает DITA. Бесплатно скачивается здесь: https://www.xmlmind.com/xmleditor/download.shtml. Русский интерфейс устанавливается через расширения.
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", с другими уровнями аналогично.
Пошаговый флоу разработки ditamap в Oxygen XML Author с преобразованием в pdf
1. Скачиваем Oxygen XML Author здесь https://www.oxygenxml.com/xml_author.html.
2. Собираем файл ditamap в Oxygen XML Author.
Создание новой карты:
File -> New -> DITA -> Maps -> Map -> указываем каталог, где будет храниться проект -> нажимаем Create.
Добавление топика:
Ставим курсор в конец строки и нажимаем Enter -> вводим topicref -> выбираем topicref (new topic), если нужно создать новый топик, или просто topicref, если топик уже есть и нужно указать на него ссылку.
3. На панели инструментов нажимаем Configure Transformation Scenario(s). Выбираем сценарий преобразования DITA Map PDF - based on HTML5 & CSS и нажимаем Duplicate. Внизу, в наборе Project, появится DITA Map PDF - based on HTML5 & CSS - Copy, выбираем его и нажимаем Edit.
4. Во вкладке Parameters в поле CSS указываем путь к файлу styles.css*. Нажимаем OK.
5. Для преобразования ditamap в pdf нажимаем Configure Transformation Scenario(s), выбираем DITA Map PDF - based on HTML5 & CSS - Copy и нажимаем Apply Associated. Либо сразу нажимаем Apply Transformation Scenario(s) (при этом в сценариях должен быть выбран наш кастомный сценарий DITA Map PDF - based on HTML5 & CSS - Copy).
*Если нужно задать расширенное форматирование выходного документа, оптимально использовать кастомную таблицу css. Для этого используем сервис https://styles.oxygenxml.com/:
1. Задаём нужные параметры форматирования выходного документа и нажимаем Downloads.
2. Полученный пакет файлов располагаем в новом каталоге custom-css в каталоге проекта.
3.Открываем файл styles.css и после интеграций, но до параметров заголовков вставляем код:
*[class ~= "toc/title"][empty]:before {
content: "Содержание";
} 
Это необходимо, чтобы задать своё название странице с содержанием (по умолчанию она называется Contents).
Last updated