MEP-0020

Topic links elements allow you to specify a list of groups, where each group is matched against the group attribute of a link element. This allows you to override the default order. It also allows you to segment the topic links for a guide page into multiple link lists, with potentially block content between lists, or different styling for different lists.

People currently use this in three ways:

The first use case works very well, thanks to the inclusion of the implicit groups. Without the implicit groups, this would be somewhat more tedious, though no moreso than the second use case.

The second use case works reasonably well. Groups can have logical, semantic names. Having link targets include these semantic groups feels natural, but sometimes it duplicates other metadata. For example, you might group all tutorials together using a tutorial group, then specify on the link target that it belongs to the group. In this case, tutorials might already use style="tutorial", which leads to a duplication of information.

The third case works very poorly. Each link target ends up declaring a unique group, which is usually just the same as the id attribute.

This page proposes adding special groups that match existing metadata on the link target. A special group would always contain a colon character and be of the form key:value. The key indicates what metadata is being matched against, while the value indicates the value to match.

This page proposes two special group types: id and style. More special group types could be added in the future.

An id group matches against the fully qualified ID of the target. For a page, that is simply the value of the id attribute. For anything inside a page, it is the containing page id and the target id, combined with the # character. This is the same form you would use to link to the target.

A style group matches a style hint on the target node. For this group type, the style hint is always taken from the style attribute of the page, section, or formal block element being linked to. The style attribute is a space-separated list of style hints. The group matches if it is the same as any style hint in the list of style hints on the link target.

Explicitly order links based on their id attributes:

<links type="topic" groups="id:firstpage id:secondpage id:thirdpage"/>

Group tutorials first based on style hints:

<links type="topic" groups="style:tutorial">
  <title>Tutorials</title>
</links>
<links type="topic" groups="#first #default #last">
  <title>All Other Topics</title>
</links>

No alternatives were considered, but there are two further group types that were considered but deferred for this MEP:

This proposal could potentially create backwards compatibility issues if anybody is using explicit groups that look like the new implicit groups. For example, if a writer defines the group style:tutorial with the intention of using an explicit group="style:tutorial" attribute on informational link elements, with this proposal implemented, that group would start matching elements with the tutorial style hint. It's unlikely this affects any real-world documents.

The fallback behavior for any link targets that should be matched with special groups is that they would be placed in #default by any tool that doesn't support this proposal. There is no loss information, but the presentation would be imperfect.

The link grouping mechanism is unique to Mallard's method of collecting and organizing links, so no comparisons can be made.