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

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

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

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

Объяснение карты 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>