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

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>