Home
Language reference: All-inclusive edition
The language reference portion of the DITA specification contains a topic for each DITA element. The topic defines the element, its inheritance hierarchy, and provides examples of usage. This portion of the DITA specification also includes information about DITA attributes.
Technical content elements
Elements in the technical content section include the original Concept, Task, and Reference specializations, as well as specializations added in later releases. It also includes domains designed primarily for technical content.
Glossary elements
Glossary elements include those elements designed to specify terms and their definitions, as well as elements that are designed to group, reference, or otherwise make use of information in the glossentry topic.
Glossentry elements
Use the glossary entry topic type to define glossary terms. Each glossentry topic should define a single sense of a term.
<glossSurfaceForm>
The <glossSurfaceForm> element specifies an unambiguous presentation of the <glossterm> that might combine multiple forms. The surface form is suitable to introduce the term in new contexts.

Specification URIs
Notices
Introduction to DITA 1.3
The Darwin Information Typing Architecture (DITA) specification defines a set of document types for authoring and organizing topic-oriented information, as well as a set of mechanisms for combining, extending, and constraining document types.
Architectural specification: All-inclusive edition
The architectural specification portion of the DITA specification outlines the framework of DITA. It contains an overview of DITA markup; addressing; processing; configuration, specialization, generalization, and constraints; as well as information about coding DITA grammar files.
Language reference: All-inclusive edition
The language reference portion of the DITA specification contains a topic for each DITA element. The topic defines the element, its inheritance hierarchy, and provides examples of usage. This portion of the DITA specification also includes information about DITA attributes.
- Element quick reference
  This section contains a listing of DITA elements.
- Topic elements
  The base topic elements include elements that make up the core building blocks of the DITA topic, such as topic, body, and related-links, as well as elements like <p> and <ph> that are used in many topic specializations. Some of these elements are also available inside the <topicmeta> map element.
- Map elements
  Map elements include the core components of DITA maps, such as <topicref> and <reltable>, as well as general purpose map specializations in the map group domain.
- Metadata elements
  Metadata elements include information that is located within the <topicmeta> element (in maps) or <prolog> element (in topics), as well as indexing elements that can be placed in additional locations within topic content.
- Domain elements
  General purpose domains are not specific to any type of information, such as the hazard statement domain that provides elements for describing hazardous situations.
- Classification elements
  Classification elements support managing metadata. Those in the subject scheme map are used to define controlled values and to bind the controlled values to DITA attributes as enumerations. Those declared in the classification domain are used in other maps to classify content according to the scheme.
- Specialization elements
  Several DITA elements exist either for architectural reasons or for support of specialized markup yet to be designed. Although there is little need to use these elements unless you are directed to, some of them, such as <state>, can be used if your content makes use of these semantic distinctions. For example, a discussion of signals on a gate of an integrated logic circuit might use the <state> element to represent either on or off conditions of that gate.
- Legacy conversion elements
  Conversion elements exist primarily to aid in the conversion of content to DITA.
- DITAVAL elements
  A conditional processing profile (DITAVAL file) is used to identify which values are to be used for conditional processing during a particular output, build, or some other purpose. The profile should have an extension of .ditaval.
- Technical content elements
  Elements in the technical content section include the original Concept, Task, and Reference specializations, as well as specializations added in later releases. It also includes domains designed primarily for technical content.
  - Concept elements
    DITA concept topics answer "What is..." questions. Use the concept topic to introduce the background or overview information for tasks or reference topics. The concept topic restricts content following a section or example to other sections or examples. For more details on when to use concept and other information types, please refer to the DITA architectural specification.
  - Task elements
    Task topics answer "How do I?" questions, and have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. Use the task topic to describe the steps of a particular task, or to provide an overview of a higher-level task. The task topic includes sections for describing the context, prerequisites, actual steps, expected results, example, and expected next steps for a task. For more details on when to use task and other information types, please refer to the DITA architectural specification.
  - 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.
  - Troubleshooting elements
    Troubleshooting topics document corrective action such as troubleshooting or alarm clearing.
  - Glossary elements
    Glossary elements include those elements designed to specify terms and their definitions, as well as elements that are designed to group, reference, or otherwise make use of information in the glossentry topic.
    - Glossentry elements
      Use the glossary entry topic type to define glossary terms. Each glossentry topic should define a single sense of a term.
      - <glossentry>
        The <glossentry> element defines a single sense of a glossary term. Glossary entries for different term senses can be reused independently of one another.
      - <glossterm>
        The <glossterm> element specifies the preferred term that is associated with a definition of a sense. If the same term has multiple senses, create a separate <glossentry> topic for each sense.
      - <glossdef>
        The <glossdef> element specifies the definition of one sense of a term. If a term has multiple senses, create a separate <glossentry> topic to define each sense.
      - <glossAbbreviation>
        The <glossAbbreviation> element provides an abbreviated form of the term that is contained in a <glossterm> element.
      - <glossAcronym>
        The <glossAcronym> element defines an acronym for the term that is defined in the <glossterm> element.
      - <glossAlt>
        The <glossAlt> element contains a variant term for the preferred term. The variant should have the same meaning as the term in the <glossterm> element; the variant is simply another way to refer to the same term. There might be many ways to refer to a term; each variant is placed in its own <glossAlt> element. The <glossUsage> element can be used within <glossAlt> to indicate when use of the alternate term is appropriate.
      - <glossAlternateFor>
        The <glossAlternateFor> element indicates when a variant term has a relationship to another variant term in addition to the preferred term.
      - <glossBody>
        The <glossBody> element is used to provide details about a glossary term (such as part of speech or additional forms of the term).
      - <glossPartOfSpeech>
        The <glossPartOfSpeech> element identifies the part of speech for the preferred and alternate terms. Alternate terms must have the same part of speech as the preferred term, because all terms in the <glossentry> topic designate the same subject.
      - <glossProperty>
        The <glossProperty> element is a specialization of the <data> element. You can use it to specify additional details about the preferred term or its subject, for example, the gender of a noun.
      - <glossScopeNote>
        The <glossScopeNote> element contains a clarification of the subject that is designated by the <glossterm>, such as examples of included or excluded companies or products. For instance, a scope note for "Linux" might explain that the term doe not apply to UNIX products; it might give examples of Linux products that are included as well as UNIX products that are excluded.
      - <glossShortForm>
        The <glossShortForm> element provides a shorter alternative to the primary term that is specified in the <glossterm> element.
      - <glossStatus>
        The <glossStatus> element identifies the usage status of a preferred or alternate term. If the status isn't specified, the <glossterm> provides a preferred term and an alternate term provides an allowed term.
      - <glossSurfaceForm>
        The <glossSurfaceForm> element specifies an unambiguous presentation of the <glossterm> that might combine multiple forms. The surface form is suitable to introduce the term in new contexts.
      - <glossSymbol>
        The <glossSymbol> element identifies a standard image that is associated with the subject of the <glossterm> element.
      - <glossSynonym>
        The <glossSynonym> element provides a term that is a synonym of the primary value in the <glossterm> element.
      - <glossUsage>
        The <glossUsage> element provides information about the correct use of a term, such as where or how it can be used.
    - Glossary related elements
      Elements related to the glossary specialization are not defined as part of the glossary topic type, but are often used in conjunction with those elements.
  - Bookmap elements
    Elements in the bookmap section are used to organize DITA content into book form. They include elements for dividing up content, such as chapter and appendix, as well as metadata specific to publishing.
  - Technical-content domains elements
    Domains in this section include those generally associated with technical content, such as the programming and software domains.
- Learning and training elements
  Elements in the learning and training section include specialized topics, maps, content, and metadata elements specially designed to support instructional content.
- Attributes
  This section collects commonly used attributes, with common definitions. If an element uses a different definition, or narrows the scope of, an otherwise common attribute, it will be called out in the topic that defines the element.
Conformance
Conformance to the DITA specification allows documents and document types that are used with different processors or different versions of a processor to produce the same or similar results with little or no reimplementation or modification.
Acknowledgments
(Non-normative) Many members of the OASIS DITA Technical Committee participated in the creation of this specification and are gratefully acknowledged.
Non-normative information
This section contains non-normative information, including topics about new features in DITA 1.3 and migrating from DITA 1.2 to DITA 1.3.
Content models for learning and training package
For each element in the learning and training package, this section presents the content model and a list of parent elements that can contain that element.

`<glossSurfaceForm>`

The <glossSurfaceForm> element specifies an unambiguous presentation of the <glossterm> that might combine multiple forms. The surface form is suitable to introduce the term in new contexts.

The <glossSurfaceForm> element is most often used for terms that also specify the <glossAcronym> element. In that context, the <glossSurfaceForm> element contains the term in a manner that introduces both the term and the acronym, so that later references to the term can be replaced with the acronym alone. See the <abbreviated-form> element for a full description of how the surface form is used together with acronyms.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- topic/p concept/p glossentry/glossSurfaceForm

Example

The following topic defines the term "Anti-lock Braking System". Within the topic, the <glossSurfaceForm> element provides a version of the term that combines both the primary term and the acronym. This allows references to the topic from <abbreviated-form> to different versions of the term in different contexts.

<glossentry id="abs">
  <glossterm>Anti-lock Braking System</glossterm>
  <glossBody>
    <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>ABS</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

Attributes

The following attributes are available on this element: Universal attribute group and outputclass.