Reference

Reference topics describe regular features of a subject or product, such as commands in a programming language.

Why reference?

In technical information, reference topics are often used to cover subjects such as the commands in a programming language. Reference topics can hold anything that has regular content, such as ingredients for food recipes, bibliographic lists, catalogues, and the like. Reference topics provide quick access to facts. Information needed for deeper understanding of a reference topic or to perform related procedures should be provided in a concept or task topic.

Reference structure

The <reference> element defines a top-level container for a reference topic. Reference topics have the same high-level structure as the other core DITA topic types, with a title, short description, and body. Within the body, reference topics organize content into one or more sections, property lists, or tables.

The <refbody> element holds the main content of the reference topic. Reference topics limit the body structure to tables (both simple and standard), property lists, syntax sections, and generic sections and examples.

All of the elements of <refbody> are optional and may appear in any sequence and number.

<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 may 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 containing examples that illustrate or support the current topic. The <example> element has the same content model as <section>.
<table>: Organizes information according into a tabular rows and columns structure. 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 for a caption.
<properties>: Lists properties and their types, values, and descriptions.

Here’s an example of a reference topic.

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

Modules

reference.mod (DTD)
referenceMod.xsd, referenceGrp.xsd (Schema)