Создание карт DITA

Вы можете создавать файлы карт DITA, используя три новых команды qdoc: команду ditamap, команду topicref и команду mapref. Как эти карты DITA будут использоваться автоматически или вручную процессом построения документации, всё ещё рассматривается. Этот раздел будет обновлён по мере принятия решений.

Что такое карта DITA?

Полное описание DITA можно найти на сайте Архитектура типов данных Darwin Information.

Объяснение карты DITA можно найти на этом сайте здесь.

\ditamap

Команда \ditamap предназначена для создания карты DITA с помощью команд qdoc. Команда \ditamap — это своего рода команда \page, которая генерирует файл .ditamap вместо файла .html или .xml. Файл, который создаётся, фактически содержит текстовый XML, но суффикс .ditamap используется для идентификации файла как содержащего карту DITA.

Аргументом является имя создаваемого файла. В следующем примере выводится файл creator.ditamap:

\ditamap creator.ditamap

\topicref \endtopicref

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

У команды \topicref два аргумента. Первый аргумент становится значением атрибута navtitle. Обычно используется заголовок темы, на которую делается ссылка. Этот заголовок часто отображается в таблице содержания, созданной из ditamap.

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

\topicref {QML Module QtQuick 2} {qtquick-2.xml}
  \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
  \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
  \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
\endtopicref

\mapref

Команда \mapref предназначена для создания mapref в ditamap. Mapref ссылается на другую ditamap, которую вы хотите включить в свою ditamap. Как и команда \topicref, команда \mapref имеет два аргумента, но для команды \mapref оба аргумента обязательны. Аргументы по существу такие же, как описано для \topicref, но для \mapref второй аргумент должен быть именем другой ditamap, т.е. он должен иметь суффикс .ditamap. Вы должны указать имя файла. qdoc не может найти имя файла за вас.

\mapref {Creator Manual} {creator-manual.ditamap} \endmapref

Пример страницы Ditamap

В следующем примере используются три описанные выше команды qdoc ditamap.

\ditamap creator.ditamap
\title The DITA Map for Creator

\topicref {QML Module QtQuick 1}
  \topicref {QML Mouse Events} \endtopicref
  \topicref {Property Binding} \endtopicref
\endtopicref

\topicref {QML Module QtQuick 2} {qtquick-2.xml}
  \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
  \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
  \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
\endtopicref

\topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml}
  \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref
\endtopicref

Результат файла Ditamap

Это файл .ditamap, который вы получаете, если вводите показанную выше страницу qdoc ditamap. Обратите внимание, что вы можете создавать файлы ditamap напрямую в XML так же легко, как и с помощью команд qdoc. Выбор за вами.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <topicmeta>
    <shortdesc>The DITA Map for Creator</shortdesc>
  </topicmeta>
  <topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml">
    <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
    <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
  </topicref>
  <topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml">
    <mapref navtitle="Creator Manual" href="creator-manual.ditamap"/>
    <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
    <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
  </topicref>
  <topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml">
    <topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/>
  </topicref>
</map>