DITA features in the documentation

Subject schemes

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

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

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.

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:

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

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:

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:

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

XML mention domain

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

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