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>

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

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">
      <navtitle>Building output</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.)

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

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