Roles on Sort Titles

This page proposes allowing a role attribute on informational sort titles. The appropriate sort title would be selected similarly to how link titles are selected with roles.

Authors: Shaun McCance
Created: 2017-08-31
Status: proposed (2018-03-14)
Target: 1.2
show history
hide history
2017-08-31 1.1 proposed
2018-03-14 1.2 proposed

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.


Mallard allows multiple informational titles for various purposes. One type of informational title is the title to be used when sorting links to pages or sections. For example, you can use sort titles to sort without leading articles such as “an” and “the”.

Another type of informational title is the title used for link text when linking to a page or section. You can actually provide multiple link titles, each with a different role attribute. The correct title is selected based on a role attribute on an inline link element or an implicit role specified by a type of automatic link. MEP-0003 also allows you to explicitly select a role with a links element.

Unfortunately, no matter which link title is used for the link text, the same sort title is always used.


This page proposes making the role attribute relevant for sort titles. In Mallard 1.0, the role attribute is already valid, because the schemas don’t distinguish between link types. However, the role attribute is only used for link types that are specified.

Whenever links are collected and need to be sorted, they would be sorted according to a selected sort title:

  1. If the links are generated for an explicit links, and that links element has a role attribute, use the sort title with that role, if it exists.

  2. If the links are of a type that has an implicit role (such as topic for topic links), use the sort title with that implicit role, if it exists.

  3. Use the sort title without a role attribute, if it exists.

If the target node does not have a sort title that matches one of these rules, then it is sorted according to its link title, which follows a similar selection procedure.


This section is not yet written. Discuss this proposal on mallard-list.


This section is not yet written. Discuss this proposal on mallard-list.

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.

If a page with multiple sort titles is processing by a tool that does not implement this proposal, that tool will select one of those sort titles, and there is no guarantee as to which one. In practice, all known implementations select the first sort title when multiple sort titles are available. For this reason, when writers use multiple sort titles, they should place the sort title without a role before other sort titles in the info element.

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.

© 2017 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