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

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

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

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

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

  <desc>Mark up a sequence of interface controls to navigate.</desc>
</info>

<title>GUI Sequences</title>

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

  mixed { <link xref="mal_inline_gui">mal_inline_gui</link> + }
}
</code></synopsis>

<p>Use the <code>guiseq</code> element to mark up a sequence of graphical
interface elements.  This is typically used to present a sequence of menu
items.</p>


<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>guiseq</code> element can contain a mixture of text and
    <code xref="mal_inline_gui">gui</code> elements.</p></item>

    <item><p>The <code>guiseq</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>guiseq</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>guiseq</code> to mark up a sequence of menu items:</p>

  <example>
    <code><![CDATA[
Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open
a new document.
]]></code>
    <p>Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open
    a new document.</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 the
  language and style preferences, but it will typically be some sort of
  right-pointing arrow or triangle, or left-pointing for right-to-left
  languages.</p>

  <p>Child <code>gui</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>guiseq</code> element is similar to the
  <code href="http://www.docbook.org/tdg/en/html/menuchoice.html">menuchoice</code>
  element in DocBook.  Since Mallard does not provide different elements for
  different types of interface elements, the contents of <code>guiseq</code>
  are all <code>gui</code> elements or text.  Currently, Mallard does not
  provide a way to encode shortcut keys like the
  <code href="http://www.docbook.org/tdg/en/html/shortcut.html">shortcut</code>
  element in DocBook.  It is recommended that shortcuts, when necessary, be
  written into prose separately.</p>
</section>
<!-- END comparison -->

</page>
