code-srv-test/dita-ot-3.6/docsrc/reference/docs-dita-features.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
<concept id="ID">
  <title>DITA features in the documentation</title>
  <titlealts>
    <navtitle>DITA features in docs</navtitle>
  </titlealts>
  <shortdesc>DITA Open Toolkit uses various recent DITA features in the project documentation.</shortdesc>
  <prolog>
    <metadata>
      <keywords>
        <indexterm><xmlatt>audience</xmlatt></indexterm>
        <indexterm><xmlatt>orient</xmlatt></indexterm>
        <indexterm>profiling</indexterm>
        <indexterm>branch filters</indexterm>
        <indexterm>Antenna House
          <indexterm>DITA XML mention domain</indexterm></indexterm>
        <indexterm>DITA 1.3
          <indexterm>XML mention domain</indexterm></indexterm>
      </keywords>
    </metadata>
  </prolog>
  <conbody>
    <p>The
      <xref href="https://github.com/dita-ot/docs" format="html" scope="external">source files</xref> for the DITA-OT
      documentation include examples of the following DITA features (among others):</p>
    <ul>
      <li>subjectScheme classification for controlling available attributes</li>
      <li>profiling and branch filtering (novice/expert content)</li>
      <li>extending topics with conref push</li>
      <li>keys and key references</li>
      <li>XML mention domain</li>
    </ul>

    <section>
      <title>Subject schemes </title>
      <p>Various topics, sections and elements in the docs are profiled by audience:</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
            href="../resources/conref-task.dita#token=excerpt-variables,end-excerpt"
          /></codeblock></p>
      <p>An “audience” subject scheme controls the values that are available for the <xmlatt>audience</xmlatt>
        attribute:</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
            href="../resources/subjectscheme.ditamap#token=excerpt-audience,end-excerpt"
          /></codeblock></p>
      <p>A dedicated subject scheme map defines several series of permissible values for <xmlatt>outputclass</xmlatt>
        attributes, which apply styling to elements on the project website, enable
        <xref keyref="extended-functionality">extended codeblock processing</xref> such as whitespace visualization and
        line numbering in PDF output, or trigger
        <xref keyref="html5-code-highlighting"/> via
        <xref keyref="prismjs"/>.</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
            href="../resources/subjectscheme.ditamap#token=excerpt-outputclass,excerpt-audience"
          /></codeblock></p>
    </section>

    <section>
      <title>Branch filtering: re-using profiled content</title>
    </section>
    <section>
      <p><cite>Installing DITA-OT</cite> pulls a subset of the build description from <cite>using the
            <cmdname>dita</cmdname> command</cite>, filtered to display only content deemed suitable for novice users
        under
        <xref keyref="first-build-using-dita-command"/>:</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
            href="../topics/installing.ditamap#token=branch-filter,end-filtering"
          /></codeblock></p>
      <p>The same content appears later in
        <xref keyref="build-using-dita-command"/> with additional information on arguments, options and examples.</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
            href="../topics/publishing.ditamap#token=branch-filter,end-filtering"
          /></codeblock></p>
    </section>

    <section>
      <title>Conref push</title>
    </section>
    <section>
      <p>The docs build uses the conref push mechanism (with the <codeph>pushreplace</codeph>, <codeph>mark</codeph>,
        and <codeph>pushafter</codeph>
        <xref keyref="dita13-spec-conaction">conactions</xref>) to extend the parameter descriptions embedded in the
        default plug-ins:</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
            href="../parameters/ant-parameters-details.dita#token=excerpt-csspath,end-excerpt"
          /></codeblock></p>
      <p>The pushed content appears in the output after the default description. (See
        <xref keyref="parameters-base-html"/>.)</p>
      <note type="tip">You could also use the same mechanism to extend the documentation with custom information that
        applies only to your company’s toolkit distribution.</note>
    </section>

    <section>
      <title>Keys and key references</title>
    </section>
    <section>
      <p>The <codeph>key-definitions.ditamap</codeph> defines keys for version references, re-usable links, etc.</p>
      <p>This key definition defines the maintenance release version:</p>
      <p><codeblock outputclass="language-xml normalize-space"><coderef
            href="../resources/key-definitions.ditamap#token=excerpt-version,end-excerpt"
          /></codeblock></p>
      <p>In topics, the keyword is used in place of hard-coded version references:</p>
      <codeblock
        outputclass="language-xml"
      >&lt;title&gt;DITA Open Toolkit &lt;keyword keyref="maintenance-version"/&gt; Release Notes&lt;/title&gt;</codeblock>
    </section>

    <section>
      <title>XML mention domain</title>
    </section>
    <section>
      <p>The docs use the
        <xref
          format="html"
          href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/containers/xml-mention-domain.html#xml-mention-domain"
          scope="external"
        >XML mention domain</xref> to mark up XML elements and attributes:</p>
      <codeblock outputclass="language-xml">&lt;li id="1777"&gt;
  DITA 1.3: Initial support has been added for the &lt;xmlatt&gt;orient&lt;/xmlatt&gt;
  attribute on &lt;xmlelement&gt;table&lt;/xmlelement&gt; elements. These changes allow
  Antenna House Formatter to render tables in landscape mode when the
  &lt;xmlatt&gt;orient&lt;/xmlatt&gt; attribute is set to &lt;option&gt;land&lt;/option&gt;. […]
&lt;/li&gt;</codeblock>
      <p>When the toolkit generates output for the sample above:</p>
      <ul>
        <li>the XML element name is wrapped in angle brackets as <xmlelement>table</xmlelement>
        </li>
        <li>the attribute name is prefixed with an “at” sign as <xmlatt>orient</xmlatt></li>
      </ul>
    </section>
  </conbody>
</concept>