<titlealt>

An alternative title is used to convey information about a document in contexts other than straightforward display.

Usage Information

Alternative titles can be used in both maps and topics:

  • When used in the <topicmeta> of a root <map> element, the alternative title applies to the map itself.
  • When used inside a <topicref> element, the alternative title applies to the resource that is referenced by the <topicref> element.
  • When the referenced resource is a DITA topic, the alternative titles from the <topicref> element are merged with those authored directly in the topic, with the alternative titles from the <topicref> element taking higher priority.

The roles of an alternative title are specified by the @title-role attribute. Multiple roles can be specified, separated by white space. An alternative title specifies at least one role. Other tokens for the @title-role attribute can be defined for specific purposes.

Some roles might not be meaningful in certain contexts. For example, a navigational alternate title is not meaningful in the context of a <topicgroup> element, since the element is not part of the navigation structure of a publication. Such alternate titles are ignored by processors.

The base DITA vocabulary contains an alternative titles domain that contains convenience elements that are equivalent to <titlealt> elements with the @title-role attribute set to the tokens outlined in Processing expectations.

Processing expectations

The processing of an alternative title depends on its roles. Processors SHOULD support the following tokens for the @title-role attribute:
linking
Specifies that the content of the <titlealt> element contains the title for use in references to the resources generated from DITA map structures, such as hierarchical parent/child/sibling links and links generated from relationship tables. In addition, this is the fallback alternative title for navigation and search roles. Custom title roles meant for use in link generation should also use this as a fallback.
navigation
Specifies that the content of the <titlealt> element contains the title for use in tables of content and other navigation aids. In some cases, when processing a <topicref> that has no @href, this is also used as the title of the generated topic, if applicable. If not present, this role is fulfilled by the linking role.
search
Specifies that the content of the <titlealt> element contains a title for use in search results for systems that support content search. If not present, this role is fulfilled by the linking role.
subtitle
Specifies that the content of the <titlealt> element contains a subtitle for the document.
hint
Specifies that the content of the <titlealt> element contains a hint about the referenced resource. This is intended for the benefit of map authors; it does not have an effect on processing or output.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.

Alternative titles with the @title-role attribute set to tokens that are not recognized by the processor SHOULD be ignored and not appear in output.

Content model

(Text | <data> | <foreign> | <keyword> | <term> | <text> | <ph> | <draft-comment> | <required-cleanup>)*

Contained by

<prolog>

Zero or more of the following

Contained by

Inheritance

- topic/titlealt

The <titlealt> element is a base element type. It is defined in the topic module.

Attributes

The following attributes are available on this element: universal attributes and @title-role.

The following attributes are available on this element: universal attributes and the attributes defined below.

@title-role (REQUIRED)
Specifies the role that the alternative title serves. Multiple roles are separated by white space. The following roles are defined in the specification: linking, navigation, search, subtitle, and hint.

Processors can define custom values for the @title-role attribute.

Examples

This section is non-normative.

This section contains examples of how the <titlealt> element can be used.

Example 1. Subtitles

The following code sample shows how a map can specify a subtitle for a publication:

<map>
  <title>Publication title</title>
  <topicmeta>
    <titlealt title-role="subtitle">Publication subtitle</titlealt>
  </topicmeta>
</map>

An identical result could be achieved by using the <subtitle> element that is provided by the alternative titles domain.

Example 2. Multiple alternative titles and their roles

The following code sample shows how a topic reference can specify several alternative titles:

<topicref keys="about" href="about.dita">
  <topicmeta>
    <titlealt title-role="linking navigation">About the product</titlealt>
    <titlealt title-role="search">About</titlealt>
    <titlealt title-role="hint">About the Acme TextMax 5000</titlealt>
  </topicmeta>
</topicref>
  1. "About the product" will be used for both linking and navigation titles, for example, when generating related links and rendering a table of contents.
  2. "About" will be used for a search title, for example, when providing a title in systems that support dynamic content searches.
  3. "About the Acme TextMax 500" provides a hint to map authors as to the contents of the referenced DITA resource. This title is not used in output.

If the alternative-titles domain is available, the following markup would be equivalent:

<topicref keys="about" href="about.dita">
  <topicmeta>
    <linktitle>About the product</navtitle>
    <searchtitle">About</searchtitle>
    <titlehint>About the Acme TextMax 5000</titlehint>
  </topicmeta>
</topicref>