DITA features in the documentation

DITA Open Toolkit uses various recent DITA features in the project documentation.

The source files for the DITA-OT documentation include examples of the following DITA features (among others):

  • subjectScheme classification for controlling available attributes
  • profiling and branch filtering (novice/expert content)
  • extending topics with conref push
  • keys and key references
  • XML mention domain

Subject schemes

Various topics, sections and elements in the docs are profiled by audience:

<li id="novice-variables-last" audience="novice">
  <p id="common-format-info">
    <varname>format</varname> is the output format (transformation type). This argument corresponds to the
    common parameter <xref keyref="parameters-base/transtype"/>. Use the same values as for the
      <parmname>transtype</parmname> build parameter, for example <option>html5</option> or

An “audience” subject scheme controls the values that are available for the @audience attribute:

<subjectdef keys="audience">
  <subjectdef keys="novice"/>
  <subjectdef keys="expert"/>
  <subjectdef keys="xslt-customizer"/>

A dedicated subject scheme map defines several series of permissible values for @outputclass attributes, which apply styling to elements on the project website, enable extended codeblock processing such as whitespace visualization and line numbering in PDF output, or trigger HTML5-compliant syntax highlighting via prism.js.

<schemeref href="subjectscheme-outputclass.ditamap"/>

Branch filtering: re-using profiled content

Installing DITA-OT pulls a subset of the build description from using the dita command, filtered to display only content deemed suitable for novice users under First build:

<topicref href="using-dita-command.dita"
          keys="first-build-using-dita-command" locktitle="yes">
    <navtitle>First build</navtitle>
  <ditavalref href="../resources/novice.ditaval">

The same content appears later in Using the dita command with additional information on arguments, options and examples.

<topicref href="using-dita-command.dita"
          keys="build-using-dita-command" locktitle="yes">
    <navtitle>Using the <cmdname>dita</cmdname> command</navtitle>
  <ditavalref href="../resources/expert.ditaval">

Conref push

The docs build uses the conref push mechanism (with the pushreplace, mark, and pushafter conactions) to extend the parameter descriptions embedded in the default plug-ins:

<plentry id="args.csspath">
  <pd conaction="pushreplace" conref="parameters-html5.dita#html5/args.csspath.desc">
    <div conref="./ant-parameters-details.dita#base-html/args.csspath.desc"/>
  <pd conaction="mark" conref="parameters-html5.dita#html5/args.csspath.desc"/>
  <pd conaction="pushafter">
    <div conref="./ant-parameters-details.dita#base-html/args.csspath.details"/>

The pushed content appears in the output after the default description. (See HTML-based output parameters.)

You could also use the same mechanism to extend the documentation with custom information that applies only to your company’s toolkit distribution.

Keys and key references

The key-definitions.ditamap defines keys for version references, re-usable links, etc.

This key definition defines the maintenance release version:

<keydef keys="maintenance-version">

In topics, the keyword is used in place of hard-coded version references:

<title>DITA Open Toolkit <keyword keyref="maintenance-version"/> Release Notes</title>

XML mention domain

The docs use the XML mention domain to mark up XML elements and attributes:

<li id="1777">
  DITA 1.3: Initial support has been added for the <xmlatt>orient</xmlatt>
  attribute on <xmlelement>table</xmlelement> elements. These changes allow
  Antenna House Formatter to render tables in landscape mode when the
  <xmlatt>orient</xmlatt> attribute is set to <option>land</option>. […]

When the toolkit generates output for the sample above:

  • the XML element name is wrapped in angle brackets as <table>
  • the attribute name is prefixed with an “at” sign as @orient