Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

DITA topics consist of content units that can be as generic as sets of paragraphs and unordered lists or as specific as sets of instructional steps in a procedure or cautions to be considered before a procedure is performed. Content units in DITA are expressed using XML elements and can be conditionally processed using metadata attributes.

Classically, a DITA topic is a titled unit of information that can be understood in isolation and used in multiple contexts. It should be short enough to address a single subject or answer a single question but long enough to make sense on its own and be authored as a self-contained unit. However, DITA topics also can be less self-contained units of information, such as topics that contain only titles and short descriptions and serve primarily to organize subtopics or links or topics that are designed to be nested for the purposes of information management, authoring convenience, or interchange.

DITA topics are used by reference from DITA maps. DITA maps enable topics to be organized in a hierarchy for publication. Large units of content, such as complex reference documents or book chapters, are created by nesting topic references in a DITA map. The same set of DITA topics can be used in any number of maps.

DITA topics also can be used and published individually; for example, one can represent an entire deliverable as a single DITA document that consists of a root topic and nested topics. This strategy can accommodate the migration of legacy content that is not topic-oriented; it also can accommodate information that is not meaningful outside the context of a parent topic. However, the power of DITA is most fully realized by storing each DITA topic in a separate XML document and using DITA maps to organize how topics are combined for delivery. This enables a clear separation between how topics are authored and stored and how topics are organized for delivery.

While DITA does not require the use of any particular writing practice, the DITA architecture is designed to support authoring, managing, and processing of content that is designed to be reused. Although DITA provides significant value even when reuse is not a primary requirement, the full value of DITA is realized when content is authored with reuse in mind. To develop topic-based information means creating units of standalone information that are meaningful with little or no surrounding context.

By organizing content into topics that are written to be reusable, authors can achieve several goals:

• Content is readable when accessed from an index or search, not just when read in sequence as part of an extended narrative. Since most readers do not read technical and business-related information from beginning to end, topic-oriented information design ensures that each unit of information can be read independently.
• Content can be organized differently for online and print delivery. Authors can create task flows and concept hierarchies for online delivery and create a print-oriented hierarchy to support a narrative content flow.
• Content can be reused in different collections. Since a topic is written to support random access (as by search), it should also be understandable when included as part of various product deliverables. Topics permit authors to refactor information as needed, including only the topics that apply to each unique scenario.
• Content is more manageable in topic form whether managed as individual files in a traditional file system or as objects in a content management system.
• Content authored in topics can be translated and updated more efficiently and less expensively than information authored in larger or more sequential units.
• Content authored in topics can be filtered more efficiently, encouraging the assembly and deployment of information subsets from shared information repositories.

Topics written for reuse should be small enough to provide opportunities for reuse but large enough to be coherently authored and read. When each topic is written to address a single subject, authors can organize a set of topics logically and achieve an acceptable narrative content flow.

Information typing has a long history of use in the technical documentation field to improve information quality. It is based on extensive research and experience, including Robert Horn's Information Mapping and Hughes Aircraft's STOP (Sequential Thematic Organization of Proposals) technique. Note that many DITA topic types are not necessarily closely connected with traditional Information Mapping.

Information typing is a practice designed to keep documentation focused and modular, thus making it clearer to readers, easier to search and navigate, and more suitable for reuse. Classifying information by type helps authors perform the following tasks:

• Develop new information more consistently
• Ensure that the correct structure is used for closely related kinds of information (retrieval-oriented structures like tables for reference information and simple sequences of steps for task information)
• Avoid mixing content types, thereby losing reader focus
• Separate supporting concept and reference information from tasks, so that users can read the supporting information if needed and ignore if it is not needed
• Eliminate unimportant or redundant detail
• Identify common and reusable subject matter

DITA currently defines a small set of well-established information types that reflects common practices in certain business domains, for example, technical communication and instruction and assessment. However, the set of possible information types is unbounded. Through the mechanism of specialization, new information types can be defined as specializations of the base topic type (<topic>) or as refinements of existing topics types, for example, <concept>, <task>, <reference>, or <learningContent>.

You need not use any of the currently-defined information types. However, where a currently-defined information type matches the information type of your content, the currently-defined information type should be used, either directly, or as a base for specialization. For example, information that is procedural in nature should use the task information type or a specialization of task. Consistent use of established information types helps ensure smooth interchange and interoperability of DITA content.

For authors, typed content is preferred to support consistency in writing and presentation to readers. The generic topic type should only be used if authors are not trained in information typing or when a specialized topic type is inappropriate. The OASIS DITA standard provides several specialized topic types, including concept, task, and reference that are critical for technical content development.

For those pursuing specialization, new specialized topic types should be specialized from appropriate ancestors to meet authoring and output requirements.

All DITA topics must have an XML identifier (the @id attribute) and a title. The basic topic structure consists of the following parts, some of which are optional:

Topic element

The topic element holds the required @id attribute and contains all other elements.

Title

The title contains the subject of the topic.

Alternate titles

Titles specifically for use in navigation or search. When not provided, the base title is used for all contexts.

Short description or abstract

A short description of the topic or a longer abstract with an embedded short description. The short description might be used both in topic content (as the first paragraph), in generated summaries that include the topic, and in links to the topic. Alternatively, the abstract lets you create more complex introductory content and uses an embedded short description element to define the part of the abstract that is suitable for summaries and link previews.

While short descriptions aren't required, they can make a dramatic difference to the usability of an information set and should generally be provided for all topics.

Prolog

The prolog is the container for topic metadata, such as change history, audience, product, and so on.

Body

The topic body contains the topic content: paragraphs, lists, sections, and other content that the information type permits.

Related links

Related links connect to other topics. When an author creates a link as part of a topic, the topic becomes dependent on the other topic being available. To reduce dependencies between topics and thereby increase the reusability of each topic, authors can use DITA maps to define and manage links between topics, instead of embedding links directly in each related topic.

Nested topics

Topics can be defined inside other topics. However, nesting requires special care because it can result in complex documents that are less usable and less reusable. Nesting might be appropriate for information that is first converted from desktop publishing or word processing files or for topics that are unusable independent from their parent or sibling topics.

The rules for topic nesting can be configured in a document-type shells. For example, the standard DITA configuration for concept topics only allows nested concept topics. However, local configuration of the concept topic type could allow other topic types to nest or disallow topic nesting entirely. In addition, the @chunk attribute enables topics to be equally re-usable regardless of whether they are separate or nested. The standard DITA configuration for ditabase document-type documents allows unrestricted topic nesting and can be used for holding sets of otherwise unrelated topics that hold re-usable content. It can also be used to convert DITA topics from non-DITA legacy source without first determining how individual topics should be organized into separate XML documents.

Topic body

The topic body contains all content except for that contained in the title or the short description/abstract. The topic body can be constrained to remove specific elements from the content model; it also can be specialized to add additional specialized elements to the content model. The topic body can be generic while the topic title and prolog are specialized.

Sections and examples

The body of a topic might contain divisions, such as sections and examples. They might contain block-level elements like titles and paragraphs and phrase-level elements like API names or text. It is recommend that sections have titles, whether they are entered directly into the <title> element or rendered using a fixed or default title.

Either body divisions or untitled sections or examples can be used to delimit arbitrary structures within a topic body. However, body divisions can nest, but sections and examples cannot contain sections.

<sectiondiv>

The <sectiondiv> element enables the arbitrary grouping of content within a section for the purpose of content reuse. The <sectiondiv> element does not include a title. Content that requires a title should use <section> or <example>.

<bodydiv>

The <bodydiv> element enables the arbitrary grouping of content within the body of a topic for the purpose of content reuse. The <bodydiv> element does not include a title. Content that requires a title should use <section> or <example>.

<div>

The <div> element enables the arbitrary grouping of content within a topic. The <div> element does not include a title. Content that requires a title should use <section> or <example> or, possibly, <fig>.

Block-level elements

Paragraphs, lists, figures, and tables are types of "block" elements. As a class of content, they can contain other blocks, phrases, or text, though the rules vary for each structure.

Phrases and keywords

Phrase level elements can contain markup to label parts of a paragraph or parts of a sentence as having special semantic meaning or presentation characteristics, such as <uicontrol> or <b>. Phrases can usually contain other phrases and keywords as well as text. Keywords can only contain text.

Images

Images can be inserted to display photographs, illustrations, screen captures, diagrams, and more. At the phrase level, they can display trademark characters, icons, toolbar buttons, and so forth.

Multimedia

The <object> element enables authors to include multimedia, such as diagrams that can be rotated and expanded. The <foreign> element enables authors to include media within topic content, for example, SVG graphics, MathML equations, and so on.

Maps draw on a rich set of existing best practices and standards for defining information models, such as hierarchical task analysis. They also support the definition of non-hierarchical relationships, such as matrices and groups, which provide a set of capabilities that has similarities to Resource Description Framework (RDF) and ISO topic maps.

DITA maps use <topicref> elements to reference DITA topics, DITA maps, and non-DITA resources, for example, HTML and TXT files. The <topicref> elements can be nested or grouped to create relationships among the referenced topics, maps, and non-DITA files; the <topicref> elements can be organized into hierarchies in order to represent a specific order of navigation or presentation.

DITA maps impose an architecture on a set of topics. Information architects can use DITA maps to specify what DITA topics are needed to support a given set of user goals and requirements; the sequential order of the topics; and the relationships that exist among those topics. Because DITA maps provide this context for topics, the topics themselves can be relatively context-free; they can be used and reused in multiple different contexts.

DITA maps often represent a single deliverable, for example, a specific Web site, a printed publication, or the online help for a product. DITA maps also can be subcomponents for a single deliverable, for example, a DITA map might contain the content for a chapter in a printed publication or the troubleshooting information for an online help system. The DITA specification provides specialized map types; book maps represent printed publications, subject scheme maps represent taxonomic or ontological classifications, and learning maps represent formal units of instruction and assessment. However, these map types are only a starter set of map types reflecting well-defined requirements.

DITA maps establish relationships through the nesting of <topicref> elements and the application of the @collection-type attribute. Relationship tables also can be used to associate topics with each other based on membership in the same row; for example, task topics can be associated with supporting concept and reference topics by placing each group in cells of the same row. During processing, these relationships can be rendered in different ways, although they typically result in lists of "Related topics" or "For more information" links. Like many aspects of DITA, the details about how such linking relationships are presented is determined by the DITA processor.

DITA maps also define keys and organize the contexts (key scopes ) in which key references are resolved.

DITA maps support the following uses:

Defining an information architecture

Maps can be used to define the topics that are required for a particular audience, even before the topics themselves exist. DITA maps can aggregate multiple topics for a single deliverable.

Defining what topics to build for a particular output

Maps reference topics that are included in output processing. Information architects, authors, and publishers can use maps to specify a set of topics that are processed at the same time, instead of processing each topic individually. In this way, a DITA map can serve as a manifest or bill of materials.

Defining navigation

Maps can define the online navigation or table of contents for a deliverable.

Defining related links

Maps define relationships among the topics they reference. These relationships are defined by the nesting of elements in the DITA map, relationship tables, and the use of elements on which the @collection-type attribute is set. On output, these relationships might be expressed as related links or the hierarchy of a table of contents (TOC).

Defining an authoring context

The DITA map can define the authoring framework, providing a starting point for authoring new topics and integrating existing ones.

Defining keys and key scopes

Maps can define keys, which provide an indirect addressing mechanism that enhances portability of content. The keys are defined by <topicref> elements or specializations of <topicref> elements, such as <keydef>. The <keydef> element is a convenience element; it is a specialized type of a <topicref> element with the following attributes:

• A required @keys attribute
• A @processing-role attribute with a default value of "resource-only".

Maps also define the context or contexts for resolving key-based references, such as elements that specify the @keyref or @conkeyref attribute. Elements within a map structure that specify a @keyscope attribute create a new context for key reference resolution. Key references within such elements are resolved against the set of effective key definitions for that scope.

Specialized maps can provide additional semantics beyond those of organization, linking, and indirection. For example, the subjectScheme map specialization adds the semantics of taxonomy and ontology definition.

A DITA map is composed of the following elements:

<map>

The <map> element is the root element of the DITA map.

<topicref>

The <topicref> elements are the basic elements of a map. A <topicref> element can reference a DITA topic, a DITA map, or a non-DITA resource. A <topicref> element also can have a title, short description, and the same kind of prolog-level metadata that is available in topics.

The <topicref> elements can be nested to create a hierarchy, which can be used to define a table of contents (TOC) for print output, online navigation, and parent/child links. Hierarchies can be annotated using the @collection-type attribute to define a particular type of relationship, such as a set of choices, a sequence, or a family. These collection types can affect link generation, and they might be interpreted differently for different outputs.

<reltable>

Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships among DITA topics or among DITA topics and non-DITA resources. In a relationship table, the columns define common attributes, metadata, or information types (for example, task or troubleshooting) for the resources that are referenced in that column. The rows define relationships between the resources in different cells of the same row.

The <relrow>, <relcell>, <relheader>, and <relcolspec> elements are used to define the components of the relationship table. Relationships defined in the relationship table also can be further refined by using the @collection-type attribute.

<topicgroup>

The <topicgroup> element defines a group or collection outside of a hierarchy or relationship table. It is a convenience element that is equivalent to a <topicref> element without an @href attribute or navigation title. Groups can be combined with hierarchies and relationship tables, for example, by including a <topicgroup> element within a set of siblings in a hierarchy or within a table cell. The <topicref> elements so grouped can then share inherited attributes and linking relationships with no effect on the navigation or table of contents.

<topicmeta>

Most map-level elements, including the map itself, can contain metadata inside the <topicmeta> element. Metadata typically is applied to an element and its descendants.

<ux-window>

The <ux-window> element enables authors to define windowing information for the display of output topics that are appropriate to the delivery platform. Window management is important in user assistance and help system outputs, as well as for other hypertext and electronic delivery modes.

<topichead>

The <topichead> element provides a navigation title; it is a convenience element that is equivalent to a <topicref> element with a navigation title but no associated resource.

<anchor>

The <anchor> element provides an integration point that another map can reference in order to insert its navigation into the referenced map's navigation tree. For those familiar with Eclipse help systems, this serves the same purpose as the <anchor> element in that system. It might not be supported for all output formats.

<navref>

The <navref> element represents a pointer to another map which is preserved as a transcluding link in the result deliverable rather than resolved when the deliverable is produced. Output formats that support such linking can integrate the referenced resource when displaying the referencing map to an end user.

<keydef>

Enables authors to define keys. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @processing-role attribute to "resource-only". Setting the @processing-role attribute to resource-only ensures that the resource referenced by the key definition is not directly included in the navigation that is defined by the map.

<mapref>

Enables authors to reference an entire DITA map, including hierarchy and relationship tables. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @format attribute to "ditamap". The <mapref> element represents a reference from a parent map to a subordinate map.

<topicset>

Enables authors to define a branch of navigation in a DITA map so that it can be referenced from another DITA map.

<topicsetref>

Enables authors to reference a navigation branch that is defined in another DITA map.

<anchorref>

Enables authors to define a map fragment that is pushed to the location defined by an anchor.

Controlled values are keywords that can be used as values for attributes. For example, the @audience attribute can take a value that identifies the users that are associated with a particular product. Typical values for a medical-equipment product line might include "therapist", "oncologist", "physicist", and "radiologist". In a subject scheme map, an information architect can define a list of these values for the @audience attribute. Controlled values can be used to classify content for filtering and flagging at build time.

Subject definitions are classifications and sub-classifications that compose a tree. Subject definitions provide semantics that can be used in conjunction with taxonomies and ontologies. In conjunction with the classification domain, subject definitions can be used for retrieval and traversal of the content at run time when used with information viewing applications that provide such functionality.

Key references to controlled values are resolved to a key definition using the same precedence rules as apply to any other key. However, once a key is resolved to a controlled value, that key reference does not typically result in links or generated text.

Each controlled value is defined using a <subjectdef> element, which is a specialization of the <topicref> element. The <subjectdef> element is used to define both a subject category and a list of controlled values. The parent <subjectdef> element defines the category, and the children <subjectdef> elements define the controlled values.

The subject definitions can include additional information within a <topicmeta> element to clarify the meaning of a value:

• The <navtitle> element can provide a more readable value name.
• The <shortdesc> element can provide a definition.

In addition, the <subjectdef> element can reference a more detailed definition of the subject, for example, another DITA topic or an external resource..

The following behavior is expected of processors:

• Authoring tools SHOULD use these lists of controlled values to provide lists from which authors can select values when they specify attribute values.
• Authoring tools MAY give an organization a list of readable labels, a hierarchy of values to simplify selection, and a shared definition of the value.
• An editor MAY support accessing and displaying the content of the subject definition resource in order to provide users with a detailed explanation of the subject.
• Tools MAY produce a help file, PDF, or other readable catalog to help authors better understand the controlled values.

<subjectdef keys="terminology" href="https://www.oasis-open.org/policies-guidelines/keyword-guidelines">
  <subjectdef keys="rfc2119" href="rfc-2119.dita">
    <topicmeta>
      <navtitle>RFC-2119 terminology</navtitle>
      <shortdesc>The normative terminology that the DITA TC uses for the DITA specification</shortdesc>
    </topicmeta>
  </subjectdef>
  <subjectdef keys="iso" href="iso-terminology.dita">
    <topicmeta>
      <navtitle>ISO keywords</navtitle>
      <shortdesc>The normative terminology used by some other OASIS technical committees</shortdesc>
    </topicmeta>
  </subjectdef>
</subjectdef>

The <enumerationdef> element binds the set of controlled values to an attribute. Valid attribute values are those that are defined in the set of controlled values; invalid attribute values are those that are not defined in the set of controlled values. An enumeration can specify an empty <subjectdef> element. In that case, no value is valid for the attribute. An enumeration also can specify an optional default value by using the <defaultSubject> element.

If an enumeration is bound, processors SHOULD validate attribute values against the controlled values that are defined in the subject scheme map. For authoring tools, this validation prevents users from entering misspelled or undefined values. Recovery from validation errors is implementation specific.

The default attribute values that are specified in a subject scheme map apply only if a value is not otherwise specified in the DITA source or as a default value by the XML grammar.

To determine the effective value for a DITA attribute, processors check for the following in the order outlined:

1. An explicit value in the element instance
2. A default value in the XML grammar
3. Cascaded value within the document
4. Cascaded value from a higher level document to the document
5. A default controlled value, as specified in the <defaultSubject> element
6. A value set by processing rules

<subjectScheme>
  <!-- Define types of users -->
  <subjectdef keys="users">
    <subjectdef keys="therapist"/>
    <subjectdef keys="oncologist"/>
    <subjectdef keys="physicist"/>
    <subjectdef keys="radiologist"/>
  </subjectdef>

  <!-- Bind the "users" subject to the @audience attribute.
       This restricts the @audience attribute to the following
       values: therapist, oncologist, physicist, radiologist -->
  <enumerationdef>
    <attributedef name="audience"/>
    <subjectdef keyref="users"/>
  </enumerationdef>
</subjectScheme>

<subjectScheme>
  <enumerationdef>
    <attributedef name="outputclass"/>
    <subjectdef/>
  </enumerationdef>
</subjectScheme>

The following algorithm applies when processors apply filtering and flagging rules to attribute values that are defined as a hierarchy of controlled values and bound to an enumeration:

1. If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches.
2. Otherwise, if the parent value in the taxonomy has a rule, that matches.
3. Otherwise, continue up the chain in the taxonomy until a matching rule is found.

The following behavior is expected of processors:

• Processors SHOULD be aware of the hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization.
• Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. (The list of controlled values is not validated by basic XML parsers.) If the controlled values are part of a named key scope, the scope name is ignored for the purpose of validating the controlled values.
• Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning.

<subjectScheme>
  <subjectdef keys="users">
    <subjectdef keys="therapist">
      <subjectdef keys="novice-therapist"/>
      <subjectdef keys="expert-therapist"/>
    </subjectdef>
    <subjectdef keys="oncologist"/>
    <subjectdef keys="physicist"/>
    <subjectdef keys="radiologist"/>
  </subjectdef>
  <enumerationdef>
    <attributedef name="audience"/>
    <subjectdef keyref="users"/>
  </enumerationdef>
</subjectScheme>

The <schemeref> element provides a reference to another subject scheme map. Typically, the referenced subject-scheme map defines a base set of controlled values that are extended by the current subject-scheme map. The values in the referenced subject-scheme map are merged with the values in the current subject-scheme map; the result is equivalent to specifying all of the values in a single subject scheme map.

A taxonomy differs from a controlled values list primarily in the degree of precision with which the metadata values are defined. A controlled values list sometimes is regarded as the simplest form of taxonomy. Regardless of whether the goal is a simple list of controlled values or a taxonomy:

• The same core elements are used: <subjectScheme> and <subjectdef>.
• A category and its subjects can have a binding that enumerates the values of an attribute.

Beyond the core elements and the attribute binding elements, sophisticated taxonomies can take advantage of some optional elements. These optional elements make it possible to specify more precise relationships among subjects. The <hasNarrower>, <hasPart>, <hasKind>, <hasInstance>, and <hasRelated> elements specify the kind of relationship in a hierarchy between a container subject and its contained subjects.

While users who have access to sophisticated processing tools benefit from defining taxonomies with this level of precision, other users can safely ignore this advanced markup and define taxonomies with hierarchies of <subjectdef> elements that are not precise about the kind of relationship between the subjects.

<subjectScheme>
  <hasInstance>
    <subjectdef keys="city" navtitle="City">
      <subjectdef keys="la" navtitle="Los Angeles"/>
      <subjectdef keys="nyc" navtitle="New York City"/>
      <subjectdef keys="sf" navtitle="San Francisco"/>
    </subjectdef>
    <subjectdef keys="state" navtitle="State">
      <subjectdef keys="ca" navtitle="California"/>
      <subjectdef keys="ny" navtitle="New York"/>
    </subjectdef>
  </hasInstance>
  <hasPart>
    <subjectdef keys="place" navtitle="Place">
      <subjectdef keyref="ca">
        <subjectdef keyref="la"/>
        <subjectdef keyref="sf"/>
      </subjectdef>
      <subjectdef keyref="ny">
        <subjectdef keyref="nyc"/>
      </subjectdef>
    </subjectdef>
  </hasPart>
</subjectScheme>

The classification domain provides elements that enable map authors to indicate information about the subject matter of DITA topics. The subjects are defined in subjectScheme maps, and the map authors reference the subjects using the @keyref attribute.

The <metadata> element is a wrapper element that contains many of the metadata elements. In topics, the <metadata> element is available in the <prolog> element. In maps, the <metadata> element is available in the <topicmeta> element.

In DITA maps, the metadata elements also are available directly in the <topicmeta> element. Collections of metadata can be shared between DITA maps and topics by using the conref or keyref mechanism.

In general, specifying metadata in a <topicmeta> element is equivalent to specifying it in the <prolog> element of a referenced topic. The value of specifying the metadata at the map level is that the topic then can be reused in other maps where different metadata might apply. Many items in the <topicmeta> element also cascade to nested <topicref> elements within the map.

Context hook and windowing information is ignored if the processor does not support this metadata.

User interfaces for software application often are linked to user assistance (such as help systems and tool tips) through context hooks. Context hooks are identifiers that associate a part of the user interface with the location of a help topic. Context hooks can be direct links to URIs, but more often they are indirect links (numeric context identifiers and context strings) that can processed into external resource files. These external resource and mapping files are then used directly by context-sensitive help systems and other downstream applications.

Context hooks can define either one-to-one or one-to-many relationships between user interface controls and target help content.

The metadata that is available in <resourceid> and <ux-window> provides flexibility for content developers:

• You can overload maps and topics with all the metadata needed to support multiple target help systems. This supports single-sourcing of help content and help metadata.
• You can choose whether to add <resourceid> metadata to <topicref> elements, <prolog> elements, or both. Context-dependent metadata might be best be kept with maps, while persistent, context-independent metadata might best stay with topics in <prolog> elements

Context hook information is defined within DITA topics and DITA maps through attributes of the <resourceid> element.

In some help systems, a topic might need to be displayed in a specifically sized or featured window. For example, a help topic might need to be displayed immediately adjacent to the user interface control that it supports in a window of a specific size that always remains on top, regardless of the focus within the operating system. Windowing metadata can be defined in the DITA map within the <ux-window> element.

The <ux-window> element provides the @top, @left, @height, @width, @on-top, @features, @relative, and @full-screen attributes.

A key scope is defined by a <map> or <topicref> element that specifies the @keyscope attribute. The @keyscope attribute specifies the names of the scope, separated by spaces.

A key scope includes the following components:

• The scope-defining element
• The elements that are contained by the scope-defining element, minus the elements that are contained by child key scopes
• The elements that are referenced by the scope-defining element or its descendants, minus the elements that are contained by child key scopes

If the @keyscope attribute is specified on both a reference to a DITA map and the root element of the referenced map, only one scope is created; the submap does not create another level of scope hierarchy. The single key scope that results from this scenario has multiple names; its names are the union of the values of the @keyscope attribute on the map reference and the root element of the submap. This means that processors can resolve references to both the key scopes specified on the map reference and the key scopes specified on the root element of the submap.

The root element of a root map always defines a key scope, regardless of whether a @keyscope attribute is present. All key definitions and key references exist within a key scope, even if it is an unnamed, implicit key scope that is defined by the root element in the root map.

Each key scope has its own key space that is used to resolve the key references that occur within the scope. The key space that is associated with a key scope includes all of the key definitions within the key scope. This means that different key scopes can have different effective key definitions:

• A given key can be defined in one scope, but not another.
• A given key also can be defined differently in different key scopes.

Key references in each key scope are resolved using the effective key definition that is specified within its own key scope.

<map>
  <mapref keyscope="A" href="installation.ditamap"/>
  <!-- ... -->
</map>

<map keyscope="B">
  <!-- ... -->
</map>

A root map might contain any number of key scopes; relationships between key scopes are discussed using the following terms:

child scope

A key scope that occurs directly within another key scope. For example, in the figure below, key scopes "A-1" and "A-2" are child scopes of key scope "A".

parent scope

A key scope that occurs one level above another key scope. For example, in the figure below, key scope "A" is a parent scope of key scopes "A-1" and "A-2".

ancestor scope

A key scope that occurs any level above another key scope. For example, in the figure below, key scopes "A" and "Root" are both ancestor scopes of key scopes "A-1" and "A-2"

descendant scope

A key scope that occurs any level below another key scope. For example, in the figure below, key scopes "A", "A-1", and "A-2" are all descendant scopes of the implicit, root key scope

sibling scope

A key scope that shares a common parent with another key scope. For example, in the figure below, key scopes "A" and "B" are sibling scopes; they both are children of the implicit, root key scope.

key scope hierarchy

A key scope and all of its descendant scopes.

A key scope hierarchy

When maps are referenced and the value of the @scope attribute is set to "peer", the implications are that the two maps are managed in tandem, and that the author of the referencing map might have access to the referenced map. Adding a key scope to the reference indicates that the peer map should be treated as a separate deliverable for the purposes of linking.

The keys that are defined by the peer map belong to any key scopes that are declared on the <topicref> element that references that map. Such keys can be referenced from content in the referencing map by using scope-qualified key names. However, processors handle references to keys that are defined in peer maps differently from how they handle references to keys that are defined in submaps.

DITA processors are not required to resolve key references to peer maps. However, if all resources are available in the same processing or management context, processors have the potential to resolve key references to peer maps. There might be performance, scale, and user interface challenges in implementing such systems, but the ability to resolve any given reference is ensured when the source files are physically accessible.

Note the inverse implication; if the peer map is not available, then it is impossible to resolve the key reference. Processors that resolve key references to peer maps should provide appropriate messages when a reference to a peer map cannot be resolved. Depending on how DITA resources are authored, managed, and processed, references to peer maps might not be resolvable at certain points in the content life cycle.

The peer map might specify @keyscope on its root element. In that case, the @keyscope on the peer map is ignored for the purpose of resolving scoped key references from the referencing map. This avoids the need for processors to have access to the peer map in order to determine whether a given key definition comes from the peer map.

<map>
  <title>Map A</title>
  <topicref 
    scope="peer"
    format="ditamap"
    keyscope="map-b"
    href="../map-b/map-b.ditamap"
    processing-role="resource-only"
  />
  <!-- ... -->
</map>

<mapref 
  keyscope="scope-b"
  scope="peer"  
  href="map-b.ditamap"
/> 

<map keyscope="product-x">
 <!-- ... -->
</map>

When a key definition is bound to a resource that is addressed by the @href or @keyref attributes, and does not specify "none" for the @linking attribute, all references to that key definition become links to the bound resource. When a key definition is not bound to a resource or specifies "none" for the @linking attribute, references to that key definition do not become links.

When a key definition has no @href value and no @keyref value, references to that key will not result in a link, even if they do contain an @href attribute of their own. If the key definition also does not contain a <topicmeta> subelement, empty elements that refer to the key (such as <link keyref="a"/> or <xref keyref="a" href="fallback.dita"/>) are ignored.

The <object> element has additional key-referencing attributes (@archivekeyrefs, @classidkeyref, @codebasekeyref, and @datakeyref). Key names in these attributes are resolved using the same processing that is described for the normal @keyref attribute.

For topic references that use the @keyref attribute, the effective value of the <topicref> element is determined in the following way:

Determining the effective resource

The effective resource bound to the <topicref> element is determined by resolving all intermediate key references. Each key reference is resolved either to a resource addressed directly by URI reference in an @href attribute, or to no resource. Processors MAY impose reasonable limits on the number of intermediate key references that they will resolve. Processors SHOULD support at least three levels of key references.

Note

This rule applies to all topic references, including those that define keys. The effective bound resource for a key definition that uses the @keyref attribute cannot be determined until the key space has been constructed.

Combining metadata

Content from a key-defining element cascades to the key-referencing element following the rules for combining metadata between maps and other maps and between maps and topics. The @lockmeta attribute is honored when metadata content is combined.

The combined attributes and content cascade from one map to another or from a map to a topic, but this is controlled by existing rules for cascading, which are not affected by the use of key references.

If, in addition to the @keys attribute, a key definition specifies a @keyref attribute that can be resolved after the key resolution context for the key definition has been determined, the resources bound to the referenced key definition take precedence.

Empty elements that include a key reference with a defined key might get their effective content from the key definition. Empty elements are defined as elements that meet the following criteria:

• Have no text content, including white space
• Have no sub-elements
• Have no attributes that would be used as text content (such as @alt on the <image> element)

When an empty element as defined above references a key definition that has a child <topicmeta> element, content from that <topicmeta> element is used to determine the effective content of the referencing element. Effective content from the key definition becomes the element content, with the following exceptions:

• For empty <image> elements, effective content is used as alternate text, equivalent to creating an <alt> sub-element to hold that content.
• For empty <link> elements, effective content is used as link text, equivalent to creating a <linktext> sub-element to hold that content.
• For empty <link> and <xref> elements, a key definition can be used to provide a short description in addition to the normal effective content. If the key definition includes <shortdesc> inside of <topicmeta>, that <shortdesc> should be used to provide effective content for a <desc> sub-element.
• The <longdescref> and <longquoteref> elements are empty elements with no effective content. Key definitions are not used to set effective text for these elements.
• The <param> element does not have any effective content, so key definitions do not result in any effective content for <param> elements.
• The <indextermref> element is not completely defined, so determining effective content for this element is also left undefined.

Effective text content is determined using the following set of rules:

1. For elements that also exist as a child of <topicmeta> in the key definition, effective content is taken from the first matching direct child of <topicmeta>. For example, given the following key definition, an empty <author> element with the attribute keyref="justMe" would result in the matching content "Just M. Name":

   <keydef keys="justMe" href="http://www.example.com/my-profile" format="html" scope="external">
     <topicmeta>
       <author>Just M. Name</author>
     </topicmeta>
   </keydef>

2. For elements that do not allow the @href attribute, content is taken from the first <keyword> element inside of <keywords> inside of the <topicmeta>. For example, given the following key definition, empty <keyword>, <term>, and <dt> elements with the attribute keyref="nohref" would all result in the matching content "first":

   <keydef keys="nohref">
     <topicmeta>
       <keywords><keyword>first</keyword><keyword>second</keyword><keyword>third</keyword></keywords>
     </topicmeta>
   </keydef>

3. For elements that do allow @href, elements from within <topicmeta> that are legal within the element using @keyref are considered matching text. For example, the <xref> element allows @href, and also allows <keyword> as a child. Using the code sample from the previous item, an empty <xref> with keyref="nohref" would use all three of these elements as text content; after processing, the result would be equivalent to:

   <xref keyref="test"><keyword>first</keyword><keyword>second</keyword><keyword>third</keyword></xref>

4. Otherwise, if <linktext> is specified inside of <topicmeta>, the contents of <linktext> are used as the effective content.

   Note

   Because all elements that get effective content will eventually look for content in the <linktext> element, using <linktext> for effective content is a best practice for cases where all elements getting text from a key definition should result in the same value.
5. Otherwise, if the element with the key reference results in a link, normal link text determination rules apply as they would for <xref> (for example, using the <navtitle> or falling back to the URI of the link target).

When the effective content for a key reference element results in invalid elements, those elements SHOULD be generalized to produce a valid result. For example, <linktext> in the key definition might use a domain specialization of <keyword> that is not valid in the key reference context, in which case the specialized element should be generalized to <keyword>. If the generalized content is also not valid, a text equivalent should be used instead. For example, <linktext> might include <ph> or a specialized <ph> in the key definition, but neither of those are valid as the effective content for a <keyword>. In that case, the text content of the <ph> should be used.

When a map contains a topic reference to a map (often called a map reference), processors should integrate the navigation tree of the referenced map with the navigation tree of the referencing map at the point of reference. In this way, a deliverable can be compiled from multiple DITA maps.

The effective navigation title is used for the value of the TOC node. A TOC node is generated for every <topicref> element that references a topic or specifies a navigation title, except in the following cases:

• The @processing-role attribute that is specified on the <topicref> element or an ancestor element is set to "resource-only".
• Conditional processing is used to filter out the node or an ancestor node.
• The @print attribute is specified on the <topicref> element or an ancestor element, and the current processing does not match the value set by the @print attribute. For example, print="printonly" and the output format is XHTML-based, or print="no" and the output format is PDF. (Note that the @print attribute is deprecated in DITA 1.3; it is replaced by the @deliveryTarget attribute.)
• There is no information from which a TOC entry can be constructed; there is no referenced resource or navigation title.
• The node is a <topicgroup> element, even if it specifies a navigation title.

To suppress a <topicref> element from appearing in the TOC, set the @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 children of the <topicref> element are also excluded from the TOC. If a child <topicref> overrides the cascading operation by specifying toc="yes", then the node that specifies toc="yes" appears in the TOC (minus the intermediate nodes that set @toc to "no").

The specialized indexing domain also provides elements to enable additional indexing function, such as "See" and "See also".

For more information, see Indexing group elements.

This topic uses the definitions of referenced element and referencing element as defined in DITA terminology and notation.

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 elements that is rendered in place of the referencing element. Although the start and end elements must be of the same type as the referencing element (or specialized from that element type), the elements inside the range can be any type.

Pushing content from the referencing element

The @conaction attribute reverses the direction of reuse from pull to push. With a push, the referencing element is rendered before, after, or in place of the referenced element. The location (before, after, or in place of) is determined by the value of the @conaction attribute. Because the @conaction and @conrefend attributes cannot both be used within the same referencing element, it is not possible to push a range of elements.

A fragment of DITA content, such as an XML document that contains only a single paragraph without a topic 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 one of the following items:

• A referenced element within a DITA map
• A referenced element within a DITA topic
• An entire DITA map
• An entire DITA topic

Except where allowed by weak constraints, 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 set of domains declared on the @domains attribute in the referenced topic or map instance is the same as or a subset of the 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.

When pushing content with the conref mechanism, the domain checking algorithm is reversed. In this case, if the set of domains declared on the @domains attribute in the referencing topic or map instance is the same as or a subset of the domains declared in the referenced document, the element set allowed in the pushed content is guaranteed to be the same as, or a subset of, the element set allowed in the new location.

In both cases, processors resolving conrefs SHOULD tolerate specializations of valid elements and generalize elements in the pushed or pulled content fragment as needed for the resolving context.

The attribute specifications on the resolved element are 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 set to "-dita-use-conref-target".
2. All attributes as specified on the referenced element except the @id attribute.
3. The @xml:lang attribute has special treatment as described in The @xml:lang attribute.

The token -dita-use-conref-target is defined by the specification to enable easier use of @conref on elements with required attributes. 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 element MUST 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 @audience) 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 topic A and topic C allow highlighting, and topic B does not, then a content reference chain of topic A-to-topic B-to-topic C 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 topic A.

Direct URI reference (but not a same-topic fragment identifier )

When the address is a direct URI reference of any form other than a same-topic fragment identifier, processors MUST resolve it relative to the source document that contains the original URI reference.

Same-topic fragment identifier

When the address is a same-topic fragment identifier, processors MUST resolve it relative to the location of the content reference (referencing context).

Key reference

When the address is a key reference, processors MUST resolve it relative to the location of the content reference (referencing context).

When resolving key references or same-topic fragment identifiers, the phrase location of the content reference means the final resolved context. For example, in a case where content references are chained (topic A pulls from topic B, which in turn pulls a reference from topic C), the reference is resolved relative to the topic that is rendered. When topic B is rendered, the reference is resolved relative to the content reference in topic B; when topic A is rendered, the reference is resolved relative to topic A. If content is pushed from topic A to topic B to topic C, then the same-topic fragment identifier is resolved in the context of topic C.

The implication is that a content reference or cross reference can resolve to different targets in different use contexts. This is because a URI reference that contains a same-topic fragment identifier is resolved in the context of the topic that contains the content reference, and a key reference is resolved in the context of the key scope that is in effect for each use of the topic that contains the content reference.

<topic id="paras-01"><title>Reusable paragraphs</title>
    <body>
        <p id="p1">See <xref href="#paras-01/p5"/>.</p>
        <p id="p2">See <xref href="topic-02.dita#topic02/fig-01"/>.</p>
        <p id="p3">See <xref href="#./p5"/>.</p>
        <p id="p4">See <xref keyref="task-remove-cover"/>.</p>
        <p id="p5">Paragraph 5 in paras-01.</p>
    </body>
</topic>

<topic id="using-topic-01"><title>Using topic one</title>
    <body>
        <p id="A" conref="paras-01.dita#paras-01/p1"/> 
        <p id="B" conref="paras-01.dita#paras-01/p2"/> 
        <p id="C" conref="paras-01.dita#paras-01/p3"/>
        <p id="D" conref="paras-01.dita#paras-01/p4"/>
        <p id="p5">Paragraph 5 in using-topic-01</p>  
    </body>
</topic>

<map>
  <topicgroup keyscope="product-1">
    <topicref keys="task-remove-cover" href="prod-1-task-remove-cover.dita"/>
    <topicref href="using-topic-01.dita"/>
  </topicgroup>
  <topicgroup keyscope="product-2">
    <topicref keys="task-remove-cover" href="prod-2-task-remove-cover.dita"/>
    <topicref href="using-topic-01.dita"/>
  </topicgroup>
</map>

For example, the string values within @product in <p product="basic deluxe"> indicate that the paragraph applies to the “basic” product and to the “deluxe” product.

Groups organize classification metadata into subcategories. This is intended to support situations where a predefined metadata attribute applies to multiple specialized subcategories. For example, the @product attribute can be used to classify an element based on both related databases and related application servers. Using groups for these subcategories allows each category to be processed independently; when filter conditions exclude all applicable databases within a group, the element can be safely excluded, regardless of any other @product conditions.

Groups can be used within @audience, @product, @platform, or @otherprops. The following rules apply:

• Groups consist of a name immediately followed by a parenthetical group of one or more space-delimited string values. For example, "groupName(valueOne valueTwo)".
• Groups cannot be nested.
• If two groups with the same name are found in a single attribute, they should be treated as if all values are specified in the same group. The following values for the @otherprops attribute are equivalent:

  otherprops="groupA(a b) groupA(c) groupZ(APPNAME)"
  otherprops="groupA(a b c) groupZ(APPNAME)"

• If both grouped values and ungrouped values are found in a single attribute, the ungrouped values belong to an implicit group; the name of that group matches the name of the attribute. Therefore, the following values for the @product attribute are equivalent:

  product="a database(dbA dbB) b appserver(mySERVER) c"
  product="product(a b c) database(dbA dbB) appserver(mySERVER)"

Setting a conditional processing attribute to an empty value, such as product="", is equivalent to omitting that attribute from the element. An empty group within an attribute is equivalent to omitting that group from the attribute. For example, <ph product="database() A"> is equivalent to <ph product="A">. Combining both rules into one example, <ph product="operatingSystem()"> is equivalent to <ph>.

If two groups with the same name exist on different attributes, a rule specified for that group will evaluate the same way on each attribute. For example, if the group "sampleGroup" is specified within both @platform and @otherprops, a DITAVAL rule for sampleGroup="value" will evaluate the same in each attribute. If there is a need to distinguish between similarly named groups on different attributes, the best practice is to use more specific group names such as platformGroupname and productGroupname. Alternatively, DITAVAL rules can be specified based on the attribute name rather than the group name.

If the same group name is used in different attributes, a complex scenario could be created where different defaults are specified for different attributes, with no rule set for a group or individual value. In this case a value might end up evaluating differently in the different attributes. For example, a DITAVAL can set a default of "exclude" for @platform and a default of "flag" for @product. If no rules are specified for group oddgroup(), or for the value oddgroup="edgecase", the attribute platform="oddgroup(edgecase)" will evaluate to "exclude" while product="oddgroup(edgecase)" will resolve to "flag". See DITAVAL elements for information on how to change default behaviors in DITAVAL provile.

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 can change this default to "exclude", so that any value not explicitly defined in the DITAVAL profile will evaluate to "exclude". The DITAVAL profile also can be used to change the default for a single attribute; for example, it can 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 independently:

1. For each attribute:
   • If the attribute is empty, or contains only empty groups, it is equivalent to omitting the attribute from the element. If evaluated for the purposes of filtering, the attribute is treated as "include", because an omitted attribute cannot evaluate to "exclude".
   • If the attribute value does not contain any groups, then if any token in the attribute value evaluates to "include", the element evaluates to "include"; otherwise it evaluates to "exclude". In other words, the attribute evaluates to "exclude" only when all the values in that attribute evaluate to "exclude".
   • If the attribute value does include groups, evaluate as follows, treating ungrouped tokens together as a group:
     1. For each group (including the group of ungrouped tokens), if any token inside the group evaluates to "include", the group evaluates to "include"; otherwise it evaluates to "exclude". In other words, a group evaluates to "exclude" only when every token in that group evaluates to "exclude".
     2. If any group within an attribute evaluates to "exclude", that attribute evaluates to "exclude"; otherwise it evaluates to "include".
2. 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.

Similarly, with groups, a step might apply to one application server and two database applications:

<steps>
  <step><cmd>Common step</cmd></step>
  <step product="appserver(mySERVER) database(ABC dbOtherName)">
    <cmd>Do something special for databases ABC or OtherName when installing on mySERVER</cmd>
  </step>
  <!-- additional steps -->
</steps>

If a publisher decides to exclude the application server mySERVER, then the appserver() group evaluates to exclude. This can be done by setting product="mySERVER" to exclude or by setting appserver="mySERVER" to exclude. This means the step should be excluded, regardless of how the values "ABC" or "dbOtherName" evaluate. If a rule is specified for both product="mySERVER" and appserver="mySERVER", the rule for the more specific group name "appserver" takes precedence.

Similarly, if both "ABC" and "dbOtherName" evaluate to exclude, then the database() group evaluates to exclude and the element should be excluded regardless of how the "mySERVER" value is set.

In more advanced usage, a DITAVAL can be used to specify a rule for a group name. For example, an author could create a DITAVAL rule that sets product="database" to "exclude". This is equivalent to setting a default of "exclude" for any individual value in a database() group; it also excludes the more common usage of "database" as a single value within the @product attribute. Thus when "myDB" appears in a database() group within the @product attribute, the full precedence for determining whether to include or exclude the value is as follows:

1. Check for a DITAVAL rule for database="myDB"
2. Check for a DITAVAL rule for product="myDB"
3. Check for a DITAVAL rule for product="database" (default for the database group)
4. Check for a DITAVAL rule for "product" (default for the @product attribute)
5. Check for a default rule for all conditions (default of include or exclude for all attributes)
6. Otherwise, evaluate to "include"

At processing time, a conditional processing profile can be used to specify profiling attribute values that determine whether an element with those values is flagged.

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

When the same element evaluates as both flagged and included, the element should be flagged and included. When the same element evaluates as both flagged and filtered (for example, flagged because of a value for the @audience attribute and filtered because of a value for the @product attribute value), the element should be filtered.

Within maps, topic references can use the @deliveryTarget attribute to indicate the delivery targets to which they apply. The map or topic references can still use the deprecated @print attribute to indicate whether they are applicable to print deliverables.

Within topics, most elements can use the @deliveryTarget attribute to indicate the delivery targets to which they apply.

If a referenced topic should be excluded from all output formats, set the @processing-role attribute to "resource-only" instead of using the @deliveryTarget or @print attribute. Content within that topic can still be referenced for display in other locations.

The <ditavalref> element is designed to manage conditional processing for the following use cases.

1. A map branch needs to be filtered using conditions that do not apply to the rest of the publication. For example, a root map might contain content that is written for both novice and expert users. However, the authors want to add a section that targets only novice users. Using branch filtering, a map branch can be filtered so that it only includes content germane to a novice audience, while the content of the rest of the map remains appropriate for multiple audiences.
2. A map branch needs to be presented differently for different audiences. For example, a set of software documentation might contain installation instructions that differ between operating systems. In that case, the map branch with the installation instructions needs to be filtered multiple times with distinct sets of conditions, while the rest of the map remains common to all operating systems.

Filtering rules often are specified globally, outside of the content. When global conditions set a property value to "exclude", that setting overrides any other settings for the same property that are specified at a branch level. Global conditions that set a conditional property to "include" or "flag" do not override branch-level conditions that set the same property to "exclude".

Using <ditavalref> elements, it is possible to specify one set of conditions for a branch and another set of conditions for a subset of the branch. As with global conditions, properties set to "exclude" for a map branch override any other settings for the same property specified for a subset of the branch. Branch conditions that set a conditional property to "include" or "flag" do not override conditions on a subset of the branch that explicitly set the same property to "exclude".

In addition to filtering, applications MAY support flagging at the branch level based on conditions that are specified in referenced DITAVAL documents.

The following rules outline how the filtering conditions that are specified in DITAVAL document are applied:

<ditavalref> element as a direct child of a map

The filtering conditions are applied to the entire map.

<ditavalref> element within a map branch

The filtering conditions are used to process the entire branch, including the parent element that contains the <ditavalref> element.

<ditavalref> element within a <topicref> reference to a local map

The filtering conditions are applied to the submap.

<ditavalref> element within a <topicref> reference to peer map

The reference conditions are not applied to the peer map.

When multiple <ditavalref> elements occur as children of the same element, the rules in the referenced DITAVAL documents are processed independently. This effectively requires a processor to maintain one copy of the branch for each <ditavalref>, so that each copy can be filtered using different conditions.

When a processor maintains multiple copies of a branch for different condition sets, it has to manage situations where a single resource with a single key name results in two distinct resources. Key names must be modified in order to allow references to a specific filtered copy of the resource; without renaming, key references could only be used to refer to a single filtered copy of the resource, chosen by the processor. See Branch filtering: Impact on resource and key names for details on how to manage resource names and key names.

When a map branch uses multiple condition sets, processors create multiple effective copies of the branch to support the different conditions. This results in potential conflicts for resource names, key names, and key scopes. Metadata elements inside of the <ditavalref> element are available to provide control over these values, so that keys, key scopes, and URIs can be individually referenced within a branch.

For example, the following map branch specifies two DITAVAL documents:

<topicref href="productFeatures.dita" keys="features" keyscope="prodFeatures">
  <ditavalref href="novice.ditaval"/>
  <ditavalref href="admin.ditaval"/>
  <topicref href="newFeature.dita" keys="newThing"/>
</topicref>

In this case, the processor has two effective copies of productFeatures.dita and newFeature.dita. One copy of each topic is filtered using the conditions specified in novice.ditaval, and the other copy is filtered using the conditions specified in admin.ditaval. If an author has referenced a topic using keyref="features" or keyref="prodFeatures.features", there is no way for a processor to distinguish which filtered copy is the intended target.

<topicref href="productFeatures.dita" keys="features" keyscope="prodFeatures">
  <ditavalref href="novice.ditaval"/>
  <ditavalref href="admin.ditaval">
    <ditavalmeta>
      <dvrResourcePrefix>admin-</dvrResourcePrefix>
      <dvrKeyscopePrefix>adminscope-</dvrKeyscopePrefix>
    </ditavalmeta>
  </ditavalref>
  <topicref href="newFeature.dita" keys="newThing"/>
</topicref>

<topicref href="branchParent.dita">
  <ditavalref href="parent.ditaval">
    <ditavalmeta>
      <dvrResourcePrefix>parentPrefix-</dvrResourcePrefix>
    </ditavalmeta>
  </ditavalref>
  <!-- additional topics or layers of nesting -->
  <topicref href="branchChild.dita">
    <ditavalref href="child.ditaval">
      <ditavalmeta>
        <dvrResourcePrefix>childPrefix-</dvrResourcePrefix>
      </ditavalmeta>
    </ditavalref>
  </topicref>
</topicref>

In general, the DITA specification refrains from mandating a processing order; thus publication results can vary slightly depending on the order in which processes are run. With branch filtering, processors are not required to apply filter conditions specified outside of the map and filter conditions specified with <ditavalref> at the same time in a publishing process.

For example, a processor might use the following processing order:

1. Apply externally-specified filter conditions to maps
2. Apply filtering based on <ditavalref> elements

Because externally-specified "exclude" conditions always take precedence over branch-specific conditions, content excluded based on external conditions will always be removed, regardless of the order in which processors evaluate conditions.

Processors should consider the following points when determining a processing order:

• If links are generated based on the map hierarchy, those links should be created using the renamed keys and URIs that result from evaluating the <ditavalref> filter conditions, to ensure that the links are consistent within the modified branches. For example, sequential links based on a map hierarchy should remain within the appropriate modified branch.
• If conrefs are resolved in topics before the <ditavalref> filtering conditions are evaluated, content that applies to multiple audiences can be brought in and (later in the process) selectively filtered by branch. For example, if a set of installation steps is pulled in with conref (from outside the branch), it might contain information that is later filtered by platform based on <ditavalref>. This results in copies of the steps that are specific to each operating system. If conref is processed after the <ditavalref>, content might be pulled in that has not been appropriately filtered for the new context.
• The same scenario applies to conref values that push content into the branch.
  • Pushing content into a branch before resolving the <ditavalref> conditions allows content for multiple conditions to be pushed and then filtered by branch based on the <ditavalref> conditions.
  • If the branch using <ditavalref> pushes content elsewhere, resolving <ditavalref> first could result in multiple copies of the content to be pushed (one for each branch), resulting in multiple potentially conflicting copies pushed to the new destination.

A DITA document must either have an associated document-type definition or all required attributes must be made explicit in the document instances. Most DITA documents have an associated document-type shell. DITA documents that reference a document-type shell can be validated using standard XML processors. Such validation enables processors to read the XML grammar files and determine default values for the @domains and @class attributes.

The following figure illustrates the relationship between a DTD-based DITA document, its document-type shell, and the various vocabulary modules that it uses. A similar structure applies to DITA documents that use other XML grammars.

Document type shell

The DITA specification contains a starter set of document-type shells. These document type shells are commented and can be used as templates for creating custom document-type shells. While the OASIS-provided document-type shells can be used without any modification, creating custom document-type shells is a best practice. If the document-type shells need to be modified in the future, for example, to include a specialization or integrate a constraint, the existing DITA documents will not need to be modified to reference a new document-type shell.

• While the DITA specification only defines coding requirements for DTD, RELAX NG, and XML Schema documents, conforming DITA documents MAY use other document-type constraint languages, such as Schematron.

• With two exceptions, a document-type shell MUST NOT directly define element or attribute types; it only includes and configures vocabulary and constraint modules. The exceptions to this rule are the following:

  • The ditabase document-type shell directly defines the <dita> element.
  • RNG- and XML Schema-based shells directly specify values for the @domains attribute; these values reflect the details of the domains and structural types that are integrated by the document-type shell.
• Document type shells that are not provided by OASIS MUST have a unique public identifier, if public identifiers are used.

• Document type shells that are not provided by OASIS MUST NOT indicate OASIS as the owner; the public identifier or URN for such document-type shells SHOULD reflect the owner or creator of the document-type shell.

  For example, if example.com creates a copy of the document type shell for topic, an appropriate public identifier would be "-//example.com//DTD DITA Topic//EN", where "example.com" is the owner identifier component of the public identifier. An appropriate URN would be "urn:example.com:names:dita:rng:topic.rng".

A DITA document type is defined by the following:

• The set of modules that are declared in the @domains attribute on the root element of the document
• The values of the @class attributes of all the elements in the document
• Rules for topic nesting

Two document-type shells define the same DITA document type if they integrate identical vocabulary modules, constraint modules, and rules for topic nesting. For example, a document type shell that is an unmodified copy of the OASIS-provided document-type shell for topic defines the same DITA document type as the original document-type shell. However, the new document-type shell has the following differences:

• It is a distinct file that is stored in a different location.
• It has a distinct system identifier.
• If it has a public identifier, the public identifier is unique.

Conforming DITA documents are not required to have any governing document type declaration or schema. There might be compelling or practical reasons to use non-conforming document-type shells. For example, a document might use a document-type shell that does not conform to the DITA requirements for shells in order to meet the needs of a specific application or tool. Such a non-conforming document-type shell still might enable the creation of conforming DITA content.

Specialization modules enable information architects to create new element types and attributes. These new element types and attributes are derived from existing element types and attributes.

In traditional XML applications, all semantics for a given element instance are bound to the element type, such as <para> for a paragraph or <title> for a title. The XML specification provides no built-in mechanism for relating two element types to say "element type B is a subtype of element type A".

In contrast, the DITA specialization mechanism provides a standard mechanism for defining that an element type or attribute is derived from an ancestor type. This means that a specialized type inherits the semantics and default processing behavior from its ancestor type. Additional processing behavior optionally can be associated with the specialized descendant type.

For example, the <section> element type is part of the DITA base or core. It represents an organizational division in a topic. Within the task information type (itself a specialization of <topic>), the <section> element type is further specialized to other element types (such as <prereq> and <context>) that provide more precise semantics about the type of organizational division that they represent. The specialized element types inherit both semantic meaning and default processing from the ancestor elements.

There are two types of DITA specializations:

Structural specialization

Structural specializations are developed from either topic or map types. Structural specializations enable information architect to add new document types to DITA. The structures defined in the new document types either directly use or inherit from elements found in other document types. For example; concept, task, and reference are specialized from topic, whereas bookmap is specialized from map.

Domain specialization

Domain specializations are developed from elements defined with topic or map, or from the @props or @base attributes. They define markup for a specific information domain or subject area. Domain specialization can be added to document-type shells.

Each type of specialization module represents an “is a” hierarchy, in object-oriented terms, with each structural type or domain being a subclass of its parent. For example, a specialization of task is still a task, and a specialization of the user interface domain is still part of the user interface domain. A given domain can be used with any map or topic type. In addition, specific structural types might require the use of specific domains.

Use specialization when you need a new structural type or domain. Specialization is appropriate in the following circumstances:

• You need to create markup to represent new semantics (meaningful categories of information). This might enable you to have increased consistency or descriptiveness in your content model.
• You have specific needs for output processing and formatting that cannot be addressed using the current content model.

Do not use specialization to simply eliminate element types from specific content models. Use constraint modules to restrict content models and attribute lists without changing semantics.

The DITA XML grammar files are a set of module files that declare the markup and entities that are required for each specialization. The document-type shell then integrates the modules that are needed for a particular authoring and publishing context.

Because all the pieces are modular, the task of developing a new information type or domain is easy. An information architect can start with existing base types (topic or map) -- or with an existing specialization if it comes close to matching their business requirements -- and only develop an extension that adds the extra semantics or functionality that is required. A specialization reuses elements from ancestor modules, but it only needs to declare the elements and attributes that are unique to the specialization. This saves considerable time and effort; it also reduces error, enforces consistency, and makes interoperability possible.

Because all the pieces are modular, it is easy to reuse different modules in different contexts. For example, a company that produces machines can use the task requirements and hazard statements domains, while a company that produces software can use the software, user interface, and programming domains. A company that produces health information for consumers can avoid using any of the standard domains, and instead develop a new domain that contains the elements necessary for capturing and tracking the comments made by medical professionals who review their information for accuracy and completeness.

Because all the pieces are modular, new modules can be created and put into use without affecting existing document-type shells. For example, a marketing division of a company can develop a new specialization for message campaigns and have their content authors begin using that specialization, without affecting any of the other information types that they have in place.

The following terminology is used to refer to DITA vocabulary modules:

structural module

A vocabulary module that defines a top-level map or topic type. Structural modules also can define specializations of, or reuse elements from, domain or other structural modules. When this happens, the structural module becomes dependent.

element domain module

A vocabulary module that defines one or more specialized element types that can be integrated with maps or topics.

attribute domain module

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

For structural types, the module name is typically the same as the root element. For example, "task" is the name of the structural vocabulary module whose root element is <task>.

For element domain modules, the module name is typically a name that reflects the subject domain to which the domain applies, such as "highlight" or "software". Domain modules often have an associated short name, such as "hi-d" for the highlighting domain or "sw-d" for the software domain.

The name (or short name) of an element domain module is used to identify the module in @class and @domains attribute values. While module names need not be globally unique, module names must be unique within the scope of a given specialization hierarchy. The short name must be a valid XML name token.

Structural modules based on topic MAY define additional topic types that are then allowed to occur as subordinate topics within the top-level topic. However, such subordinate topic types MAY NOT be used as the root elements of conforming DITA documents. For example, a top-level topic type might require the use of subordinate topic types that would only ever be meaningful in the context of their containing type and thus would never be candidates for standalone authoring or aggregation using maps. In that case, the subordinate topic type can be declared in the module for the top-level topic type that uses it. However, in most cases, potential subordinate topics should be defined in their own vocabulary modules.

Domain elements intended for use in topics MUST ultimately be specialized from elements that are defined in the topic module. Domain elements intended for use in maps MUST ultimately be specialized from elements defined by or used in the map module. Maps share some element types with topics but no map-specific elements can be used within topics.

A specialized element type has the following characteristics:

• A properly-formed @class attribute that specifies the specialization hierarchy of the element
• A content model that is the same or less inclusive than that of the element from which it was specialized
• A set of attributes that are the same or a subset of those of the element from which it was specialized
• Values or value ranges of attributes that are the same or a subset of those of the element from which it was specialized

DITA elements are never in a namespace. Only the @DITAArchVersion attribute is in a DITA-defined namespace. All other attributes, except for those defined by the XML standard, are in no namespace.

This limitation is imposed by the details of the @class attribute syntax, which makes it impractical to have namespace-qualified names for either vocabulary modules or individual element types or attributes. Elements included as descendants of the DITA <foreign> element type can be in any namespace.

A specialized attribute has the following characteristics:

• It is specialized from @props or @base.
• It is declared as a global attribute. Attribute specializations cannot be limited to specific element types.
• It does not have values or value ranges that are more extensive than those of the attribute from which it was specialized.
• Its values must be alphanumeric space-delimited values. In generalized form, the values must conform to the rules for attribute generalization.

The @class attribute tells a processor what general classes of elements the current element belongs to. DITA scopes elements by module type (for example topic type, domain type, or map type) instead of document type, which lets document type developers combine multiple module types in a single document without complicating transformation logic.

The sequence of values in the @class attribute is important because it tells processors which value is the most general and which is most specific. This sequence is what enables both specialization aware processing and generalization.

<!ATTLIST step         class  CDATA "- topic/li task/step ">

<wintitle class="+ topic/keyword ui-d/wintitle ">A specialized keyword</wintitle>

<windowname class="- topic/keyword task/keyword guitask/windowname ">...</windowname>