3.2.3 Reference elements

Reference topics describe factual material about a subject, such as the commands in a programming language. This format is also suitable for bibliographies, catalogues, the list of ingredients for recipes, and similar collections of structured descriptive prose. For more details on when to use reference and other information types, please refer to the DITA architectural specification.

• 3.2.3.1 reference
  The <reference> element defines a top-level container for a reference topic. Reference topics document programming constructs or facts about a product. Examples of reference topics include (but are not limited to) product specifications, environmental specifications, equipment lists, parts lists, required tools, language elements, class descriptions, commands, functions, and API information. All of these items provide quick access to facts, but no deeper explanation of related concepts or tasks. Reference topics have the same high-level structure as any other topic type, with a title, short description, and body. Within the body, reference topics are typically organized into one or more sections, property lists, and tables. The reference topic type provides general rules that apply to all kinds of reference information, using elements like <refsyn> for syntax or signatures, and <properties> for lists of properties and values.
• 3.2.3.2 refbody
  The <refbody> element is a container for the main content of the reference topic. Reference topics limit the body structure to tables (both simple and standard), property lists, syntax sections, and generic sections and examples, in any sequence or number.
• 3.2.3.3 refbodydiv
  The <refbodydiv> element is similar to the <bodydiv> element in that it provides an informal container for content that may be grouped within a reference. Reference topics place many restrictions on their content compared to generic topics; the <refbodydiv> element maintains these restrictions by only allowing elements that are already available within the body of a reference. There are no additional semantics attached to the <refbodydiv> element; it is purely a grouping element provided to help organize content.
• 3.2.3.4 refsyn
  The <refsyn> element is a special section inside a reference topic. The section often 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.
• 3.2.3.5 properties
  The <properties> element gives a list of properties for the subject of the current topic, for example whether a class is public or protected. Each property can include the type, value, and a description. The typical rendering is usually in a table-like format. To represent multiple values for a single type, create additional property elements and use only the <propvalue> element (and <propdesc> when needed) for each successive value.
• 3.2.3.6 prophead
  The prophead element supports headings for the properties element.
• 3.2.3.7 proptypehd
  The proptypehd element supports headings for the type column of a properties table.
• 3.2.3.8 propvaluehd
  The propvaluehd element supports headings for the value column of a properties table.
• 3.2.3.9 propdeschd
  The propdeschd element supports headings for the description column of a properties table.
• 3.2.3.10 property
  The <property> element represents a single property of the current topic's subject. For example, if the current reference topic describes a programming class, the property might show that the class is protected rather than public. The <property> element generally appears together with a series of other properties; it contains three optional elements to provide a type, value, or description of the property.
• 3.2.3.11 proptype
  The <proptype> element describes the type of the property.
• 3.2.3.12 propvalue
  The <propvalue> element indicates one or more values for the current property type. Values may be placed separate <property> elements if they need separate descriptions. The <proptype> attribute need not be repeated.
• 3.2.3.13 propdesc
  The <propdesc> element is used to provide a short description of the property type and its listed values.

Return to main page.

DITA v1.2 CD 03
Copyright © OASIS Open 2005, 2010. All Rights Reserved.