DITA features in the documentation

The 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 <parmname>transtype</parmname>. 
    Use the same values as for the <parmname>transtype</parmname> build parameter,
    for example, <option>html5</option> or <option>pdf</option>.</p>
</li>

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"/>
  </subjectdef>

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 Building output:

  <topicref href="using-dita-command.dita" keys="first-build-using-dita-command" locktitle="yes">
    <topicmeta>
      <navtitle>Building output</navtitle>
    </topicmeta>
    <ditavalref href="../resources/novice.ditaval">
      <ditavalmeta>
        <dvrResourcePrefix>first-build-</dvrResourcePrefix>
      </ditavalmeta>
    </ditavalref>
  </topicref>

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">
    <topicmeta>
      <navtitle>Using the <cmdname>dita</cmdname> command</navtitle>
    </topicmeta>
    <ditavalref href="../resources/expert.ditaval">
      <ditavalmeta>
        <dvrResourcePrefix>build-</dvrResourcePrefix>
      </ditavalmeta>
    </ditavalref>

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">
  <pt>
    <parmname>args.csspath</parmname>
  </pt>
  <pd conaction="pushreplace" conref="parameters-html5.dita#html5/args.csspath.desc">
    <div conref="./ant-parameters-details.dita#base-html/args.csspath.desc"/>
  </pd>
  <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"/>
  </pd>
</plentry>

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

Tip: 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">
    <topicmeta>
      <keywords>
        <keyword>3.0.3</keyword>
      </keywords>
    </topicmeta>
  </keydef>

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>. […]
</li>

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