Key Sequences

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the keyseq element to mark up a key combination or sequence. Use the key element to mark up each individual key press. You can use text without markup to indicate a class of keys, such as arrow keys, or to indicate a mouse action.

Notes

The keyseq element can contain a mixture of text, key elements, and other keyseq elements.
The keyseq element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The type element indicates whether the keys should be pressed together ("combo") or in sequence ("sequence"). The default is "combo".
The keyseq element can link to other pages or documents. See Ubiquitous Linking for more information.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The keyseq element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use keyseq to mark up a keyboard shortcut:

Press <keyseq><key>Ctrl</key><key>Q</key></keyseq> to quit.

Press Ctrl+Q to quit.

Use keyseq with text for classes of keys:

Press <keyseq><key>Shift</key>arrow keys</keyseq> to make a continuous
selection as you move the keyboard focus.

Press Shift+arrow keys to make a continuous selection as you move the keyboard focus.

Use keyseq with text for mouse actions:

<keyseq><key>Shift</key>click</keyseq> to make a continuous selection.

Shift+click to make a continuous selection.

Use nested keyseq elements for complex key commands:

Press <keyseq type="sequence"><keyseq><key>C</key><key>x</key></keyseq>
<keyseq><key>C</key><key>s</key></keyseq></keyseq> to save a file in
<app>Emacs</app>.

Press C+x C+s to save a file in Emacs.

Since classes of keys and mouse actions are written without surrounding markup, you can't have two consecutive key classes or mouse actions. You can overcome this limitation by using nested singleton keyseq elements:

There are various ways to modify drag behavior by using
<keyseq><keyseq>modifier</keyseq>drag</keyseq>.

There are various ways to modify drag behavior by using modifier+drag.

Processing Expectations

Each of the child key elements and text nodes, except whitespace-only text nodes, is displayed as described below, adding a separator between them. The exact separator may vary according to language and style preferences, and according to the type attribute. For sequences, a space is typically used. For combinations, the plus sign (+) is most frequently used on modern systems, although the hyphen (-) is still common in some areas. A style hint may be used to choose between different separators.

Child key and keyseq elements are shown as normal. Text nodes have their whitespace normalized to strip leading and trailing spaces. Text nodes may be rendered using a font variation.

Comparison to Other Formats

The keyseq element is similar to the keycombo element in DocBook. Like keycombo, keyseq elements can be nested to indicate sequences of key combinations. Since Mallard does not provide an element analogous to the DocBook element mousebutton, mouse actions in key sequences should be written as text content without markup.

There is no specific element for marking up key sequences in DITA.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the keyseq element. The namespace declarations for this definition are on the page Pages.

mal_inline_keyseq = element keyseq {
  mal_inline_keyseq_attr,
  mal_inline_keyseq_inline
}
mal_inline_keyseq_attr = (
  mal_attr_link *,
  attribute type { "combo" | "sequence" } ?,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_keyseq_inline = (
  mal_inline_key * &
  mal_inline_keyseq * &
  text
)