MEP-0003
The role Attribute on the links Element
This page outlines a mechanism for explicitly specifying the role to use when selecting alternate link titles for automatic links using the links element.
| Authors: | Shaun McCance |
|---|---|
| Created: | 2013-10-24 |
| Status: | final (2019-01-31) |
| Target: | 1.1 |
| History: |
Background
Mallard allows you to have multiple titles in an info element. These are used for different purposes, specified by the type attribute. One of those types is link titles. Link titles can also take a role attribute, which gets used in two ways:
Inline link elements can specify the title to use for link text with the role attribute on the link element.
Automatic links automatically use a role. For example, topic links will use (as a first pick) a link title with role="topic".
Sometimes, however, you want to use different titles in one place where you use automatic links than in another. For example, if a topic is in two guides, and one of the guides uses thumbnails to display its topic links, that guide might want to use shorter titles than a guide that uses a standard list.
Proposal
This page proposes allowing an optional role attribute on the links element. In Mallard 1.0, automatic links created from a links element (or implicitly) use a role by default to look up a link title for link text. For example, topic links will use link titles with the role topic by default. The general process for most types of links is:
Use the link title with the correct role attribute for this type of links element, if available.
Use the link title without a role attribute, if available.
Use the primary title.
This page proposes keeping the default role for each links type and the general procedure above, but adding a step at the beginning, such that the procedure becomes:
If the links element has a role attribute, use the link title with a matching role attribute, if available.
Use the link title with the correct role attribute for this type of links element, if available.
Use the link title without a role attribute, if available.
Use the primary title.
Compatibility and Fallback
This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.
The fallback behavior for a processing tool that does not implement this proposal is that the lookup according to the role attribute on the links element will not be performed. Instead, the remaining lookups will be performed as specified by Mallard 1.0.
Comparison to Other Formats
No other format has a comparable mechanism for selecting the title to use for link text. Also, the links element is particular to the unique automatic linking mechanism in Mallard. No comparison can be made to other formats for this proposal.
