Reference topic

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.