Draft

1.2 (2019-02-09)

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.

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
© 2008-2009 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard