<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="mal_inline_keyseq">

<info>
  <link type="guide" xref="mal_inline#elements"/>
  <link type="seealso" xref="mal_inline_key"/>

  <revision version="0.1" date="2008-12-17" status="review"/>

  <credit type="author">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
  </credit>
  <copyright>
    <year>2008-2009</year>
    <name>Shaun McCance</name>
  </copyright>

  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <desc>Mark up a key combination or sequence.</desc>
</info>

<title>Key Sequences</title>

<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_keyseq = element keyseq {
  attribute style { xsd:NMTOKENS } ?,
  attribute type { "combo" | "sequence" } ?,
  attribute * - (mal:* | local:*) { text } *,

  mixed {
    (<link xref="mal_inline_gui">mal_inline_key</link> | mal_inline_keyseq) *
  }
}
</code></synopsis>

<p>Use the <code>keyseq</code> element to mark up a key combination or sequence.
Use the <code xref="mal_inline_key">key</code> element to mark up each individual
key press.  You can use text without markup to indicate a class of keys, such as
<em>arrow keys</em>, or to indicate a mouse action.</p>


<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>keyseq</code> element can contain a mixture of text,
    <code xref="mal_inline_key">key</code> elements, and other
    <code>keyseq</code> elements.</p></item>

    <item><p>The <code>keyseq</code> element can occur in any
    general inline context, including inside most
    <link xref="mal_inline">inline elements</link>, some
    <link xref="mal_block#basic">basic block elements</link>, and certain
    <link xref="mal_info">informational elements</link>.</p></item>


    <item><p>The <code>style</code> attribute takes a space-separated list of
    style hints.  Processing tools should adjust their behavior according to
    those style hints they understand.</p></item>

    <item><p>The <code>type</code> element indicates whether the keys should be
    pressed together (<code>"combo"</code>) or in sequence (<code>"sequence"</code>).
    The default is <code>"combo"</code>.</p></item>

    <item><p>The <code>keyseq</code> element can have attributes from external
    namespaces.  See <link xref="mal_external"/> for more information
    on external-namespace attributes.</p></item>
  </list>
</section>
<!-- END notes -->


<!-- BEGIN examples -->
<section id="examples">
  <title>Examples</title>

  <p>Use <code>keyseq</code> to mark up a keyboard shortcut:</p>

  <example>
    <code><![CDATA[
Press <keyseq><key>Ctrl</key><key>Q</key></keyseq> to quit.
]]></code>
    <p>Press <keyseq><key>Ctrl</key><key>Q</key></keyseq> to quit.</p>
  </example>

  <p>Use <code>keyseq</code> with text for classes of keys:</p>

  <example>
    <code><![CDATA[
Press <keyseq><key>Shift</key>arrow keys</keyseq> to make a continuous
selection as you move the keyboard focus.
]]></code> 
    <p>Press <keyseq><key>Shift</key>arrow keys</keyseq> to make a continuous
    selection as you move the keyboard focus.</p>
  </example>

  <p>Use <code>keyseq</code> with text for mouse actions:</p>

  <example>
    <code><![CDATA[
<keyseq><key>Shift</key>click</keyseq> to make a continuous selection.
]]></code> 
    <p><keyseq><key>Shift</key>click</keyseq> to make a continuous selection.</p>
  </example>

  <p>Use nested <code>keyseq</code> elements for complex key commands:</p>

  <example>
    <code><![CDATA[
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>.
]]></code> 
    <p>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>.</p>
  </example>

  <p>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 <code>keyseq</code>
  elements:</p>

  <example>
    <code><![CDATA[
There are various ways to modify drag behavior by using
<keyseq><keyseq>modifier</keyseq>drag</keyseq>.
]]></code> 
    <p>There are various ways to modify drag behavior by using
    <keyseq><keyseq>modifier</keyseq>drag</keyseq>.</p>
  </example>
</section>
<!-- END examples -->


<!-- BEGIN processing -->
<section id="processing">
  <title>Processing Expectations</title>

  <p>Each of the child <code>key</code> 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 <code>type</code>
  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.</p>

  <p>Child <code>key</code> and <code>keyseq</code> 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.</p>
</section>
<!-- END processing -->


<!-- BEGIN comparison -->
<section id="comparison">
  <title>Comparison to Other Formats</title>
  <p>The <code>keyseq</code> element is similar to the
  <code href="http://www.docbook.org/tdg/en/html/keycombo.html">keycombo</code>
  element in DocBook.  Like <code>keycombo</code>, <code>keyseq</code> elements
  can be nested to indicate sequences of key combinations.  Since Mallard does
  not provide an element analogous to the DocBook element
  <code href="http://www.docbook.org/tdg/en/html/mousebutton.html">mousebutton</code>,
  mouse actions in key sequences should be written as text content without markup.</p>
</section>
<!-- END comparison -->

</page>
