[mallard] Added content to block_example, plus typo fixes

5 files changed, 102 insertions, 5 deletions

diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index 9ac8b0f..75c54e4 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -56,7 +56,7 @@ by the user.</p>
 
     <item><p>The <code>code</code> element can have attributes from external
     namespaces.  See <link xref="mal_attr_external"/> for more information
-    on external-namespace attributes on inline elements.</p></item>
+    on external-namespace attributes on block elements.</p></item>
 
     <item><p>The <code>code</code> element may also be used in an inline context.
     See <link xref="mal_inline_code"/> for more information.</p></item>
diff --git a/doc/mallard/C/mal_block_example.xml b/doc/mallard/C/mal_block_example.xml
index 6333fd6..d349b7a 100644
--- a/doc/mallard/C/mal_block_example.xml
+++ b/doc/mallard/C/mal_block_example.xml
@@ -3,7 +3,20 @@
       id="mal_block_example">
 
 <info>
-  <version number="0.1" date="2008-12-21" status="stub"/>
+  <version number="0.1" date="2009-05-06" 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 a group of block elements as being part of a single example.</desc>
 </info>
 
 <title>Examples</title>
@@ -17,17 +30,101 @@ mal_block_example = element example {
 }
 </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>
+
 <comment>
   <cite date="2008-12-11"><name>Shaun McCance</name></cite>
   <p>Add explanation, examples</p>
 </comment>
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <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_attr_external"/> for more information
+    on external-namespace attributes on block elements.</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_title">title</code>
+  element.</p>
+</section>
+<!-- END comparison -->
+
 </page>
diff --git a/doc/mallard/C/mal_block_media.xml b/doc/mallard/C/mal_block_media.xml
index 2ca7498..78ee252 100644
--- a/doc/mallard/C/mal_block_media.xml
+++ b/doc/mallard/C/mal_block_media.xml
@@ -57,7 +57,7 @@ for details on how fallback elements are handled.</p>
 
     <item><p>The <code>media</code> element can have attributes from external
     namespaces.  See <link xref="mal_attr_external"/> for more information
-    on external-namespace attributes on inline elements.</p></item>
+    on external-namespace attributes on block elements.</p></item>
 
     <item><p>The <code>media</code> element may also be used in an inline context.
     See <link xref="mal_inline_media"/> for more information.</p></item>
diff --git a/doc/mallard/C/mal_block_screen.xml b/doc/mallard/C/mal_block_screen.xml
index d8c70fa..94aa940 100644
--- a/doc/mallard/C/mal_block_screen.xml
+++ b/doc/mallard/C/mal_block_screen.xml
@@ -75,7 +75,7 @@ by the user.</p>
 
     <item><p>The <code>screen</code> element can have attributes from external
     namespaces.  See <link xref="mal_attr_external"/> for more information
-    on external-namespace attributes on inline elements.</p></item>
+    on external-namespace attributes on block elements.</p></item>
   </list>
 </section>
 <!-- END notes -->
diff --git a/doc/mallard/C/mal_block_synopsis.xml b/doc/mallard/C/mal_block_synopsis.xml
index a9ae0dc..c1b7a5d 100644
--- a/doc/mallard/C/mal_block_synopsis.xml
+++ b/doc/mallard/C/mal_block_synopsis.xml
@@ -54,7 +54,7 @@ control element.</p>
 
     <item><p>The <code>synopsis</code> element can have attributes from external
     namespaces.  See <link xref="mal_attr_external"/> for more information
-    on external-namespace attributes on inline elements.</p></item>
+    on external-namespace attributes on block elements.</p></item>
   </list>
 </section>
 <!-- END notes -->