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:

Draft comment: Kristen J Eberlein 26 October 2022

TODO: While the following code sample is a perfectly reasonable example of a properties list, I think we could provide a better example of a reference topic.

Draft comment: robander
TO RESOLVE 18 May 2026: If someone wants to make a better one, that's great, otherwise leave it alone and move on.

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