MEP: The role Attribute on the links Element

Shaun McCance <shaunm at gnome.org>
Thu Nov 21 08:48:50 EST 2013

Earlier this year, I proposed adding the role attribute to the links
element to allow users to explicitly specify the link title role to use
for those links:

http://projectmallard.org/pipermail/mallard-list/2013-July/000167.html

Attached is MEP. Here's the synopsis:

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:

1. Use the link title with the correct role attribute for this type of
   links element, if available.
2. Use the link title without a role attribute, if available.
3. 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:

1. If the links element has a role attribute, use the link title with
   a matching role attribute, if available.
2. Use the link title with the correct role attribute for this type
   of links element, if available.
3. Use the link title without a role attribute, if available.
4. Use the primary title.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: mep-links-role.page
Type: text/x-mallard-page+xml
Size: 4683 bytes
Desc: not available
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20131121/8f895978/attachment.bin>