Map components

Map components include the core components of LwDITA maps, such as key definition, key text, and topic reference.

A key definition provides a simple way to define a key without making the definition itself a part of rendered content.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<keydef>

<keydef keys="product-name">
  <topicmeta>
    <keytext>Remote Network Lighting</keytext>
  </topicmeta>
</keydef>
HDITA

<div data-class="keydef">

<div data-class="keydef">
  <span data-class="keytext" data-keys="product-name">Remote Lighting Network</span>
</div>
MDITA

There is no specific support in the MDITA core profile. If needed, use an HDITA snippet.

Usage information

The key definition component is a convenience component. It is equivalent to a topic reference component that defines a key while also setting @processing-role to resource-only. Attributes defaulted on the key definition component ensure that key definitions do not appear in the TOC, do not add extra links, and are not rendered as topics.

Attributes

The available attributes vary based on the authoring format:

XDITA and HDITA
The following attributes are available on this element: localization attributes, link relationship attributes, universal attributes, @keys, @props, and @processing-role.
MDITA
There is no attribute support for the MDITA core profile. For the MDITA extended profile, attributes can be specified by using the HDITA representation.
(XDITA and HDITA) For the key definition component, the following considerations apply:
  • The @keys attribute is required.
  • The @href attribute might be omitted when the key definition is used for variable text.
  • The @processing-role attribute has a default value of resource-only.

Examples

This section is non-normative.

The section contains examples of how the key definition component can be used. Key definitions can be used to define keys for topics, as well as variable text.

Example 1. XDITA example

The following code sample shows how the <keydef> element can be used to define keys for resources:

<map>
  <!-- Key definitions -->
  <keydef keys="winter-garden" href="garden/winter-garden.dita"/>
  <keydef keys="crop-types" href="crop-types.html" format="html" scope="local"/>
  <keydef keys="selecting-plants" href="garden/tasks/selecting-plants.dita"/>
  <!-- ... -->
</map>

For an example of a key definition used to define variable text, see Figure 4.

Example 2. HDITA example

The following code sample shows how the <keydef> element can be used to define keys for resources:

<nav>
  <h1>Planting a winter garden</h1>
<!-- Key definitions -->
  <div data-class="keydef" 
       data-keys="winter-garden" 
       href="garden/winter-garden.html"/>
  <div data-class="keydef" 
       data-keys="crop-types" 
       href="garden/crop-types.html"/>
  <div data-class="keydef" 
       data-keys="selecting-plants" 
       href="garden/selecting-plants.html"/>
  <!-- ... -->
  
</nav>

For an example of a key definition used to define variable text, see Figure 5.

Example 3. MDITA example

The following code sample shows how the <keydef> element can be used to define keys for resources. Note that in an MDITA map, the HDITA representation for key definitions must be used.

# Planting a winter garden
  <!-- Key definitions -->
  <div data-class="keydef" 
       data-keys="winter-garden" 
       href="garden/winter-garden.md"/>
  <div data-class="keydef" 
       data-keys="crop-types" 
       href="garden/crop-types.md"/>
  <div data-class="keydef" 
       data-keys="selecting-plants" 
       href="garden/selecting-plants.md"/>
  <!-- ... -->

For an example of a key definition used to define variable text, see Figure 6.

Key text is variable or link text that is used when resolving key references. It also specifies alternate text for images that are referenced by keys.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<keytext>

<keydef keys="product-name">
  <topicmeta>
    <keytext>Remote Network Lighting</keytext>
  </topicmeta>
</keydef>
HDITA

<span data-class="keytext">

div data-class="keydef">
  <span data-class="keytext" data-keys="product-name">Remote Lighting Network</span>
</div>
MDITA

There is no specific support in the MDITA core profile. If needed, use an HDITA snippet.

Processing expectations

See "Processing key reference to generate text or link text" in the DITA 2.0 specification.

Attributes

The available attributes vary based on the authoring format:

XDITA and HDITA
The following attributes are available on this element: localization attributes and universal attributes.
MDITA
There is no attribute support for the MDITA core profile. For the MDITA extended profile, attributes can be specified by using the HDITA representation.

Examples

This section is non-normative.

This section contains examples of how the key text component can be used.

Example 4. XDITA key text

The following code sample shows how the <keytext> element can be used to create variable text for a product name, as well as alternate text for an image referenced by @keyref:

<!-- Key definitions for images -->
  <keydef keys="icon-save" href="icons/save.gif" format="gif" scope="local">
    <keytext>Save icon</keytext>
  </keydef>
  <!-- Variable text definition -->
  <keydef keys="product-greenhouse">
    <topicmeta>
      <keytext>Acme Greenhouse</keytext>
    </topicmeta>
  </keydef>
Example 5. HDITA key text

The following code sample shows how the <keytext> element can be used to create variable text for a product name, as well as alternate text for an image referenced by @keyref:

<!-- Key definitions for images -->
  <div data-class="keydef" 
       data-keys="icon-save" 
       href="icons/save.gif" format="gif" scope="local">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
  <!-- Variable text definition -->
  <div data-class="keydef" data-keys="product-greenhouse">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
Example 6. MDITA key text

The following code sample shows how the <keytext> element can be used to create variable text for a product name, as well as alternate text for an image referenced by @keyref:

<!-- Key definitions for images -->
  <div data-class="keydef" 
       data-keys="icon-save" 
       href="icons/save.gif" format="gif" scope="local">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
  <!-- Variable text definition -->
  <div data-class="keydef" data-keys="product-greenhouse">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>

A DITA map is the mechanism for aggregating topic references and defining a context for those references. It contains references to topics, maps, and other resources.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<map>

<map id="remote-main">
  <topicmeta>
    <navtitle>Remote Lighting Network</navtitle>
  </topicmeta>
  <topicref href="introduction.dita"/>
  <topicref href="alternatives.dita">
    <topicref href="low-power.dita"/>
    <topicref href="high-power.dita"/>
  </topicref>
</map>
HDITA

<nav>

<nav>
  <h1>Remote Lighting Network</h1>
  <ul>
    <li><p><a href="introduction.html">Introduction</a><p></li>
    <li><p><a href="alternatives.html">Alternative lighting setups</a></p>
      <ul>
        <li><p><a href="low-power.html">Low power installation</a></p></li>
        <li><p><a href="high-power.html">High power installation</a></p></li>
      </ul>
    </li>
  </ul>
</nav>
MDITA

A Markdown file with a title and an unordered of titles for topics and their associated file names

# Remote Lighting Network
 - [Introduction](introduction.md)
 - [Alternative lighting setups](alternatives.md)
   - [Low power installation](low-power.md)
   - [High power installation](high-power.md)

Usage information

A map describes the relationships among a set of DITA topics. Nested topics create a hierarchical relationship. The topic that does the nesting is the parent, and the topics that are nested are the children.

The title component can be used to provide a title for the map. In some scenarios the title is purely informational and is present only as an aid to the author. In other scenarios, the title might be useful or even required. In a map referenced by another map, the title might be discarded as topics from the submap are aggregated into a larger publication.

Rendering expectations

When rendering a map, processors might make use of the relationships defined in the map to create a table of contents (TOC), aggregate topics into a PDF document, or create links between topics in the output.

Attributes

The available attributes vary based on the authoring format:

XDITA
The following attributes are available on this element: architectural attributes, localization attributes, universal attributes, and @id.

For this element, the @id attribute is required.

HDITA
The following attributes are available on this element: localization attributes, universal attributes, and @id.
MDITA
There is no attribute support for the MDITA core profile. For the MDITA extended profile, attributes can be specified by using the HDITA representation.

Examples

This section is non-normative.

The section contains examples of how the map component can be used.

Example 7. XDITA example

The following code sample shows a simple XDITA map. It contains key definitions, including one for variable text, as well as topic references that create a hierarchical table of contents (TOC):

<map>
  <topicmeta>
    <navtitle>Planting a winter garden</navtitle>
  </topicmeta>
  <!-- Key definitions for topics -->
  <keydef keys="winter-garden" href="garden/winter-garden.dita"/>
  <keydef keys="crop-types" href="garden/crops/crop-types.dita"/>
  <keydef keys="selecting-plants" href="garden/tasks/selecting-plants.dita"/>
  <!-- Variable text definition -->
  <keydef keys="product-greenhouse">
    <topicmeta>
      <keytext>Acme Greenhouse</keytext>
    </topicmeta>
  </keydef>
  <!-- TOC hierarchy -->
  <topicref keyref="winter-garden">
    <topicref keyref="crop-types"/>
    <topicref keyref="selecting-plants"/>
    <topicref href="garden/tasks/planting-short-season-crops.dita"/>
    <topicref href="garden/tasks/planting-long-season-crops.dita"/>
    <topicref href="garden/tasks/extending-growing-season.dita"/>
    <!-- … -->
  </topicref>
</map>
Example 8. HDITA example

The following code sample shows a simple HDITA map. It contains key definitions, including one for variable text, as well as topic references that create a hierarchical table of contents (TOC):

<nav>
  <h1>Planting a winter garden</h1>
  <!-- Key definitions for topics -->
  <div data-class="keydef" data-keys="winter-garden" href="garden/winter-garden.html"/>
  <div data-class="keydef" data-keys="crop-types" href="garden/crop-types.html"/>
  <div data-class="keydef" data-keys="selecting-plants" href="garden/selecting-plants.html"/>
  <div data-class="keydef" data-keys="plant-short-season" href="garden/plant-short-season.html"/>
  <div data-class="keydef" data-keys="plant-long-season" href="garden/plant-long-season.html"/>
  <div data-class="keydef" data-keys="extending-season" href="garden/extending-season.html"/>
  <!-- Variable text definition -->
  <div data-class="keydef" data-keys="product-greenhouse">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
  <!-- TOC hierarchy -->
  <ul>
    <li><a data-keyref="winter-garden">Planting a winter garden</a>
      <ul>
        <li><a data-keyref="crop-types">Crops for a winter garden</a></li>
        <li><a data-keyref="selecting-plants">Selecting your winter crops</a></li>
        <li><a data-keyref="plant-short-season">Planting short-season crops</a></li>
        <li><a data-keyref="plant-long-season">Planting long-season crops</a></li>
        <li><a data-keyref="extending-season">Extending the growing season</a></li>
      </ul>
    </li>
  </ul>
</nav>
Example 9. MDITA example

The following code sample shows a simple MDITA map. It contains key definitions, including one for variable text, as well as topic references that create a hierarchical table of contents (TOC):

# Planting a winter garden
  <!-- Key definitions for topics -->
  <div data-class="keydef" data-keys="winter-garden" href="garden/winter-garden.md"/>
  <div data-class="keydef" data-keys="crop-types" href="garden/crop-types.md"/>
  <div data-class="keydef" data-keys="selecting-plants" href="garden/selecting-plants.md"/>
  <div data-class="keydef" data-keys="plant-short-season" href="garden/plant-short-season.md"/>
  <div data-class="keydef" data-keys="plant-long-season" href="garden/plant-long-season.md"/>
  <div data-class="keydef" data-keys="extending-season" href="garden/extending-season.md"/>
  <!-- Variable text definition -->
  <div data-class="keydef" data-keys="product-greenhouse">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
  <!-- TOC hierarchy -->
 - [Planting a winter garden](winter-garden)
   - [Crops for a winter garden](crop-types)
   - [Selecting your winter crops](selecting-plants)
   - [Planting short-season crops](plant-short-season)
   - [Planting long-season crops](plant-long-season)
   - [Extending the growing season](extending-season)

A navigation title is an alternative title for a resource. It is designed for situations where the topic title is unsuitable for use in a table of contents or navigation pane.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<navtitle>

<topicref href="alternatives.dita">
  <topicmeta>
    <navtitle>Alternative lighting setups</navtitle>
  </topicmeta>
</topicref>
HDITA There is no specific markup for navigation title.
MDITA There is no specific markup for navigation title.

Attributes

The available attributes vary based on the authoring format:

XDITA and HDITA
The following attributes are available on this element: localization attributes and universal attributes.
MDITA
There is no attribute support for the MDITA core profile. For the MDITA extended profile, attributes can be specified by using the HDITA representation.

Example

This section is non-normative.

The following code sample shows how the <navtitle> element can provide a title for the map and a navigation title for a topic:

<map>
  <topicmeta>
    <!-- 1. Applies a title for the map -->
    <navtitle>Developing a reuse strategy</navtitle>
  </topicmeta>
  <topicref keyref="developing-reuse-strategy">
    <topicref keyref="define-business-requirements"/>
    <topicref keyref="prototype-sample-source"/>
    <topicref keyref="select-reuse-methods"/>
    <topicref keyref="test-reuse-methods"/>
    <topicref keyref="correct-reuse-strategy">
      <topicmeta>
        <!-- 2. Applies a navigation title for the resource -->
        <navtitle>Refine reuse strategy</navtitle>
      </topicmeta>
    </topicref>
    <!-- … -->
  </topicref>
</map>

In the above code sample, the <navtitle> element appears twice:

  1. It supplies a title for the DITA map.
  2. It supplies a navigation title of "Refine reuse strategy" for the resource referenced by the key "correct-reuse-strategy."

Topic metadata is metadata that applies to a topic based on its context in a map.

Syntax

Authoring format Syntax and example
XDITA

<topicmeta>

<map>
  <topicmeta>
    <navtitle>Configuring the ACME Test Suite</navtitle>
    <data name="goal" value="configuring"/>
  </topicmeta>
  <!-- ... -->
</map
HDITA

There is no equivalent to <topicmeta>.
MDITA

There is no equivalent to <topicmeta>.

Usage information

The metadata specified in a topic metadata component is specific to a given context within a map. If a reference to a single resource appears more than once in a map or set of maps, unique metadata can be specified in each instance. For example, when the parent topic reference results in a link, components within the topic metadata component can be used to provide context-specific information about the link, such as link text or a navigation title.

Attributes

The following attributes are available on this element: localization attributes and universal attributes.

Example

This section is non-normative.

The following code sample shows how the <topicmeta> element can be used to both specify metadata for the entire map and for a specific topic

<map>
  <!-- 1. Applies a title and metadata to the entire map -->
  <topicmeta>
    <navtitle>Configuring the ACME Test Suite</navtitle>
    <data name="goal" value="configuring"/>
  </topicmeta>
  <topicref keyref="configuring-test-suite">
    <topicref keyref="setting-preferences"/>
    <topicref keyref="testing-parameters">
      <!-- 2. Applies metadata to the specific topic-->
      <topicmeta>
        <data name="parameters" value="test-suite-set"/>
      </topicmeta>
    </topicref>
    <topicref keyref="setting-options"/>
    <!-- … -->
  </topicref>
</map>

In the above code sample, a <topicmeta> element appears twice:

  1. Specifies a navigation title for the map and indicates that all topics in the map are about the user goal of "configuring".
  2. Specifies specific metadata for the topic defined by the key "test-suite-set".

A topic reference is the mechanism for referencing a topic (or another resource) from a DITA map. It can nest, which enables the expression of navigation and table-of-content hierarchies, as well as containment hierarchies and parent-child relationships.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<topicref>

<topicref href="alternatives.dita">
  <topicref href="low-power.dita"/>
  <topicref href="high-power.dita"/>
</topicref>
HDITA

<a href> inside of a list item

<li><a href="alternatives.html">Alternative lighting setups</a>
  <ul>
    <li><a href="low-power.html">Low power installation</a></li>
    <li><a href="high-power.html">High power installation</a></li>
  </ul>
</li>
MDITA

[link text](URI) inside of a list item

- [Alternative lighting setups](alternatives.md)
 - [Low power installation](low-power.md)
 - [High power installation](high-power.md)

Attributes

The available attributes vary based on the authoring format:

XDITA and HDITA
The following attributes are available on this element: ID attributes, link relationship attributes, localization attributes, universal attributes, @keys, @keyref, and @props.
MDITA
For the MDITA core profile, the equivalent of the XDITA @keyref attribute is supported. For the MDITA extended profile, attributes can be specified by using the HDITA representation.

Examples

This section is non-normative.

This section contains examples of how the topic reference component can be used.

Example 10. XDITA example

The following code sample shows a simple DITA map that represents the Acme Widget User Guide. Each of the <topicref> elements represents the top-level topic for a chapter, and indirect addressing is used to reference the DITA topics.

map>
  <topicmeta>
    <navtitle>Acme Widget User Guide</navtitle>
  </topicmeta>
  <keydef href="key-definitions.ditamap"/>
  <topicref keyref="installing">
    <!-- … -->
  </topicref>
  <topicref keyref="configuring">
    <!-- … -->
  </topicref>
  <topicref keyref="administering">
    <!-- … -->
  </topicref>
  <topicref keyref="developing">
    <!-- … -->
  </topicref>
  <topicref keyref="troubleshooting">
    <!-- … -->
  </topicref>
</map>
Example 11. HDITA example

The following code sample shows a simple DITA map that represents the Acme Widget User Guide. Each of the topic reference components represents the top-level topic for a chapter, and direct addressing is used to reference the HDITA topics.

<ul>
  <li><a href="installing.html">Installing Acme Widget</a>
      <! ... -->
  </li>
  <li><a href="configuring.html">Configuring Acme Widget</a>
      <! ... -->
  </li>
  <li><a href="administering.html">Administering Acme Widget</a>
      <! ... -->
  </li>
  <li><a href="developing.html">Developing Acme Widget applications</a>
      <! ... -->
  </li>
  <li><a href="troubleshooting.html">Troubleshooting Acme Widget</a>
      <! ... -->
  </li>
</ul>
Example 12. MDITA example

The following code sample shows a simple DITA map that represents the Acme Widget User Guide. Each of the topic reference components represents the top-level topic for a chapter, and direct addressing is used to reference the MDITA topics.

- [Installing Acme Widget](installing.md)
 <!-- ... -->
- [Configuring Acme Widget](configuring.md)
 <!-- ... -->
- [Administering Acme Widget] (configuring.md)
 <!-- ... -->
- [Developing Acme Widget apps (developing.md)
 <!-- ... -->
- [Troubleshooting Acme Widget (troubleshooting.md)