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). 
    Use the same values available for the <parmname>transtype</parmname> 
    build parameter, for example, <codeph>html5</codeph> or <codeph>pdf</codeph>.
  </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

The Getting Started section pulls a subset of the build description from the User Guide, filtered to display only content deemed suitable for novice users under Building output using the dita command:

<topicref href="../user-guide/using-dita-command.dita" 
  copy-to="using-dita-command.dita" keys="first-build-using-dita-command">
  <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 the User Guide with additional information on arguments, options and examples (see Using the dita command).

Conref push

The docs build uses the conref push mechanism (specifically @conaction="pushafter") to extend the parameter descriptions embedded in the default plug-ins:

<plentry id="args.csspath">
  <pt>
    <parmname>args.csspath</parmname>
  </pt>
  <pd conaction="mark" 
      conref="parameters-base-html.dita#base-html/args.csspath.desc"/>
  <pd conaction="pushafter" audience="xslt-customizer">
    Corresponds to the XSLT parameter <parmname>CSSPATH</parmname>. 
    DITA-OT will copy the file to this location.</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>2.3.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