Darwin Information Typing Architecture (DITA) Version 1.2

Notation

The following conventions are used throughout the specification:

attribute types

Attribute names may be preceded by @ to distinguish them from elements or surrounding text, for example, the @props or the @class attribute.

element types

Element names may be delimited with angle brackets (< and >) to distinguish them from surrounding text, for example, the <keyword> and the <prolog> element.

In general, the unqualified use of the term map or topic can be interpreted to mean "a <map> element and any specialization of a <map> element " or "a <topic> element or any specialization of a <topic> element."

Normative and non-normative information

The DITA specification contains normative and non-normative information:

Normative information

Normative information is the formal portion of the specification that describes the rules and requirements that make up the DITA standard and which must be followed.

Non-normative information

Non-normative information includes descriptions that provide background, examples, and other useful information that are not formal requirements or rules that must be followed. The terms non-normative and informative are used interchangeably.

All information in the specification should be considered normative unless it is an example, an appendix, or is explicitly labeled as informative or non-normative. Appendices are always non-normative, unless explicitly stated otherwise. The DITA specification contains examples to help clarify or illustrate specific aspects of the specification. Because examples are specific rather than general, they may not illustrate all aspects or be the only way to accomplish or implement an aspect of the specification. Therefore all examples are non-normative, unless explicitly stated otherwise.

Basic DITA terminology

The following terminology is used to discuss basic DITA concepts:

DITA attribute type

An attribute type that is one of the following:

• One of the base attribute types that are defined by the DITA specification
• A specialization of the either the @base or @props attribute

DITA document

An XML document that conforms to the requirements of this specification. A DITA document must have as its root element one of the following elements:

• <map> or a specialization of the <map> element
• <topic> or a specialization of the <topic> element
• <dita>, which cannot be specialized, but which allows documents with multiple sibling topics

DITA document type

A unique set of structural modules, domain modules, and constraint modules that taken together provide the XML element and attribute declarations that define the structure of DITA documents. DITA document types normally are implemented using DITA document-type shells.

DITA document-type shell

A set of DTD or XSD declarations that implement a DITA document type by using the rules and design patterns that are included in the DITA specification. A DITA document-type shell includes and configures one or more structural modules, zero or more domain modules, and zero or more constraint modules. With the exception of the optional declarations for the <dita> element and its attributes, DITA document-type shells do not declare any element or attribute types directly.

DITA element

An XML element instance whose type is a DITA element type. DITA elements must exhibit a @class attribute that has a value that conforms to the rules for specialization hierarchy specifications.

DITA element type

An element type that is one of the following:

• One of the base element types that are defined by the DITA specification
• A specialization of one of the base element types

A DITA element type is declared in exactly one vocabulary module. DITA element types may only exhibit attributes that are DITA attribute types.

map instance

An occurrence of a map type in a document.

map type

An element type that defines a set of relationships among topic instances. The map type provides the root element and, through the contained element types, the substructure for the map instances. The map substructure provides hierarchy, group, and matrix organization of references to topic instances.

structural type instance

An occurrence of a topic type or a map type in a document.

topic instance

An occurrence of a topic type in a document.

topic type

An element type that defines a complete unit of content. The topic type provides the root element for the topic and, through the contained element types, the substructure for the topic instances. The root element of the topic type is not necessarily the same as the root element of a document type; document types may nest multiple topic types and may also declare non-DITA wrapper elements as the root element for compatibility with other processes.

Specialization terminology

The following terminology is used to discuss DITA specialization:

base content model

The content model of a DITA element before specialization or the application of constraints or extensions.

base type

An element or attribute type that is not a specialization. All base types are defined by the DITA specification.

extension element

Within a vocabulary module, an element type that can be extended, replaced, or constrained for use in a DITA document type.

generalization

The process by which a specialized element is transformed into a less-specialized ancestor element or a specialized attribute is transformed into a less-specialized ancestor attribute. The original specialization-hierarchy information may be preserved in the generalized instance, thus allowing the original specialized type to be recreated from the generalized instance.

restricted content model

For a DITA element type, a content model that has been restricted from the base content model for the element type by one or more of the following mechanisms:

• Removing optional elements
• Requiring optional elements
• Ordering of unordered elements
• Restricting repeatable (but optional) elements from repeating

Content models may be restricted through the use of constraint modules or through specialization.

selective domain extension

An extension that replaces an extension element with element types that are defined in an domain module, thus making the base type unavailable in the DITA document-type shell that configures the extension.

specialization

(1) The act of defining new element or attribute types as a semantic refinement of existing element or attribute types

(2) An element or attribute type that is a specialization of a base type

(3) A process by which a generalized element is transformed into one of its more specialized element types or a generalized attribute is transformed into a more specialized attribute.

specialization hierarchy

The sequence of element or attribute types, from the most general to most specialized, from which a given element or attribute type is specialized. The specialization hierarchy for a DITA element is formally declared through its @class attribute.

specialization parent

For a given DITA element type, the most specialized of its ancestors in its specialization hierarchy.

specialized attribute type

An attribute type that is defined as a semantic refinement of another attribute type. The attribute type must be specialized from either the @base or @props attribute, and its range of permissible values must be a subset of or identical to the values allowed by the original attribute type.

specialized element type

An element type that is defined as a semantic refinement of an existing element type. The content allowed by the specialized element type must be a subset of or identical to the content allowed by the original element type. Within a DITA document, all specialized element types must be refinements of one of the base element types, with the exception of elements that are used in the context of <foreign> or <unknown> elements.

structural type

A topic type or map type.

DITA modules

The following terminology is used to discuss DITA modules:

attribute domain module

A domain module that defines exactly one specialization of either the @base or @props attribute.

constraint module

A set of declarations that imposes additional constraints onto the element or attribute types that are defined in a specific vocabulary module.

domain module

A set of element types or an attribute type that supports a specific subject or functional area. Element types or attribute types in a domain can be integrated with topic types or map types to enhance semantic support for particular kinds of content. For example, the structural type <topic> declares the <keyword> element; when integrated with a domain for describing user interfaces, new keyword specializations (such as <wintitle>) become available wherever <keyword> was allowed in the original structural type.

element domain module

A domain module that defines one or more element types for use within maps or topics.

map module

A structural module that defines a single map type.

structural module

A vocabulary module that defines exactly one top-level map type or topic type. Structural modules may also define specializations of elements from domain modules.

topic module

A structural module that defines a single top-level topic type.

vocabulary module

A uniquely-named unit of element type or attribute type declaration. There are two types of vocabulary modules: structural modules and domain modules. For a given map type, topic type, or domain, there is exactly one vocabulary module that defines it.

The following figure illustrates the relationship between a DITA document, its DITA document-type shell, and the various vocabulary modules that it uses.

Instances, modules, and declarations

Linking and addressing terms

The following terminology is used to discuss linking and addressing terms:

key name

An identifier defined by a value of the @keys attribute. A key is bound to one or more of the following items:

• A resource addressed by the <topicref> element or a specialization of the <topicref> element
• An element contained with the <topicmeta> element of the <topicref> element or a specialization of the<topicref> element

key definition

A <topicref> element or specialization of a <topicref> element that specifies the @keys attribute and defines one or more key names.

key resolution context

The root map that establishes the context for resolving key references. For a given key-resolution instance, there is at most one root map that defines the effective value of the key space, as determined by the key definition precedence rules..

key space

The effective set of unique key names that are defined by a given key resolution context. Within a given key resolution context, a key name has at most one binding.

referenced element

An element that is referenced by another DITA element. See also referencing element.

Example

The following code sample is from the installation-reuse.dita topic. The <step> element that it contains is a referenced element; other DITA topics reference the <step> element by using the @conref attribute.

<step id="run-startcmd-script">
	<cmd>Run the startcmd script that is applicable to your operating-system environment.</cmd>
</step>

referencing element

An element that references another DITA element by specifying an addressing attribute. See also referenced element and addressing attribute

Example

The following <step> element is a referencing element. It uses the @conref attribute to reference a <step> element in the installation-reuse.dita topic.

<step conref="installation-reuse.dita#reuse/run-startcmd-script>
	<cmd/>
</step>

addressing attribute

An attribute, such as @conref, @conkeyref, @keyref, and @href, that specifies an address (a URI reference or a key reference).

Tables of contents (TOCs)

Processors may generate a TOC based on the hierarchy of the <topicref> elements in the DITA map. Each <topicref> element in the map represents a node in the TOC (unless it is set as a "resource only" topic reference). These topic references define a navigation tree. When a map contains a topic reference to a map (often called a map reference), processors should integrate the referenced map's navigation tree with the referencing map's navigation tree at the point of reference. In this way, a deliverable may be compiled from multiple DITA maps.

By default, the text for each node in the TOC is obtained from the referenced topic's title. If the @locktitle attribute on the <topicref> element is set to "yes", the node text must be taken from the @navtitle attribute or <navtitle> child element of the <topicref> element and must not be read from the referenced topic's title. If a <topicref> element contains both a <navtitle> child element and a @navtitle attribute, the @locktitle attribute applies to both <navtitle> and @navtitle and, when set to "yes", the value of the <navtitle> element must be used.

A TOC node is generated for every <topicref> element (or specialization thereof) that references a topic or specifies a navigation title, except in the following cases:

• The @processing-role attribute is specified on the <topicref> element or an ancestor element.
• The @print attribute is specified on the <topicref> element or an ancestor element and the current processing is not for print output.
• Conditional processing is used to filter out this node or an ancestor node.
• No @href or @navtitle attribute is set and no child <navtitle> element exists, or the node is a <topicgroup> element.

To suppress a <topicref> element from appearing in the TOC, set its @toc attribute to "no". The value of the @toc attribute cascades to child <topicref> elements, so if @toc is set to "no" on a particular <topicref>, all of that <topicref>'s children are also excluded from the TOC. If a child <topicref> overrides the cascading TOC node suppression by specifying @toc="yes", then the node that specifies @toc="yes" must appear in the TOC (minus the intermediate nodes that turned off @toc).

Indexing

An index may be generated from index entries occurring in topic bodies, topic prologs, or DITA maps. For more information, see the language reference for the <indexterm> element.

• The @conref or @conkeyref attribute can be used to pull the referenced content into the location of the referencing element. The combination of either of these attributes with the @conrefend attribute can be used to pull the content of a range of elements.

• The @conref attribute can be used in combination with the @conaction attribute to push content from the referencing element to the location of the referenced element.

Pulling content to the referencing element

When the @conref or @conkeyref attribute is used alone, the referencing element acts as a placeholder for the referenced element, and the content of the referenced element is rendered in place of the referencing element.

The combination of the @conrefend attribute with either @conref or @conkeyref specifies a range of sibling elements that is rendered in place of the referencing element. See The conrefend attribute for examples of how to combine @conrefend with either @conref or @conkeyref.

Pushing content from the referencing element

The @conaction attribute reverses the direction of reuse from pull to push. When the @conref or @conkeyref attribute is used in combination with the @conaction attribute, content can be rendered before, after, or in place of the referenced element, depending on the value of the @conaction attribute. See The conaction attribute for more details.

Note

The @conaction and @conrefend attributes cannot both be used within the same referencing element, so it is not possible to push a range of elements.

The identifier for the referenced element must be either absolute or resolvable in the context of the referencing element.

More formally, the DITA @conref attribute can be considered a transclusion mechanism similar to XInclude and to HyTime value references. DITA differs from these mechanisms, however, in that conref validity does not apply simply to the current content at the time of replacement, but to the ranges of possible content given the constraints of both the referencing document type and the referenced document type. DITA compares the constraints of each context to ensure the continued validity of the replacement content in its new context. A conref processor must not permit resolution of a reuse relationship that could be rendered invalid under the rules of either the reused or reusing content.

When pulling content with the conref mechanism – if the referenced element is the same type as the referencing element, and the list of domains declared on the domains attribute in the referenced topic or map instance is the same as or a subset of the list of domains declared in the referencing document, the element set allowed in the referenced element is guaranteed to be the same as, or a subset of, the element set allowed in the referencing element. A processor resolving a conref should tolerate specializations of valid elements and should generalize elements in the pulled content fragment as needed for the referencing context.

When pushing content with the conref mechanism, the domain checking algorithm is reversed. In this case, the domains attribute on the referenced document's topic or map must be the same as or a superset of the domains declared on the referencing document. Once again, a processor resolving a conref should tolerate specializations of valid elements and should generalize elements in the pushed content fragment as needed for the referenced context.

All replacement of content based on @conref occurs after parsing of the document but prior to any styling or other transformational or presentational operations on the full topic.

The referenced element may replace the referencing element based on build-time or runtime conditions. For example, content such as product names or install paths may differ from one product to another. It is advantageous to separate such content from topic content which is reused for more than one product. When the content is reused in a different context, different resources are substituted as reference elements.

A fragment of DITA content, such as an XML document containing only a single paragraph without a topic or map ancestor, does not contain enough information for the conref processor to be able to determine the validity of a reference to it. Consequently, the value of a conref must specify a referenced element within a DITA topic or DITA map (or it may point to the entire topic or map).

The attribute specifications on the resolved element can be drawn from both the referencing element and the referenced element, according to the following priority:

1. All attributes as specified on the referencing element, except for attributes which specify the value "-dita-use-conref-target". (The term "target" here refers to the referenced element.)
2. All attributes as specified on the referenced element except:
   1. The id attribute
   2. Any attribute that is also specified on the referencing element, except when the value specified on the referencing element is "-dita-use-conref-target"
3. The xml:lang attribute has special treatment as described in The @xml:lang attribute.

The only time the resolved element would include an attribute whose specified value is "-dita-use-conref-target" is when the referenced element had that attribute specified with the "-dita-use-conref-target" value and the referencing element either had no specification for that attribute or had it also specified with the "-dita-use-conref-target" value. If the final resolved element (after the complete resolution of any conref chain, as explained below) has an attribute with the "-dita-use-conref-target" value, that should be treated as equivalent to having that attribute unspecified.

A given attribute value on the resolved element comes in its entirety from either the referencing element or the referenced element; the attribute values of the referencing and referenced elements for a given attribute are never additive, even if the property (such as the audience type) takes a list of values.

If the referenced element has a @conref attribute specified, the above rules should be applied recursively with the resolved element from one referencing/referenced combination becoming one of the two elements participating in the next referencing/referenced combination. The result should preserve without generalization all elements that are valid in the originating context, even if they are not valid in an intermediate context. For example, if topicA and topicC allow highlighting, and topicB does not, then a content reference chain of topicA->topicB->topicC should preserve any highlighting elements in the referenced content. The result, however it is achieved, must be equivalent to the result of resolving the conref pairs recursively starting from the original referencing element in topicA.

The @conrefend attribute is used when referencing a range of elements with the conref mechanism. The @conref attribute references the first element in the range, while @conrefend points to the last element in the range. Although the start and end referenced elements must both be of the same type as the referencing element (or specialized from that element type), the intermediary, contiguous nodes in the middle of the range do not have to be the same.

Conditional processing attributes

For a topic or topicref, the audience, platform, and product metadata can be expressed with attributes on the topic or topicref element or with elements within the topic prolog or topicmeta element. While the metadata elements are more expressive, the meaning of the values is the same, and can be used in coordination. For example, the prolog elements can fully define the audiences for a topic, and then metadata attributes can be used within the content to identify parts that apply to only some of those audiences.

audience

The values in the audience attribute may also be used to reference a more complete description of an audience in an audience element. Use the name of the audience in the audience element when referring to the same audience in an audience attribute.

The audience attribute takes a space-delimited list of values, which may or may not match the name value of any audience elements.

platform

The platform might be the operating system, hardware, or other environment. This attribute is equivalent to the platform element for the topic metadata.

The platform attribute takes a space-delimited list of values, which may or may not match the content of a platform element in the prolog.

product

The product or component name, version, brand, or internal code or number. This attribute is equivalent to the prodinfo element for the topic metadata.

The product attribute takes a space-delimited list of values, which may or may not match the value of the prodname element in the prolog.

rev

The identifier for the revision level. For example, if a paragraph was changed or added during revision 1.1, the rev attribute might contain the value "1.1".

otherprops

A catch-all for metadata qualification values about the content. This attribute is equivalent to the othermeta element for the topic metadata.

The attribute takes a space-delimited list of values, which may or may not match the values of othermeta elements in the prolog.

For example, a simple otherprops value list: <codeblock otherprops="java cpp">

MP: deprecated grouped value syntax per TC meeting 2007/01/02

The attribute may take labeled groups of values as for @props. Processors may treat such values as equivalent to @props or they may treat such values as simple strings. The use of labeled groups in @otherprops is deprecated in favor of using specializations of @props. Processors should clearly document how they treat grouped @otherprops values. See Attribute generalization for details on generalized @props attribute values.

props

A generic attribute for conditional processing values. Starting with DITA 1.1, the props attribute can be specialized to create new conditional processing attributes. See Attribute generalization.

Using conditional processing attributes

Each attribute takes zero or more space-delimited string values. For example, you can use the product attribute to identify that an element applies to two particular products.

<p audience="administrator">Set the configuration options:
    <ul>
        <li product="extendedprod">Set foo to bar</li>
        <li product="basicprod extendedprod">Set your blink rate</li>
        <li>Do some other stuff</li>
        <li platform="Linux">Do a special thing for Linux</li>
    </ul>
</p>
            

Evaluating conditional processing attributes

At processing time, a DITAVAL conditional processing profile may be used to specify values you want to include, exclude, or flag.

For example, a publisher producing information for a mixed audience using the basic product could choose to flag information that applies to administrators, and exclude information that applies to the extended product, by defining a conditional processing profile like this:

<val>
  <prop att="audience" val="administrator" action="flag">
    <startflag><alt-text>ADMIN</alt-text></startflag>
  </prop>
  <prop att="product" val="extendedprod" action="exclude"/>
</val>

At output time, the paragraph is flagged, and the first list item is excluded (since it applies to extendedprod), but the second list item is still included (even though it does apply to extendedprod, it also applies to basicprod, which was not excluded).

The result should look something like:

Filtering logic

By default, values in conditional processing attributes that are not defined in a DITAVAL profile evaluate to "include". For example, if the value audience="novice" is used on a paragraph, but this value is not defined in a DITAVAL profile, the attribute evaluates to "include". However, the DITAVAL profile may change this default to "exclude", so that any value not explicitly defined in the DITAVAL profile will evaluate to "exclude". The profile may also be used to change the default for a single attribute; for example, it may declare that values in the platform attribute default to exclude while those in the product attribute default to include. See DITAVAL elements for information on how to set up a DITAVAL profile and how to change default behaviors.

When deciding whether to include or exclude a particular element, a processor should evaluate each attribute, and then evaluate the set of attributes.

• If all the values in a single attribute evaluate to "exclude", the attribute evaluates to "exclude".
• If any single attribute evaluates to exclude, the element is excluded.

For example, if a paragraph applies to three products and the publisher has chosen to exclude all of them, the processor should exclude the paragraph. This is true even if the paragraph applies to an audience or platform that is not excluded. But if the paragraph applies to an additional product that has not been excluded, then its content is still relevant for the intended output and should be preserved.

Flagging logic

When deciding whether to flag a particular element, a processor should evaluate each value. Wherever a value that has been set as flagged appears in its attribute (for example, audience="administrator") the process should add the flag. When multiple flags apply to a single element, multiple flags should be rendered, typically in the order they are encountered.

Flagging could be done using text (for example, bold text against a colored background) or using images. When the same element evaluates as both flagged and filtered (for example, flagged because of an audience attribute value and filtered because of its product attribute values), the element should be filtered.

Using the chunk attribute

When a set of topics is processed for output using a map, the map author may use the chunk attribute to override whatever default chunking behavior is set by the processor. The chunk attribute allows the map author to request that multi-topic documents be be broken into multiple documents, and that multiple individual topics be combined into a single document.

Chunking is necessarily output processor specific with chunked output required for some and not supported for other types of output. Chunking is also implementation specific with some implementations supporting some, but not all, chunking methods, or adding new implementation specific chunking methods to the standard methods described in this specification.

The value of the chunk attribute consists of one or more space delimited tokens. Tokens are defined in three categories: for selecting topics, for setting chunking policies, and for defining how the chunk values impact rendering. It is an error to use two tokens from the same category on a single topicref element.

Selecting topics

These values describe what portion of a target document is referenced. Such tokens are only useful when addressing a document that is made up of multiple topics. These values are ignored when the element on which they are specified does not reference a topic. Recognized values include:

• select-topic : The "select-topic" token is used to select an individual topic without any ancestors, descendents, or peers from within the same document.
• select-document : The "select-document" token is used to select the target topic together with all ancestors, descendents, and peers within the target document.
• select-branch : The "select-branch" token is used to select the target topic together with its descendents.

Policies for splitting or combining documents

Two tokens are defined for setting chunking policies. Each token applies only to the current topicref or topicref specialization, except when used on the map element, in which case the value establishes a policy for the entire map.

• by-topic : The "by-topic" token establishes a policy for the current topicref (or topicref specialization) where a separate output chunk is produced for each of the selected topics.
• by-document : The "by-document" token establishes a policy for the current topicref (or topicref specialization) where a single output chunk is produced for the referenced topic or topics.

Rendering the selection

The following tokens affect how the chunk values impact rendering of the map or topics.

• to-content : The "to-content" token indicates that the selection should be rendered as a new chunk of content.
  • When specified on a topicref or topicref specialization, this means that the topics selected by this topicref and its children will be rendered as a single chunk of content.
  • When specified on the map element, this indicates that the contents of all topics referenced by the map are to be rendered as a single document.
  • When specified on a topicref or topicref specialization that contains a title but no target, this indicates that a title-only topic must be generated in the rendered result, along with any topics referenced by child topicrefs (and topicref specializations) of this topicref. The rendition address of the generated topic is determined as defined for the copy-to attribute. If the copy-to attribute is not specified and the topicref has no id attribute, the address of the generated topic is not required to be predictable or consistent across rendition instances.

  For cross references to topicref elements, if the value of the chunk attribute is "to-content" or is unspecified, the cross reference is treated as a reference to the target topic. If the reference is to a topicref with no target, it is treated as a reference to the generated title-only topic.

• to-navigation : The "to-navigation" token indicates that a new chunk of navigation should be used to render the current selection (such as an individual Table of Contents or related links). When specified on the map element, this token indicates that the map should be presented as a single navigation chunk. If a cross reference is made to a topicref that has a title but no target, and the chunk value of that topicref is set to "to-navigation", the resulting cross reference is treated as a reference to the rendered navigation document (such as an entry in the table of contents).

Some tokens or combinations of tokens may not be appropriate for all output types. When unsupported or conflicting tokens are encountered during output processing, warning or error messages should be produced. Recovery from such conflicts or other errors is implementation dependent.

There is no default value for the chunk attribute and the chunk attribute does not cascade from container elements, meaning that the chunk value on one topicref is not passed to its children. A default by-xxx policy for an entire map may be established by setting the chunk attribute on the map element, which will apply to any topicref that does not specify its own by-xxx policy.

When no chunk attribute values are given, chunking behavior is implementation dependent. When variations of this sort are not desired, a default for a specific map may be established by including a chunk attribute value on the map element.

When creating new documents via chunk processing, the storage object name or identifier (if relevant) is determined as follows:

1. If an entire map is used to generate a single chunk (by placing to-content on the map element), the name is taken from the name of the map.
2. If the @copy-to attribute is specified, the name is taken from the @copy-to attribute.
3. If @copy-to is not specified and the by-topic policy is in effect, the name is taken from the @id attribute of the topic.
4. If @copy-to is not specified and the by-document policy is in effect, the name is taken from the name of the referenced document.

Implementation-specific tokens and future considerations

Additional chunk tokens may be added to the DITA Standard in the future. In addition, implementers may define their own custom, implementation-specific tokens. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens should consist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the chunking method name. For example: “acme:level2” could be a token for the Acme DITA Toolkit that requests the “level2” chunking method.

The purpose of the concept information type

Concepts provide background that helps readers understand essential information about a product, a task, a process, or any other conceptual or descriptive information. A concept may be an extended definition of a major abstraction such as a process or function. Conceptual information may explain the nature and components of a product and describe how it fits into a category of products. Conceptual information helps readers to map their knowledge and understanding to the tasks they need to perform and to provide other essential information about a product, process, or system.

The structure of the concept topic

The concept topic is specialized from the base topic information type. The top-level element for a DITA concept topic is the <concept> element. Every concept topic contains the standard topic elements, including title, short descriptions or abstract, prolog, a body, and related links.

The <conbody> element holds the main body-level elements of the concept topic. Like the body element of a base topic, the <conbody> allows paragraphs, lists, tables, figures and other general elements. It also provides two key elements that allow authors to subdivide the topic into parts, with or without titles. These subdivisions are called sections and examples. The <conbody> also allows <bodydiv> and <sectiondiv> to facilitate grouping elements in the <conbody> for reuse.

Limitations within <conbody>

The <conbody> provides for an unlimited number of subdivisions in the form of sections and examples. However, once an author decides to incorporate a section or example in the <conbody>, only additional sections or examples are allowed. Sections and examples may not nest, meaning that only one level of subdivision is permitted in the concept topic.

Concept body primary subdivisions

<section>

Represents an organizational division in a concept topic. Sections organize subsets of information within a larger topic. You can only include a simple list of peer sections in a topic; sections cannot be nested. A section may have an optional title.

<example>

Provides examples that illustrate or support the current topic. The <example> element has the same content model as <section>.

Modules

The following DITA modules are provided for the concept topic:

• concept.mod, concept.ent (DTD)
• conceptMod.xsd, conceptGrp.xsd (Schema)

The purpose of the reference information type

Reference topics that provide data in support of the performance of a task. Reference topics may provide lists and tables that include product specifications, parts lists, constraints on use or performance, and other data that is often “looked up” rather than memorized. A reference topic may also describe regular constituents of a subject or product, such as commands in a programming language. or required tools for a series of maintenance tasks.

Reference topics provide quick access to fact-based information. In technical information, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as the commands in a programming language. Reference topics may hold any subject matter that has regular content, such as ingredients for food in recipes, bibliographic lists, catalogue items, and so on.

The structure of the reference topic

The top-level element for a reference topic is the <reference> element.

The <refbody> element holds the main body-level elements of the reference topic. Reference topics limit the body to tables (both simple and complex), property lists, syntax sections, and generic sections and examples.

All of the elements of <refbody> are optional and may appear in any sequence and number.

Limitations on the reference body

The <refbody> provides for an unlimited number of subdivisions in the form of sections, examples, syntax sections, property lists, and tables. However, once an author decides to incorporate a section, example, property list, or syntax section in the <refbody>, only additional sections, examples, property lists, or syntax sections are allowed. Simple and complex tables may appear within sections, examples, and syntax sections. They may not appear within the property list or simple or complex table sections. Sections, examples, syntax sections, table subdivisions, and property lists may not nest, meaning that only one level of subdivision is permitted in the reference topic.

The sections of the reference body

<section>

Represents an organizational division in a reference topic. Sections organize subsets of information within a larger topic. You can only include a simple list of peer sections in a topic; sections cannot be nested. A section may have an optional title.

<refsyn>

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.

<example>

Provides examples that illustrate or support the current topic. The <example> element has the same content model as <section>.

<table>

Organizes information according into a rows and columns. Table markup also allows for more complex structures, including spanning rows and columns, as well as table captions.

<simpletable>

Holds information in regular rows and columns and does not allow a caption.

<properties>

Lists properties of a subject and their types, values, and descriptions.

Modules

The following DITA modules are provided for the reference topic.

• reference.mod, reference.ent (DTD)
• referenceMod.xsd, referenceGrp.xsd (Schema)

The purpose of the general task information type

Like the DITA strict task document type, the general task document and information types contain the essential building blocks to provide procedural information. Both task information types answer the "How do I?" question by providing step-by-step instructions detailing the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. Both task topics include sections for describing the context, prerequisites, expected results, and other aspects of a task.

The general task information type is specifically designed to accommodate task specializations that differ from the DITA task information type. It may also be used for the conversion of loosely structured tasks from other sources into DITA before they are restructured to follow the more restrictive DITA task model.

The structure of the general task topic

The <task> element is the top-level element for the general task topic. The general task topic contains a title and a taskbody with optional alternative titles (titlealts), a short description or abstract, a prolog,and related-links.

The following elements are described here because they are introduced as part of the general task model. All other elements are described in the strict task topic.

<section>

Represents an organizational division in a task topic. Sections organize subsets of information within the larger topic. Sections may not be nested. A section may have an optional title.

<steps-informal>

Describes procedural task information that would not normally be ordered as steps, such as a group of general procedures that may all be applied in a particular situation. Instead of <step>, the <steps-informal> element uses <ol> and <ul> elements, which are less strictly defined than the <step> element. When converting legacy content, it may be simpler to convert numbered lists to <ol> elements than to <step> elements.

Comparison of general and strict task

The following table compares the structures of general and strict task:

Modules

The following DITA modules are provided for the task topic.

• task.mod, task.ent(DTD)
• taskMod.xsd, taskGrp.xsd (Schema)

The purpose of the standard task information type

Tasks are the essential building blocks to provide procedural information. A task information type answers the "How do I?" question by providing precise step-by-step instructions detailing the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. The task topic includes sections for describing the context, prerequisites, expected results, and other aspects of a task.

The structure of the task topic

The <task> element is the top-level element for the strict task topic. The strict task document type contains a title and a taskbody with optional alternative titles (titlealts), a short description or abstract, a prolog,and related-links.

The <taskbody> element is the main body element inside a strict task document type. The strict task body has a constrained structure, with these optional elements in the following order:

<prereq>

Describes information that the user needs to know or do before starting the immediate task. This section may occur only once.

<context>

Provides background information for the task. This information helps the users understand the purpose of the task and what they will gain by completing the task correctly. This section should be brief and does not replace or recreate a concept topic on the same subject, although the context section may include some conceptual information. This section may occur only once.

<steps>

Provides the main content of the task topic. A task consists of a series of steps that accomplish the task. The <steps> element must have one or more <step> elements, which provide the specifics about each step in the task. The <steps> element may occur only once.

The <step> element represents an action that a user must follow to accomplish a task. Each step in a task must contain a command <cmd> element which describes the particular action the user must perform to accomplish the overall task. The step element may also contain information <info>, substeps <substeps>, tutorial information <tutorialinfo>, a step example <stepxmp>, choices <choices>, or a stepresult <stepresult>, although these are optional.

<steps-unordered>

Provides alternative content for the task topic, allowing for a single step in a procedure or a set of commands that need not be performed in a specific order.

<result>

Describes the expected outcome for the task as a whole.

<example>

Provides an example that illustrates or supports the task.

<postreq>

Describes steps or tasks that the user should do after the successful completion of the current task. It is often supported by links to the next task or tasks in the <related-links> section.

Maintaining specializations using the strict task model

Organizations that have created specializations based on the DITA 1.0 and 1.1 strict task model should review the recommendations in Migrating from DITA 1.1 to 1.2 to maintain their specializations.

Modules

The following DITA modules are provided for the task topic.

• task.mod. task.ent, strictTaskbody constraint (DTD)
• taskMod.xsd, taskGrp.xsd, strictTaskbodyConstraintMod.xsd (Schema)

The purpose of the machinery task information type

The machinery-task is designed to provide procedural information, similar to the strict task topic, and has a well-defined semantic structure that describes how to perform the steps required to accomplish a specific goal. Compared to the strict task information type, the machinery-task information type contains additional descriptive elements in the prelreqs section that add detail to the pre-requisites required to perform a task. The machinery-task topic is developed using the DITA constraint mechanism, in addition to specializations for new elements.

Machinery tasks are the essential building blocks to provide procedural information for machines, machinery equipment, assemblies, and apparatuses. A machinery-task information type answers the "How do I?" question by providing precise step-by-step instructions detailing the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. The machinery-task topic includes sections for describing the context, preliminary requirements, expected results, examples, closing requirements, and other aspects of a task.

The structure of the machinery-task topic

Similar to a strict DITA task, the <task> element is the top-level element for a machinery task topic. The machinery task document type contains a title and a taskbody with optional alternative titles (titlealts), a short description or abstract, a prolog,and related-links.

The <taskbody> element is the main body element inside a machinery-task topic. A machinery-task body has a very specific structure, with the following elements in this order: (<prelreqs> or <context> or <section>)*, <steps>, <result>, <example>, and <closereqs>. Each of the body sections is optional.

The machinery task includes two specialized element groups: <prelreqs> and <closereqs>. All other element groups are the same as the general task model.

<prelreqs>

The preliminary-requirements section of a task is used to describe what the user needs to know or do before starting the immediate task. The <prelreqs> element is similar to the prerequisites section of the general task model but contains a more descriptive content model. The <prelreqs> element contains required conditions, required personnel, required equipment, supplies, spares, and safety information.

<closereqs>

The close-requirements section is used to describe conditions that must be fulfilled after the successful completion of the current task. It is often supported by links to the next task or tasks in the <related-links> section. The <closereqs> element contains required conditions <reqconds>.

Modules

The following DITA modules are provided for the machinery task topic.

• machineryTask.dtd (DTD), machineryTaskbodyConstraint.mod
• machineryTask.xsd, machineryTaskbodyConstraintMod.xsd, machineryTaskbodyConstraintIntMod.xsd (Schema)

The purpose of the glossary entry topic

Defining terminology in a glossary ensures that a team of writers uses the same term for the same concept. A glossary added to a book or available online in conjunction with other subject matter provides the reader with definitions of unfamiliar terms and expands acronyms.

The structure of the glossentry topic

The top-level element for a DITA glossentry topic is the <glossentry> element. Every glossentry topic contains a <glossterm> and a <glossdef> element and optional <related-links>.

Where a term has multiple senses, the writer should create multiple glossentry topics with the same term in the <glossterm> element but different definitions in the <glossdef> element. A process can collate and group glossentry topics by term when generating formatted output. Note that definitions with the same term in one language can have different terms in other languages, so translations can result in different collation and grouping of the same set of glossentry topics.

Here is an example of a simple glossentry topic:

<glossentry id="ddl">
    <glossterm>Data Definition Language</glossterm>
    <glossdef>A language used for defining database schemas.</glossdef>
</glossentry>

To create a glossary, authors can group multiple entries together by

• authoring in a single document using the Glossary group document type
• authoring in a single document under a container topic using the ditabase document type
• referencing the glossentry topics from a map
• using an automated process

Acronyms defined within glossentry topics

The glossentry topic may be used to provide expansions of acronyms in online text and assist in the proper translation of acronyms into multiple languages. The acronym elements of the glossentry topic include the following:

• <glossterm> to enter the full text to which the acronym refers
• <glossSurfaceForm> to provide the appropriate rendering of the full text plus the acronym in each language
• <glossAcronym> to provide the acronym text itself

Here is an example of an acronym used in the glossentry topic:

<glossentry id="wmd" xml:lang="en">
  <glossterm>Weapons of Mass Destruction</glossterm>
  <glossBody>
    <glossSurfaceForm>Weapons of Mass Destruction (WMD)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>WMD</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

Here is an example of how the glossentry topic would be translated into Spanish:

<glossentry id="wmd" xml:lang="es">
  <glossterm>armas de destrucción masiva</glossterm>
  <glossBody>
    <glossSurfaceForm></glossSurfaceForm>
    <glossAlt>
      <glossAcronym></glossAcronym>
    </glossAlt>
  </glossBody>

Note that because no acronym exists for the term in Spanish, the <glossSurfaceForm> and <glossAcronym> elements are left blank.

In some languages, the surface form that expands the acronym in its first use handles the formatting differently than in English. For example, in Polish, the acronym precedes the expansion.

<glossentry id="eu" xml:lang="pl">
  <glossterm>Unia Europejska</glossterm>
  <glossBody>
    <glossSurfaceForm>UE (Unia Europejska)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>UE</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

For more information about the correct use of acronym expansions in multiple languages, see Best Practice for Managing Acronyms and Abbreviations in DITA, produced by the DITA Translation Subcommittee. http://www.oasis-open.org/committees/download.php/29734/AcronymBestPractice_08112008.doc

Modules

The following DITA modules are provided for the glossary entry topic.

• glossentry.dtd, glossentry.ent, glossentry.mod (DTD)
• glossentryMod.xsd, glossentryGrp.xsd (Schema)

Modules

The following DITA modules are provided for the glossgroup topic.

• glossgroup.dtd, glossgroup.ent, glossgroup.mod (DTD)
• glossgroup.xsd, (Schema)

The purpose of the bookmap specialization

Books and other printed media are popular ways to present DITA content. By specializing the general DITA map structure into the general structure and subject areas used by most book-oriented DTDs, bookmaps enable users to organize their DITA information into front matter, parts, chapters, and so forth. A rich set of metadata allows for recording information about the book, such as its authors and owners, versions, and production history.

The structure of the bookmap specialization

The <bookmap> element is the top-level element for a DITA bookmap. Most of the content for a bookmap is optional, allowing for specializations that further restrict the bookmap model..

A bookmap allows the following parts:

• An intial title or booktitle (booktitle has more semantics)
• Book metadata (publisher, author, copyright holders and dates, etc.)
• Front matter (placement for Table of Contents and other preliminary information)
• Any number of chapters or parts (parts can group chapters, chapters can group topics)
• An appendices section (similar to a part or a chapter, can group multiple appendices
• Back matter (similar to front matter, notices, glossary, index, etc.)
• Relationship table

In typical book-oriented DTDs or schemas, authors commonly manage major content structures as external entities, separate from the body of the book, and referenced as imbedded elements into the overall structure. Bookmap follows the same organizational approach, using the topicref-based structure of DITA maps as the archetype for the major divisions of a book.

Here is an example of a simple bookmap. It includes several mechanisms to include chapter content:

• Referencing a DITA map
• Referencing a DITA topic
• Nesting <topicref> elements

Modules

The following DITA modules are provided for the bookmap specialization.

• bookmap.dtd, bookmap.ent, bookmap.mod (DTD)
• bookmap.xsd, bookmapGrp.xsd, bookmapMod.xsd (Schema)