Reference

Reference topics contain reference information that users might need to consult occasionally, for example, product specifications, part lists, API calls, and programming language commands.

Purpose and usage

Reference topics serve the following purposes:

Provide data that supports users as they perform a task
Provide quick access to fact-based information
Contain detailed information that users look up infrequently

Reference topics are used for the following types of information and more:

API documentation
Bibliographies
Configuration file options
Catalogs
Element references
Lists of equipment, ingredients, parts, and tools
Specifications
Syntax diagrams and explanations

Content model

The body of a reference topic can contain the following document structures:

Examples: <example>
Property lists: <properties>
Reference body divisions: <refbodydiv>
Sections: <section>
Syntax sections: <refsyn>
Tables: <simpletable> and <table>

These structures can appear in any order or combination. However, basic document structure such as paragraphs, lists, and figures cannot be placed directly in the body of the reference topic. They must be contained within one of the structures listed above.

Example

This section is non-normative.

The following code sample contains a simple reference topic:

<reference id="oil-types">
  <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>One-cylinder engines</propdesc>
      </property>
      <property>
        <proptype>Secondary oil</proptype>
        <propvalue>B2Z</propvalue>
        <propdesc>Two-cylinder engines</propdesc>
      </property>
    </properties>
  </refbody>
</reference>