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.
Technical-content domains elements
Domains in this section include those generally associated with technical content, such as the programming and software domains.
Programming elements
The programming domain elements are used to define the syntax for programming languages. They also can be used to provide examples.
groupchoice
The <groupchoice> element is part of the subset of elements that define syntax diagrams in DITA. A group is a logical set of pieces of syntax that go together. A group choice specifies that the user must make a choice about which part of the syntax to use. Groups are often nested. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.

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.
  - 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.
    - Equation domain elements
      The elements in the equation domain enable authors to clearly distinguish equations from other type of content. These markup distinctions can enable formatting distinctions, numbering of equations, and more. This domain can be used independently of the MathML domain.
    - Markup domain
      The markup domain elements are used for the mention of named constructs in markup languages, such as XML.
    - MathML domain elements
      The MathML domain elements enable direct use of MathML markup within DITA documents, as well as use-by-reference of MathML markup that is stored separate, non-DITA documents. MathML is a W3C standard.
    - Programming elements
      The programming domain elements are used to define the syntax for programming languages. They also can be used to provide examples.
      - apiname
        The <apiname> element provides the name of an application programming interface (API) such as a Java class name or method name. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - codeblock
        The <codeblock> element represents lines of program code. Like the <pre> element, line endings and spaces inside the element are preserved, and the content is typically rendered in a monospaced font. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - codeph
        The <codeph> element represents a snippet of code within the main flow of text. The code phrase is displayed in a monospaced font for emphasis. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - coderef
        The <coderef> element references an external file that contains literal code. When evaluated, the <coderef> element causes the target code to be displayed inline. If the target contains non-XML characters such as '<' or '&', those will need to be handled in a way that they can be displayed correctly by the final rendering engine. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - option
        The <option> element describes an option that can be used to modify a command (or something else, like a configuration). This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - parmname
        The <parmname> element is used to reference the name of an application programming interface parameter within the text flow of a topic. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - parml
        The <parml> element contains a list of terms and definitions that describes the parameters in an application programming interface. This is a special kind of definition list that is designed for documenting programming parameters. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - plentry
        The <plentry> element contains one or more parameter terms and definitions (<pt> and <pd>). This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - pt
        The <pt> element specifies a parameter term within a parameter list entry. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - pd
        The <pd> element specifies a parameter definition within a parameter list entry. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - synph
        The <synph> (syntax phrase) element is a container for syntax definition elements. It is used when a complete syntax diagram is not needed, but some of the syntax elements, such as <kwd>, <oper>, or <delim> are used within the text flow of the topic content. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - syntaxdiagram
        The <syntaxdiagram> element is the main container for all the syntax elements that make up a syntax definition. The syntax diagram represents the syntax of a statement from a computer language or a command, function call, or programming language statement. Traditionally, the syntax diagram is formatted with "railroad tracks" that connect the units of the syntax together, but the presentation might differ depending on the output media. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - groupseq
        The <groupseq> element is part of the subset of elements that define syntax diagrams in DITA. A group is a logical set of pieces of syntax that go together. Within the syntax definition, groups of keywords, delimiters and other syntax units act as a combined unit, and they occur in a specific sequence, as delimited by the <groupseq> element. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - groupchoice
        The <groupchoice> element is part of the subset of elements that define syntax diagrams in DITA. A group is a logical set of pieces of syntax that go together. A group choice specifies that the user must make a choice about which part of the syntax to use. Groups are often nested. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - groupcomp
        The <groupcomp> element is part of the subset of elements that define syntax diagrams in DITA. A group is a logical set of pieces of syntax that go together. The group composite means that the items that make up the syntax diagram will be formatted close together rather than being separated by a horizontal or vertical line, which is the usual formatting method. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - fragment
        The <fragment> element contains a labeled subpart of the syntax within a <syntaxdiagram>. The <fragment> element allows breaking out logical chunks of a large syntax diagram into named fragments. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - fragref
        The <fragref> element provides a logical reference to a <fragment> element within a syntax diagram, so that you can reference a syntax fragment multiple times or pull a large section of syntax out of line for easier reading. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - synblk
        The <synblk> (syntax block) element organizes small pieces of a syntax definition into a larger piece. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - synnote
        The <synnote> element contains a note (similar to a footnote) within a syntax definition group or fragment. The syntax note explains aspects of the syntax that cannot be expressed in the markup itself. The note will appear at the bottom of the syntax diagram instead of at the bottom of the page. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - synnoteref
        The <synnoteref> element references a syntax note element (<synnote>) that has already been defined elsewhere in the syntax diagram. The same notation can be used in more than one syntax definition. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - kwd
        The <kwd> element defines a keyword within a syntax diagram. A keyword is typed or output, either by the user or application, exactly as specified in the syntax definition. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - var
        The <var> element defines a variable within a syntax diagram for which the user must supply content, such as their user name or password. Processors typically represent the <var> element in output in an italic font, but are not required to do so. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - oper
        The <oper> element defines an operator within a syntax definition. Typical operators are equals (=), plus (+) or multiply (*). This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - delim
        The <delim> element defines a character marking the beginning or end of a section within a syntax diagram. Typical delimiter characters are the parenthesis, comma, tab, vertical bar or other special characters. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - sep
        The <sep> element defines a separator character that is inline with the content of a syntax diagram. The separator occurs between keywords, operators or groups in a syntax definition. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
      - repsep
        The <repsep> element provides a repeat separator character within a syntax diagram to indicate that a group of syntax elements can (or should) be repeated. If the <repsep> element contains a separator character such as a plus (+), this indicates that the character must be used between repetitions of the syntax elements. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.
    - Release-management domain elements
      The release-management domain elements contain human-authored information about the changes that have been made to a DITA topic or map. A processor can retrieve this information and use it to assemble documents or topics that contain release note information.
    - Software elements
      The software domain elements are used to describe the operation of a software program.
    - SVG elements
      The SVG domain elements enable direct use of SVG markup within DITA documents, as well as use-by-reference of SVG markup that is stored in separate non-DITA documents. SVG is a W3C standard.
    - Task requirements domain
      The task requirements domain contains elements for use in describing tasks that involve machines or other pieces of hardware.
    - User interface elements
      The user interface domain elements are used to describe the user interface of a software program.
    - XML mention domain
      Use the XML-mention domain elements for mentions of named XML constructs, including elements, attributes, entities, processing instructions, and document-type declaration components. These elements enable specific typographic effects for different construct types, precise search and retrieval of specific constructs, and automatic indexing of different constructs. This domain is intended to support the description and documentation of XML document types and XML applications.
    - xNAL domain elements
      The xNAL domain elements represent a subset of the Extensible Name and Address Standard. It is used to encode information about the author or authors of DITA information. The domain can be included in any DITA document type shell that requires additional metadata for names and addresses, although the implementations provided by OASIS only include it in the bookmap document type.
- 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.

`<groupchoice>`

The <groupchoice> element is part of the subset of elements that define syntax diagrams in DITA. A group is a logical set of pieces of syntax that go together. A group choice specifies that the user must make a choice about which part of the syntax to use. Groups are often nested. This element is part of the DITA programming domain, a special set of DITA elements designed to document programming tasks, concepts, and reference information.

Content models

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

Inheritance

+ topic/figgroup pr-d/groupchoice

Example

<syntaxdiagram frame="bottom">
 <title>CopyFile</title>
 <groupseq><kwd>COPYF</kwd></groupseq>
 <groupcomp><var>input-filename</var><kwd>*INFILE</kwd></groupcomp>
 <groupseq><var>output-filename</var><kwd>*OUTFILE</kwd></groupseq>
 <groupchoice><var>input-filename</var><kwd>*INFILE</kwd></groupchoice>
 <groupchoice><var>output-filename</var><kwd>*OUTFILE</kwd></groupchoice>
</syntaxdiagram>

Attributes

The following attributes are available on this element: Universal attribute group (with a narrowed definition of @importance, given below) and outputclass.

@importance

The attribute indicates whether this item in a syntax diagram is optional, required, or default. Output processors can indicate this designation in a generated diagram. Allowable values are:

optional: This section of the syntax is optional.
required: This section of the syntax is required.
default: This section of the syntax is used by default or has this default value.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.