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

<info>
  <revision version="0.1" date="2009-05-06" 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 a group of block elements as being part of a single example.</desc>
</info>

<title>Examples</title>

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

  <link xref="mal_block">mal_block</link> +
}
</code></synopsis>

<p>Use the <code>example</code> element to place block elements into a
logical group, indicating that they are part of a single example.  This
may be used to group example input with its result, to show different
steps with different types of block elements, or simply to group some
paragraphs together.</p>


<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>example</code> element can contain any
    <link xref="mal_block">general block content</link>.</p></item>

    <item><p>The <code>example</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>example</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>example</code> to show how to use the <code>screen</code>
  element, grouping the input and formatted result:</p>

  <example>
    <code><![CDATA[
<example>
<code><![CDATA[
<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen>
]]>]<![CDATA[]></code>
<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen>
</example>
]]></code>
    <example>
      <code><![CDATA[
<screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen>
]]></code>
      <screen>
xsltproc -o mal_block_screen.html \
  --stringparam mal.cache.file `pwd`/mallard.cache \
  `pkg-config --variable mal2html gnome-doc-utils` \
  mal_block_screen.html
</screen></example>
  </example>
</section>
<!-- END examples -->


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

  <p>The contents of an <code>example</code> element should each be rendered
  as block elements as normal.  Example should use margins, borders, or other
  stylistic effects to provide a clear visual indication of the grouping.</p>
</section>
<!-- END processing -->


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

  <p>The <code>example</code> element is similar to the
  <code href="http://www.docbook.org/tdg/en/html/example.html">example</code>
  element in DocBook.  In DocBook, the <code>example</code> element is a
  formal element.  In Mallard, <code>example</code> is a simple container
  element, and does not allow a <code xref="mal_block_title">title</code>
  element.</p>
</section>
<!-- END comparison -->

</page>
