MEP-0018
Type-and-Role Data
This page provides a set of lookup rules to determine the title, description, and thumbnail image for a page or section, using types and roles. This proposal extends the current system for finding link text.
| Authors: | Shaun McCance |
|---|---|
| Created: | 2019-11-17 |
| Status: | proposed (2019-11-17) |
| Target: | 1.2 |
| Blocks: |
|
| History: |
This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.
Background
Mallard allows different titles to be selected for different purposes based on the type and role attributes on the informational title element. The type attribute allows you to specify titles for link text, a title for sorting, and a title for text-only uses like window titles. The role attribute allows you to specify multiple link titles. These can be selected explicitly using the role attributes on the inline link element and the block links element. Furthermore, the links element can specify an implicit role.
There are three enhancement proposals that would benefit from this system being extended:
- MEP-0004: The thumb Element
MEP-0004 calls for a thumb element to be added to specify a thumbnail image for a page. Since thumbnails may be used alongside link text, it makes sense to use a role attribute to select alternatives along with other link data.
- MEP-0008: Multiple desc Elements
The desc element is often used alongside the link title to provide more context for a link. Currently, Mallard only allows a single desc, regardless of the link text. MEP-0008 calls for the desc element to use a role attribute to match link titles.
- MEP-0011: Roles on Sort Titles
Currently, Mallard only allows a single sort title, regardless of which title is being used for link text. MEP-0011 calls for sort titles to use roles as well, so that sort titles can match link titles.
Proposal
This page proposes a single, consistent set of lookup rules to use to find a title, desc, or thumb element given a type and a list of roles. These lookup rules could also be used by future core elements or extension elements.
These lookup rules extend those currently used for link titles, but add an additional step. The motivation for this extra step was to not require a type attribute for the desc element, since supplementary link text is the only current practical use for the desc element.
These lookup rules are written using the following variables:
$element: The actual element being looked up. Currently, this is title, desc, or thumb. Other elements could use these lookup rules in the future.
$type: The value of the type attribute. This is selected automatically based on how the data is used. The type link is used for link text, the type sort is used for sorting purposes, and the type text is used in text-only locations like window titles and search databases. Extensions and tool-specific features may use other types, such as those used by Mallard UI expanders.
$roles: An ordered list of roles to match against the role attribute. Though there can be any number of roles, there are currently two used in practice. The primary role is the one specified explicitly by the role attribute of the inline link element or the block links element. The secondary role is the one implicitly used based on the type of the links element.
These lookup rules apply when a processing tool requires data for a target page, section, or block element. Given an element $element, a particular type $type, and list of roles $roles, it would follow the following steps:
If $type and $roles are non-empty, then for each $role in $roles, if the target has an informational element $element with the type attribute set to $type and the role attribute set to $role, then that element is used and this procedure stops.
Otherwise, if $roles is non-empty, then for each $role in $roles, if the target has an informational element $element without a type attribute and with the role attribute set to $role, then that element is used and this procedure stops. This step would be new in the current lookup rules for link titles.
Otherwise, if $type is non-empty, then if the target has an informational element $element with the type attribute set to $type and without a role attribute, then that element is used and this procedure stops.
Otherwise, if the target has an element $element without a type attribute and without a role attribute, then that element is used and this procedure stops.
Finally, if $element is title, the primary display title is used.
Examples
This section is not yet written. Discuss this proposal on mallard-list.
Alternatives
We considered a number of alternatives when developing MEP-0004: The thumb Element, MEP-0008: Multiple desc Elements, and MEP-0011: Roles on Sort Titles:
Defining a set of custom rules just for sort titles that closely mimic the link title rules, but still use a link title fallback.
Making link titles continue to require the type attribute in all cases, but making desc not use or require the type attribute.
Making desc require the type attribute in all cases, just like Mallard 1.0 link titles.
In the end, we opted for a single set of consistent rules for all elements and types. This is easier to maintain an implementation for, and easier for users to remember.
We originally proposed making the type take precedence over the roles in the lookup rules, swapping rules 2 and 3 above. We decided against this after looking at how it would affect default sort titles. With the rules as proposed here, you can provide the same text as both link title and sort title for a role by just omitting the type attribute.
Compatibility and Fallback
This proposal does make a backwards-incompatible change to the way sort titles are looked up. Prior to this proposal, sort titles would default to link titles if no explicit sort title was found. This proposal does provide an easier way to provide both sort and link title for a role, but we should further investigate the impact of this incompatibility.
This proposal also makes a potentially incompatible change by introducing an extra step in the link title lookup rules. However, since there was previously no practical use for a title with a role but no type, there is probably no real-world impact.
The fallback behavior for new pages read by old tools varies. There are some fallback considerations for additional sort title and additional descs. Those are covered in MEP-0008: Multiple desc Elements and MEP-0011: Roles on Sort Titles. This proposal introduces the ability to specify both the link title and sort title for a given role by omitting the type attribute. This convenient shorthand will be completely ignored by older tools. If your documents may be processed by older tools, you should continue always using explicit type attributes.
Comparison to Other Formats
No other format has a comparable mechanism for selecting the titles, page descriptions, or other data.
