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

<info>
  <link type="seealso" xref="mal_block_listing"/>

  <revision version="0.1" date="2009-05-19" 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>Create an overview of concepts.</desc>
</info>

<title>Synopses</title>

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

  <link xref="mal_block_title">mal_block_title</link> ?,
  <link xref="mal_block_desc">mal_block_desc</link> ?,
  <link xref="mal_block">mal_block</link> +
}
</code></synopsis>

<p>The <code>synopsis</code> element allows you to mark up a block as
providing an overview of the material being presented.  It is useful
for providing a listing of functions, commands, or options in reference
material, or for enumerating the items in a menu or other graphical
control element.</p>

<comment>
  <cite date="2006-11-16">Shaun McCance</cite>
  <p>Add explanation, examples</p>
</comment>


<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>synopsis</code> element contains an optional
    <link xref="mal_block_title">title</link> element, an optional
    <link xref="mal_block_desc">desc</link> element, and  any
    <link xref="mal_block">general block content</link>.</p></item>

    <item><p>The <code>synopsis</code> element can occur in any
    general block context, including inside
    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
    and certain <link xref="mal_block">block 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>synopsis</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>synopsis</code> to create an overview of functions:</p>

  <example>
    <code><![CDATA[<synopsis>
<title>Beanstalk Functions</title>
<desc>Use these methods on a <code>Beanstalk</code> object.</desc>
<code>
void add_bean    (Bean bean);
int  count_beans ();
</code>
</synopsis>
]]></code>
    <synopsis>
      <title>Beanstalk Functions</title>
      <desc>Use these methods on a <code>beanstalk</code> object.</desc>
      <code>
void add_bean    (Bean bean);
int  count_beans ();
</code>
    </synopsis>
  </example>
</section>
<!-- END examples -->


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

  <p>A <code>synopsis</code> element is rendered as a displayed block,
  with each of its child elements interpreted as block elements.  Since
  a <code>synopsis</code> element often contains large blocks, and is
  generally offset from the running text, display tools may opt to render
  it inside a colored box, with a border, or otherwise differently from
  the surrounding text.</p>

  <p>When present, the title and description should be displayed in a
  way that makes their respective roles clear.</p>
</section>
<!-- END processing -->


<!-- BEGIN comparison -->
<section id="comparison">
  <title>Comparison to Other Formats</title>

  <p>The <code>synopsis</code> element is similar to the
  <code href="http://www.docbook.org/tdg/en/html/synopsis.html">synopsis</code>
  element in DocBook, although the DocBook element is not a formal element.
  DocBook also provides the
  <code href="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</code> and
  <code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html">funcsynopsis</code>
  elements, which attempt to model the data for command and function synopses,
  respectively.  Mallard does not provide modelling elements.</p>
</section>
<!-- END comparison -->

</page>
