Informational Titles

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the title element inside an info element to list alternative titles for pages and sections. These titles can be used as alternative link text, for sorting, or for other application-specific purposes.

Notes

The title element can contain a mixture of text and any general inline elements.
The title element can occur in any info element.
The type attribute specifies what purpose this informational title is serving. The following values are currently recognized:

"link"

specifies alternate link text; see Link Titles

"sort"

specifies a sort key; see Sort Titles

"text"

specifies a text title; see Text Titles
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The role attribute can be used for link titles to specify multiple alternate link texts.
The title element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Provide a title to be used as link text for links to a page:

<page xmlns="http://projectmallard.org/1.0/" id="beanstalks">
  <info>
    <title type="link">Beanstalks</title>
  </info>
  <title>Everything You Ever Wanted to Know About Beanstalks</title>
</page>

Provide a title to be used when sorting links to pages:

<page xmlns="http://projectmallard.org/1.0/" id="example">
  <info>
    <title type="sort">Beanstalk Example</title>
  </info>
  <title>A Beanstalk Example</title>
</page>

Primary Titles

The primary title of a page or section is the one specified in the block context and used for display purposes. While this title is not an informational title as specified here, it is used as fallback for all informational titles.

Link Titles

Pages and sections can have multiple link titles. These are used as alternate content for automatic link text. When automatic text must be generated for a link element, it is taken first from the link titles, falling back to the primary title if no suitable link title is found.

You can use the role attribute to specify multiple link titles. These can be selected using the role attribute of the link element. This can be used for a variety of purposes. One common purpose is to specify link text for different parts of speech in languages which have case declensions. Without this feature, it can be difficult to provide grammatically correct automatic link text in some languages.

Standard link roles may also be used to specify link text for automatic links. This specification recommends the following standard link roles:

"guide": Used for link text for guide links.
"seealso": Used for link text for see-also links.
"series": Used for link text for series links.
"topic": Used for link text for topic links.
"trail": Used when constructing a link trail, or bread crumbs, of guide links leading to a node.

Link roles may also be defined by implementations, authors, and translators. To avoid clashes in names, the following recommendations should be followed:

Roles defined by official specifications on projectmallard.org should never contain a hyphen.
Roles defined by implementations for implementation-specific features should be prefixed by a hyphen, an identifier for the implementation, and another hyphen. For example, if Yelp allowed a link role for links from search results, it could use the role -yelp-search.
Roles defined by authors, translators, or other content creators should contain but not start with a hyphen. For example, if you want to use a link role for inline links in the objective case in a German-language document, you might use the role de-objectiv.

Sort Titles

Sort titles allow you to specify alternate text to be used when sorting the page or section. Certain automatic link sections will sort the nodes they link to. When this happens, providing a sort title allows you to control how the node is collated. This is useful for excluding leading articles such as “an” and “the”.

Text Titles

Text titles are used wherever a plain text string without formatting is required. This is useful for window titles or labels in user interfaces where formatting and inline images are difficult or impossible. This is particularly useful when a title contains an image with fallback text, but you do not want the fallback text to appear in places such as window titles.

This specification does not specify exactly where text titles will be used. Uses for text titles may vary by implementation. Implementations may define roles to allow authors to provide alternate text titles for different purposes.

Processing Expectations

Informational titles are not displayed directly, although they will affect the output of any material which links to the given page or section.

The content model of the info element allows for any mixture of informational titles. As such, it is entirely possible for multiple titles to exist for some specified combination of the type and role attributes. When such an ambiguity arises, processing tools should select the first informational title that matches the desired criteria.

Comparison to Other Formats

DocBook has no general mechanism for specifying different title text for different purposes. Although a document is still valid with multiple title elements in an info element, the DocBook specification forbids having different values when titles appear in different contexts. DocBook does provide the titleabbrev element, which may be used by some implementations for link text.

DITA provides the titlealts, navtitle, and searchtitle elements, which provide a fixed mechanism to specify alternate titles for a limited number of uses. DITA does not have a general mechanism like Mallard informational titles.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the informational title element. The namespace declarations for this definition are on the page Pages.

mal_info_title = element title {
  mal_info_title_attr,
  mal_info_title_inline
}
mal_info_title_attr = (
  attribute type { xsd:NMTOKEN },
  attribute style { xsd:NMTOKENS } ?,
  attribute role { xsd:NMTOKEN } ?,
  mal_attr_external *
)
mal_info_title_inline = mal_inline