Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive 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.
• The <abbreviated-form> element is an empty element with special rules that determine its effective content.

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

1. For the <abbreviated-form> element, see the rules described in <abbreviated-form>
2. 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>

3. 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>

4. 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>

5. 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.
6. 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".