Key Strokes

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

Use the key element to mark up a key on the keyboard. You can use this for letter keys, such as Q, or for keys with names, such as Ctrl. Generally, the contents of the key element should be what is printed on the physical key, although it may be a textual description for keys with symbols printed on them.

Do not use key to mark up a class of keys, such as arrow keys. These do not require markup in running prose. Inside a keyseq element, you are allowed to use text without a key element exactly for this purpose.

Do not use key to mark up a symbolic key code or a numeric key value; if necessary, use sys for these instead.

Notes

The key element can contain a mixture of text and any general inline elements.
The key element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The key element can also occur inside the keyseq element, where it has special meaning.
The key 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 key element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use key to mark up a letter key:

Press <key>M</key> to mark the selected message as read.

Press M to mark the selected message as read.

Use key to mark up a function key:

Press <key>F9</key> to check for new messages.

Press F9 to check for new messages.

Use key to refer to a specific key by a textual description:

Press the <key>Down</key> key to select the next item.

Press the Down key to select the next item.

Processing Expectations

No particular special rendering is required for key elements. Keys may be rendered with lightened text or other subtle styling effects to distinguish them from the surrounding text.

Comparison to Other Formats

The key element is similar to the keycap element in DocBook. Mallard does not provide elements analogous to the DocBook elements keysym and keycode. In most cases, these should be marked simply with the sys element.

There is no specific element for marking up keys 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 key element. The namespace declarations for this definition are on the page Pages.

mal_inline_key = element key {
  mal_inline_key_attr,
  mal_inline_key_inline
}
mal_inline_key_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_key_inline = mal_inline