DITA maps

This topic collection contains information about DITA maps and the purposes that they serve. It also includes high-level information about DITA map elements, attributes, and metadata.

Definition of DITA maps

DITA maps are documents that organize topics and other resources into structured collections of information. DITA maps specify hierarchy and the relationships among the topics; they also provide the contexts in which keys are defined and resolved.

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, and subject scheme maps represent taxonomic or ontological classifications. 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.

Purpose of DITA maps

DITA maps enable the scalable reuse of content across multiple contexts. They can be used by information architects, writers, and publishers to plan, develop, and deliver content.

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.

DITA map attributes

DITA maps have unique attributes that are designed to control the way that relationships are interpreted for different output purposes. In addition, DITA maps share many metadata and linking attributes with DITA topics.

DITA maps often encode structures that are specific to a particular medium or output, for example, Web pages or a PDF document. Attributes, such as @deliveryTarget and @toc, are designed to help processors interpret the DITA map for each kind of output.

Many of the following attributes are not available in DITA topics; individual topics, once separated from the high-level structures and dependencies associated with a particular kind of output, should be entirely reusable regardless of the intended output format.

@cascade

Specifies whether the default rules for the cascading of metadata attributes in a DITA map apply. The following values are specified:

merge
Indicates that the metadata attributes cascade, and that the values of the metadata attributes are additive. This is the processing default for the @cascade attribute.
nomerge
Indicates that the metadata attributes cascade, but that they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered. That is, setting cascade="nomerge" does not undo merging that took place on ancestor elements.

For more information, see Example: How the cascade attribute affects attribute cascading.

@chunk
Specifies that the processor generates an interim set of DITA topics that are used as the input for the final processing. This can produce the following output results:
  • Multi-topic files are transformed into smaller files, for example, individual HTML files for each DITA topic.
  • Individual DITA topics are combined into a single file.

Specifying a value for the @chunk attribute on a <map> element establishes chunking behavior that applies to the entire map, unless overridden by @chunk attributes that are set on more specific elements in the DITA map. For a detailed description of the @chunk attribute and its usage, see Chunking.

@collection-type
The @collection-type attribute specifies how the children of a <topicref> element relate to their parent and to each other. This attribute, which is set on the parent element, typically is used by processors to determine how to generate navigation links in the rendered topics. For example, a @collection-type value of "sequence" indicates that children of the specifying <topicref> element represent an ordered sequence of topics; processors might add numbers to the list of child topics or generate next/previous links for online presentation. This attribute is available in topics on the <linklist> and <linkpool> elements, where it has the same behavior. Where the @collection-type attribute is available on elements that cannot directly contain elements, the behavior of the attribute is undefined.
@keys
Specifies one or more key names.
@keyscope
Defines a new scope for key definition and resolution, and gives the scope one or more names. For more information about key scopes, see Indirect key-based addressing.
@linking

By default, the relationships between the topics that are referenced in a map are reciprocal:

  • Child topics link to parent topics and vice versa.
  • Next and previous topics in a sequence link to each other.
  • Topics in a family link to their sibling topics.
  • Topics referenced in the table cells of the same row in a relationship table link to each other. A topic referenced within a table cell does not (by default) link to other topics referenced in the same table cell.

This behavior can be modified by using the @linking attribute, which enables an author or information architect to specify how a topic participates in a relationship. The following values are valid:

linking="none"
Specifies that the topic does not exist in the map for the purposes of calculating links.
linking="sourceonly"
Specifies that the topic will link to its related topics but not vice versa.
linking="targetonly"
Specifies that the related topics will link to it but not vice versa.
linking="normal"
Default value. It specifies that linking will be reciprocal (the topic will link to related topics, and they will link back to it).

Authors also can create links directly in a topic by using the <xref> or <link> elements, but in most cases map-based linking is preferable, because links in topics create dependencies between topics that can hinder reuse.

Note that while the relationships between the topics that are referenced in a map are reciprocal, the relationships merely imply reciprocal links in generated output that includes links. The rendered navigation links are a function of the presentation style that is determined by the processor.

@processing-role
Specifies whether the topic or map referenced is processed normally or treated as a resource that is only included in order to resolve key or content references.
processing-role="normal"
The topic is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.
processing-role="resource-only"
The topic is used only as a resource for processing. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

If the @processing-role attribute is not specified locally, the value cascades from the closest element in the containment hierarchy.

@search
Specifies whether the topic is included in search indexes.
@toc
Specifies whether topics are excluded from navigation output, such as a Web site map or an online table of contents. By default, <topicref> hierarchies are included in navigation output; relationship tables are excluded.
Attributes in the list above are used exclusively or primarily in maps, but many important map attributes are shared with elements in topics. DITA maps also use many of the following attributes that are used with linking elements in DITA topics, such as <link> and <xref>:
  • @format
  • @href
  • @keyref
  • @scope
  • @type
The following metadata and reuse attributes are used by both DITA maps and DITA topics:
  • @rev, @status, @importance
  • @dir, @xml:lang, @translate
  • @id, @conref, @conrefend, @conkeyref, @conaction
  • @props and any attribute specialized from @props, including those integrated by default in the OASIS-provided document-type shells: @audience, @deliveryTarget, @platform, @product, @otherprops
  • @search

When new attributes are specialized from @props or @base as a domain, they can be incorporated into both map and topic structural types.