MEP-0015

Mallard provides the guiseq and keyseq elements to mark up menu paths and key combinations, respectively. These two elements each takes a sequence of child elements, usually gui and key. This is the same model used by other semantic formats. Though the Mallard elements are less verbose, even a simple sequence can still be cumbersome. The sequence for Ctrl+S is 44 characters long.

<keyseq><key>Ctrl</key><key>S</key></keyseq>

These are among the most commonly used markup in user documentation, and we have not made them sufficiently easy to use.

This page proposes allowing users to write entire sequences without child elements, separating parts with the + character.

<guiseq>File+Save</guiseq>
<keyseq>Ctrl+S</keyseq>

When processing tools encounter a guiseq or keyseq element that contains text but no child elements, they split that text on the + character, trim leading and trailing whitespace from each component, and treat those components as if they were wrapped in gui or key elements, respectively.

This mechanism does not provide a way to add attributes to the implicit gui and key elements, such as style hints or linking attributes. It also does not provide a way to have components that are not wrapped, such as with classes of keys like <keyseq><key>Ctrl</key>arrow keys</keyseq>. In those cases, users will have to use the full syntax with child elements.

The + character was chosen as a separator because it is the most natural separator for keyseq. Even if a processing tool does not support this proposal, it would still give an acceptable rendering of keyseq elements using the shorthand syntax. The + character is not ideal for guiseq elements. We will have to weigh the importance of this against the convenience of using the same syntax.

When rendered according to this proposal, the shorthand syntax will have no effect on assistive technologies. However, the fallback behavior may have less semantic information and poorer results with tools like screen readers.

Translators will be presented with the same shorthand syntax used by authors in the original language. This should not present any problems, especially since it is unlikely to change message granularity in message-based formats like PO or XLIFF.

It is possible that some languages would prefer a character other than + as a separator when presenting keyseq elements to the reader. This would only affect the fallback rendering. No known tools support a different separator character for different languages.

There is a slight potential incompatibility in this proposal. Having a guiseq or keyseq with just text is already valid, if uncommon. If such an element contains a + character, it would be treated differently by a tool supporting this proposal. In practice, the only recommended use of bare text in either element is to do a key sequence with two consecutive descriptions of keys, such as <keyseq><keyseq>modifier</keyseq>arrow keys</keyseq>. Although it's conceivable somebody has used the + character in such a case, we haven't seen it.

The fallback behavior for tools that don't support this proposal is that the shorthand syntax would be rendered as written. For keyseq elements, this will often be acceptable, though it may have less styling and semantics. For guiseq elements, using the + character makes the fallback behavior less acceptable.

One difficulty with compatibility and fallback for this propsoal is that it doesn't make any changes that are testable with the schema. If a user uses the shorthand syntax but continues to validate against an older schema, validation will succeed.