2.2.2.2 Reference topic

The purpose of the reference information type

Reference topics that provide data in support of the performance of a task. Reference topics may provide lists and tables that include product specifications, parts lists, constraints on use or performance, and other data that is often “looked up” rather than memorized. A reference topic may also describe regular constituents of a subject or product, such as 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 may hold any subject matter that has regular content, such as ingredients for food in recipes, bibliographic lists, catalogue 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 holds the main body-level elements of the reference topic. Reference topics limit the body to tables (both simple and complex), 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.

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. However, once an author decides to incorporate a section, example, property list, or syntax section in the <refbody>, only additional sections, examples, property lists, or syntax sections are allowed. Simple and complex tables may appear within sections, examples, and syntax sections. They may not appear within the property list or simple or complex table sections. Sections, examples, syntax sections, table subdivisions, and property lists may not nest, meaning that only one level of subdivision is permitted in the reference topic.

The sections of 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 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 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.

Modules

The following DITA modules are provided for the reference topic.

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