Reference topic

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

version
1.3
author
OASIS DITA Technical Committee

Reference topics are specialized from topic. They contain the standard topic elements, including title, short descriptions or abstract, prolog, a body, and related links.

Purpose of the reference topic

Reference topics provide data that supports users as they perform a task. Reference topics might provide lists and tables that include product specifications, parts lists, and other data that is often “looked up” rather than memorized. A reference topic also can describe commands in a programming language or required tools for a series of maintenance tasks.

Reference topics provide quick access to fact-based information. In technical information, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as the commands in a programming language. Reference topics can contain any subject matter that has regular content, such as ingredients for food in recipes, bibliographic lists, catalog items, and so on.

The structure of the reference topic

The top-level element for a reference topic is the reference element.

The refbody element contains the main body-level elements of the reference topic. Reference topics limit the body to tables (both simple and complex), property lists, syntax sections, generic sections, and examples.

All of the elements of refbody are optional; they can appear in any sequence and number.

Limitations on the reference body

The refbody provides for an unlimited number of subdivisions in the form of sections, examples, syntax sections, property lists, and tables. Simple and complex tables can appear within sections, examples, and syntax sections. They cannot appear within the property list or simple or complex table sections. Sections, examples, syntax sections, table subdivisions, and property lists cannot nest; only one level of subdivision is permitted in the reference topic.

The elements in the reference body

section
Represents an organizational division in a reference topic. Sections organize subsets of information within a larger topic. You can only include a simple list of peer sections in a topic; sections cannot be nested. A section might have an optional title.
refsyn
Contains syntax or signature content (for example, a command-line utility's calling syntax or an API's signature). The refsyn contains a brief, possibly diagrammatic description of the subject's interface or high-level structure.
example
Provides examples that illustrate or support the current topic. The example element has the same content model as section.
table
Organizes information according into a rows and columns. Table markup also allows for more complex structures, including spanning rows and columns, as well as table captions.
simpletable
Holds information in regular rows and columns and does not allow a caption.
properties
Lists properties of a subject and their types, values, and descriptions.
Following is an example of a simple reference topic, including the refsyn element.
<reference id="boldproperty">
<title>Bold property</title>
<shortdesc>(Read-write) Whether to use a bold font for the specified text string.</shortdesc>
<refbody>
  <refsyn>
    <synph>
      <var>object</var><delim>.</delim><kwd>Font</kwd><delim>.</delim>
      <kwd>Bold</kwd><delim> = </delim><var>trueorfalse</var>
    </synph>
  </refsyn>
  <properties>
    <property>
      <proptype>Data type</proptype>
      <propvalue>Boolean</propvalue>
    </property>
    <property>
      <proptype>Legal values</proptype>
      <propvalue>True (1) or False (0)</propvalue>
    </property>
  </properties>
</refbody>
</reference>
Following is an example of a simple reference topic, including the property element.
<reference id="oiltypes">
  <title>Oil Types</title>
  <shortdesc>The tables provide the recommended oil types.</shortdesc>
  <refbody>
    <properties>
      <prophead>
        <proptypehd>Oil type</proptypehd>
        <propvaluehd>Oil brand</propvaluehd>
        <propdeschd>Appropriate use</propdeschd>
      </prophead>
      <property>
        <proptype>Primary oil</proptype>
        <propvalue>A1X<propvalue>
        <propdesc>Appropriate for one-cylinder engines</propdesc>
      </property>
      <property>
        <proptype>Secondary oil</proptype>
        <propvalue>B2Z</propvalue>
        <propdesc>Appropriate for two-cylinder engines</propdesc>
      </property>
    </properties>
  </refbody>
</reference>