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.
About the DITA specification: Overview
The DITA specification is delivered in three editions that are optimized for different audiences. Each edition consists of a written specification, XML grammar files, and DITA source.
About the DITA specification: Base edition
The base edition of the DITA specification is the smallest edition. It is designed for application developers and users who need only the most fundamental pieces of the DITA framework.
About the DITA specification: Technical content edition
The technical content edition of the DITA specification is the medium-sized edition. It is designed for users who use information typing and document complex applications and devices, such as software, hardware, medical devices, machinery, and more.
About the DITA specification: All-inclusive edition
The all-inclusive edition of the DITA specification is the largest edition. It is designed for implementers who want all OASIS-approved specializations, as well as users who develop learning and training materials.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT, "RECOMMEND", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].
Non-normative references are references to external documents or resources that implementers of DITA might find useful.
Formatting conventions in the XHTML version of the specification
Given the size and complexity of the specification, it is not generated as a single XHTML file. Instead, each DITA topic is rendered as a separate XHTML file. The XHTML version of the specification uses certain formatting conventions to aid readers in navigating through the specification and locating material easily: Link previews and navigation links.
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.
Introduction to DITA
The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. While DITA historically has been driven by the requirements of large-scale technical documentation authoring, management, and delivery, it is a standard that is applicable to any kind of publication or information that might be presented to readers, including interactive training and educational materials, standards, reports, business documents, trade books, travel and nature guides, and more.
Topics and maps are the basic building blocks of the Darwin Information Typing Architecture (DITA). Metadata attributes and values can be added to DITA topics and maps, as well as to elements within topics, to allow for conditional publishing and content reuse.
DITA provides two addressing mechanisms. DITA addresses either are direct URI-based addresses, or they are indirect key-based addresses. Within DITA documents, individual elements are addressed by unique identifiers specified on the @id attribute. DITA defines two fragment-identifier syntaxes; one is the full fragment-identifier syntax, and the other is an abbreviated fragment-identifier syntax that can be used when addressing non-topic elements from within the same topic.
DITA processing is affected by a number of factors, including attributes that indicate the set of vocabulary and constraint modules on which a DITA document depends; navigation; linking; content reuse (using direct or indirect addressing); conditional processing; branch filtering; chunking; and more. In addition, translation of DITA content is expedited through the use of the @dir, @translate, and @xml:lang attributes, and the <index-sort-as> element.
Configuration, specialization, generalization, and constraints
The extension facilities of DITA allow existing vocabulary and constraint modules to be combined to create specific DITA document types. Vocabulary modules also can be specialized to meet requirements that are not satisfied by existing markup.
Coding practices for DITA grammar files
This section collects all of the rules for creating modular DTD, RELAX NG, or XML Schema grammar files to represent DITA document types, specializations, and constraints.
Technical content specializations
This section contains information about the technical content specializations. It includes a summary of the document types and domains, as well as information about how the technical content specializations support authoring troubleshooting information.
Learning and training specializations
The section contains information about the learning and training specializations: Challenges faced by developers of instructional content; use cases; objectives of the specializations; information about the reusable learning-objects approach to learning and training content; summary of the topic types and domains; and more.
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.
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 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 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.
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 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.
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.
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 the Bookmap and Glossary specializations added with DITA 1.1. It also includes domains designed primarily for technical content, such as the task requirements 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.
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 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.
(Non-normative) Many members of the OASIS DITA Technical Committee participated in the creation of this specification and are gratefully acknowledged.
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.
About the specification source
The DITA specification is authored in DITA. It is a complex document that uses many DITA features, including key references (keyrefs), content references (conrefs), and controlled values set in a subject scheme map.
Changes from previous versions
The following topics outline the changes from earlier versions of DITA to the current version. Each version of the DITA specification is designed to be backwards-compatible with applications that conform to earlier versions of the DITA specification.
File naming conventions
The DITA OASIS Technical Committee uses certain conventions for the names of XML grammar files. We suggest using these conventions as a best practice to facilitate interchange of grammar files.
Migrating to new versions of DITA
DITA 1.3 is compatible with prior versions of the DITA specification; all valid DITA 1.0, 1.1, and 1.2 documents are valid DITA 1.3 documents. However, some changes to existing document-type shells and specializations might be needed in order to maintain the same behavior under DITA 1.3 or to take full advantage of new DITA 1.3 features.
Considerations for generalizing
The <foreign> element can contain a mixture of DITA and non-DITA content. Non-DITA content that is contained within a <foreign> element cannot be generalized. However, the <foreign> element itself, as well as any DITA elements that it contains, can be generalized using normal rules.
Element-by-element recommendations for translators: Base editionTechnical content editionAll-inclusive edition
This topic contains a list of all OASIS DITA elements that are available in the edition. It includes recommendations on how to present the element type to translators, whether the element contents are likely to be suitable for translation, and whether the element has attributes whose values are likely to be suitable for translation. Examples of content that is not suitable for translation include code fragments and mailing addresses.
DTD public identifiers
Each document-type shell (.dtd file) or module component (.mod or .ent file) has a public identifier. The public identifier can reference either the latest version or a specific version of the document-type shell or module component.
XML Schema catalog identifiers
Each Schema document must be uniquely identified using a Uniform Resource Name (URN). Each Schema document has a version-independent as well as a version-specific URN.
Domains and constraints in the OASIS specification
This section provides a summary of the domains and constraints that are available as part of the OASIS specification, as well as a summary of how they are used.
Processing interoperability considerations
The DITA specification does not require processors to perform filtering, content reference resolution, key space construction, and other processing related to base DITA semantics in any particular order. This means that different conforming DITA processors might produce different results for the same initial data set and filtering conditions. DITA users and DITA implementers need to be aware of these potential differences in behavior when DITA content will be processed by different processors.
Specialization design, customization, and the limits of specialization
DITA specialization imposes certain restrictions. An inherent challenge in designing DITA vocabulary modules and document types is understanding how to satisfy markup requirements within those restrictions and, when the requirements cannot be met by a design that fully conforms to the DITA architecture, how to create customized document types that diverge from the DITA standard as little as possible.
For each element in the all-inclusive edition, this section presents the content model and a list of parent elements that can contain that element.
Content models for elements beginning with "a".
Content models for elements beginning with "b".
Content models for elements beginning with "c".
Content models for elements beginning with "d".
Content models for elements beginning with "e".
Content models for elements beginning with "f".
Content models for elements beginning with "g".
Content models for elements beginning with "h".
Content models for elements beginning with "i".
Content models for elements beginning with "k".
Content models for elements beginning with "l".
Content models for elements beginning with "m".
Content models for elements beginning with "n".
Content models for elements beginning with "o".
Content models for elements beginning with "p".
Content models for elements beginning with "q".
Content models for elements beginning with "r".
Content models for elements beginning with "s".
Content models for elements beginning with "t".
Content models for elements beginning with "u".
Content models for elements beginning with "v".
Content models for elements beginning with "w".
Content models for elements beginning with "x".
Content models for elements beginning with "y".