MEP-0015

Shorthand syntax for guiseq and keyseq

This page proposes a shorthand syntax for guiseq and keyseq elements, allowing you to write simple sequences without child gui and key elements.

Authors: Shaun McCance
Created: 2019-03-16
Status: incomplete (2019-03-16)
Target: 1.2
Issue: https://github.com/projectmallard/projectmallard.org/issues/64
History:
show history
hide history
history
2019-03-16 1.2 incomplete

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

Background

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.

Proposal

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.

Examples

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

Accessibility

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.

Internationalization

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.

Compatibility and Fallback

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 his 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.

Comparison to Other Formats

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

© 2019 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
Mallard