Reference elements

Use the reference elements to describe regular features of sets of things, most commonly the commands in a programming language. However, this format is also suitable for recipes, bibliographies, catalogues, 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.

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 language elements, class descriptions, commands, functions, statements, protocols, types, declarators, operands, and API information, which provide quick access to facts, but no explanation of concepts or procedures. 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.
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. 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.
4. 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 type, just create additional property elements and use only the <propvalue> element (and <propdesc> when needed) for each successive value.
5. prophead
   The prophead element supports regular headings for the properties element.
6. proptypehd
   The proptypehd element supports regular headings for the type column of a properties table.
7. propvaluehd
   The propvaluehd element supports regular headings for the value column of a properties table.
8. propdeschd
   The propdeschd element supports regular headings for the description column of a properties table.
9. property
   The <property> element represents a property of the current topic's subject. For example, if the current topic is a class, the property might show that the class is protected rather than public. It contains three optional elements: type, value, and description.
10. proptype
    The proptype element describes the type of property.
11. propvalue
    The <propvalue> element indicates the value or values for the current property type. You can put values in separate rows if they need separate descriptions, and just leave the <proptype> element blank.
12. propdesc
    The <propdesc> element is used to provide a short description of the property type and its listed values (or just the value).

Return to main page.

OASIS DITA Language Specification v1.1 -- Committee Draft 13 February 2007
Copyright © OASIS Open 2005, 2007. All Rights Reserved.