# Стандарт DITA

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

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

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

#### Сущности DITA:

* **Топик.** Озаглавленный информационный объект, который может быть понят в отдельности от других объектов и используется в различных контекстах. Как правило, раскрывает один конкретный вопрос.
* **Карта документа.** Фактически представляет собой оглавление, где каждый пункт – это включающая ссылка на топик. Помимо топиков карта документа может иметь собственное текстовое наполнение.
* **Включающая ссылка.** Гиперссылка на топик в карте документа. Кроме топиков можно ссылаться на отдельных блоки внутри них с помощью ключей (любому блоку можно задать свой id).
* **Фильтр.** В карте документа можно использовать *профилирование* – это условные конструкции, которые будут отображать или скрывать топики в конечном документе в зависимости от заданных обстоятельств. Если  выходной документ поставляется с помощью DITA-OT, необходимо создать файл ditaval.xml, в котором указываются *профилирующие атрибуты*.
* **Выходной формат.** Поставка документа осуществляется в xml, html, pdf и других форматах. Механизм публикации DITA может включать форматирование текста, разметку страницы и т.д. Это зависит от конкретного инструмента (пример ниже).

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

<figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FB2rHTkUHFiLzRuOf7vzP%2Fimage.png?alt=media&#x26;token=c874cea3-f6f9-4fb6-9bfc-9e8d825f9e18" alt=""><figcaption></figcaption></figure>

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

```xml
<?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
<?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.

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FEvufa9pbnKHhjuHzETpM%2Fimage.png?alt=media&#x26;token=de3ef31f-fc40-4dcb-804d-d405fdedf06a" alt="" width="361"><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FjKT6arbXOvUt9KBOgTtc%2Fimage.png?alt=media&#x26;token=0ee6ef14-546e-4358-a4a1-4f6d405ce623" alt="" width="359"><figcaption></figcaption></figure></div>

Добавление топика:

Ставим курсор в конец строки и нажимаем Enter -> вводим topicref -> выбираем topicref (new topic), если нужно создать новый топик, или просто topicref, если топик уже есть и нужно указать на него ссылку.

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2F7a0VaMEjHUloLlbzYFWj%2Fimage.png?alt=media&#x26;token=341f1745-a463-40e8-bc5e-7501715555c1" alt=""><figcaption></figcaption></figure></div>

**3.** На панели инструментов нажимаем **Configure Transformation Scenario(s)**. Выбираем сценарий преобразования **DITA Map PDF - based on HTML5 & CSS** и нажимаем **Duplicate**. Внизу, в наборе **Project**, появится **DITA Map PDF - based on HTML5 & CSS -  Copy**, выбираем его и нажимаем **Edit**.

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FiDIWprpN9aTQM7SgIGPq%2Fimage.png?alt=media&#x26;token=dc273df4-c647-4de0-b2b9-b67ce3bd7bc9" alt=""><figcaption></figcaption></figure></div>

4\. Во вкладке **Parameters** в поле **CSS** указываем путь к файлу **styles.css**\*. Нажимаем **OK**.

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2Fw5MGPBKjn0tqbv8a7KvL%2Fimage.png?alt=media&#x26;token=86c075b0-8440-41e2-9a3c-efcc397dffc8" alt=""><figcaption></figcaption></figure></div>

**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).

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FgHyiF0TaiZBAO5VwC01Z%2Fimage.png?alt=media&#x26;token=a62e5580-136d-4fff-93ca-6f7ec5693092" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FrhgWnDZh7tUYfZGDULJX%2Fimage.png?alt=media&#x26;token=6d9fb4fc-ee17-474a-9a1d-1efe15e373f7" alt=""><figcaption></figcaption></figure></div>

**\***&#x415;сли нужно задать расширенное форматирование выходного документа, оптимально использовать кастомную таблицу css. Для этого используем сервис <https://styles.oxygenxml.com/>:

**1.** Задаём нужные параметры форматирования выходного документа и нажимаем **Downloads**.

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FKwCcf7X5f9XP0UJ3g8PO%2Fimage.png?alt=media&#x26;token=c89c7ba6-4fda-4970-ba43-1510b546eaae" alt=""><figcaption></figcaption></figure></div>

**2.** Полученный пакет файлов располагаем в новом каталоге **custom-css** в каталоге проекта.

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2F8dEAfmq3NxnToQT8Mcpz%2Fimage.png?alt=media&#x26;token=03437870-b044-4138-8506-1df75171ba65" alt=""><figcaption></figcaption></figure></div>

**3.**&#x41E;ткрываем файл styles.css и после интеграций, но до параметров заголовков вставляем код:

```xml
*[class ~= "toc/title"][empty]:before {
  content: "Содержание";
}
```

&#x20;![](https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FHNOEaaW9SHOoij1VWAEv%2Fimage.png?alt=media\&token=b80a4283-a111-4ce0-a06c-2f03e41d0c78)

**Это необходимо, чтобы задать своё название странице с содержанием (по умолчанию она называется Contents).**