From 5e1f23d4285564258ab8c9c43ec2c7b33853d528 Mon Sep 17 00:00:00 2001
From: Shaun McCance <shaunm@gnome.org>
Date: Tue, 19 May 2009 13:47:26 -0500
Subject: [mallard] Finishing block_figure and block_desc

---
 doc/mallard/C/mal_block.xml        |  1 -
 doc/mallard/C/mal_block_desc.xml   | 78 ++++++++++++++++++++++++++++++++------
 doc/mallard/C/mal_block_figure.xml | 74 +++++++++++++++++++++++++++++++++---
 3 files changed, 135 insertions(+), 18 deletions(-)

diff --git a/doc/mallard/C/mal_block.xml b/doc/mallard/C/mal_block.xml
index 9078302..32c2865 100644
--- a/doc/mallard/C/mal_block.xml
+++ b/doc/mallard/C/mal_block.xml
@@ -146,7 +146,6 @@ mal_block_list = (
 <!-- BEGIN other -->
 <section id="other">
   <info>
-    <title type="link">Other Block Elements</title>
     <link type="topic" xref="mal_title"/>
     <link type="topic" xref="mal_subtitle"/>
     <link type="topic" xref="mal_block_desc"/>
diff --git a/doc/mallard/C/mal_block_desc.xml b/doc/mallard/C/mal_block_desc.xml
index dca52d9..789e206 100644
--- a/doc/mallard/C/mal_block_desc.xml
+++ b/doc/mallard/C/mal_block_desc.xml
@@ -3,7 +3,11 @@
       id="mal_block_desc">
 
 <info>
-  <version number="0.1" date="2009-04-19" status="incomplete"/>
+  <link type="seealso" xref="mal_block_figure"/>
+  <link type="seealso" xref="mal_block_listing"/>
+  <link type="seealso" xref="mal_block_synopsis"/>
+
+  <version number="0.1" date="2009-05-19" status="review"/>
 
   <credit type="author">
     <name>Shaun McCance</name>
@@ -16,7 +20,7 @@
 
   <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
 
-  <desc>FIXME</desc>
+  <desc>Provide a caption for a formal block element.</desc>
 </info>
 
 <title>Block Descriptions</title>
@@ -36,17 +40,45 @@ The description provided by <code>desc</code> is formatted as a caption
 for the formal element.</p>
 
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>desc</code> element can contain a mixture of text and
+    any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+    <item><p>The <code>desc</code> element can occur in the formal block elements
+    <code xref="mal_block_figure">figure</code>,
+    <code xref="mal_block_listing">listing</code>, and
+    <code xref="mal_block_synopsis">synopsis</code>.</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>desc</code> element can have attributes from external
+    namespaces.  See <link xref="mal_external"/> for more information
+    on external-namespace attributes.</p></item>
+
+    <item><p>The <code>desc</code> element can also be used in an informational
+    context.  See <link xref="mal_info_desc"/> for more information.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
 
-  <p>Use <code>desc</code> to provide a caption for a figure:</p>
+  <p>Use <code>desc</code> to provide a caption for a
+  <link xref="mal_block_figure">figure</link>:</p>
 
   <example>
     <code><![CDATA[
 <figure>
-  <media type="image" mime="image/png" src="figures/mallard.png"/>
   <desc>Drake, the Mallard mascot</desc>
+  <media type="image" mime="image/png" src="figures/mallard.png"/>
 </figure>
 ]]></code>
     <figure>
@@ -55,7 +87,33 @@ for the formal element.</p>
     </figure>
   </example>
 
-  <p>More exaples of figures can be found on the page <link xref="mal_block_figure"/>.</p>
+  <p>Use <code>desc</code> to provide a caption for a
+  <link xref="mal_block_figure">listing</link>:</p>
+
+  <example>
+    <code><![CDATA[
+<listing>
+  <desc>A first Mallard page</desc>
+  <code><![CDATA[
+<page xmlns="http://www.gnome.org/~shaunm/mallard"
+      type="guide"
+      id="index">
+  <!-- Content goes here -->
+</page>]]]>]><![CDATA[</code>
+</listing>]]></code>
+    <listing>
+      <desc>A first Mallard page</desc>
+      <code><![CDATA[
+<page xmlns="http://www.gnome.org/~shaunm/mallard"
+      type="guide"
+      id="index">
+  <!-- Content goes here -->
+</page>]]></code>
+    </listing>
+  </example>
+
+  <p>More exaples can be found on the pages <link xref="mal_block_figure"/>,
+  <link xref="mal_block_listing"/>, and <link xref="mal_block_synopsis"/>.</p>
 </section>
 <!-- END examples -->
 
@@ -65,14 +123,12 @@ for the formal element.</p>
   <title>Processing Expectations</title>
 
   <p>The exact display of a description will depend on how the enclosing formal
-  element is displayed.  A description is a block of text that should be displayed
+  element is displayed.  A description is a block of text that is displayed
   directly above or below the normal contents of the enclosing element.</p>
 
-  <p>Display tools should attempt to display the description in a way that makes it
-  clear that it belongs to the enclosing formal element.  For example, if a display
-  tool draws a frame around an enclosing figure, it may choose to place the description
-  inside that frame.  If the formal element is indented from its enclosing block, the
-  description should also be at the same indentation level.</p>
+  <p>A description should be displayed in a way that makes its role clearn and
+  which clearly distinguishes it from the normal block content of the enclosing
+  element.</p>
 </section>
 <!-- END processing -->
 
diff --git a/doc/mallard/C/mal_block_figure.xml b/doc/mallard/C/mal_block_figure.xml
index 2920eb0..a9ad7f1 100644
--- a/doc/mallard/C/mal_block_figure.xml
+++ b/doc/mallard/C/mal_block_figure.xml
@@ -3,7 +3,23 @@
       id="mal_block_figure">
 
 <info>
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <link type="seealso" xref="mal_block_media"/>
+  <link type="seealso" xref="mal_block_listing"/>
+
+  <version number="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>Provide a title or caption for a multimedia object.</desc>
 </info>
 
 <title>Figures</title>
@@ -19,11 +35,11 @@ mal_block_figure = element figure {
 }
 </code></synopsis>
 
-<comment>
-  <cite date="2006-11-16"><name>Shaun McCance</name></cite>
-  <p>Add explanation, examples, processing expectations</p>
-  <p>A way to float right, a'la wikipedia?</p>
-</comment>
+<p>Use the <code>figure</code> element to provide a title or caption for a
+<link xref="mal_block_media">multimedia object</link> or other block object.
+To provide a title for the contents of a file, such as a
+<link xref="mal_block_code">code block</link>, use the
+<code xref="mal_block_listing">listing</code> element instead.</p>
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -50,4 +66,50 @@ mal_block_figure = element figure {
 </section>
 <!-- END notes -->
 
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Use <code>figure</code> to provide a title and caption for an image:</p>
+
+  <example>
+    <code><![CDATA[
+<figure>
+  <title>Drake</title>
+  <desc>Drake is the Mallard mascot.</desc>
+  <media type="image" mime="image/png" src="figures/mallard.png"/>
+</figure>
+]]></code>
+    <figure>
+      <title>Drake</title>
+      <desc>Drake is the Mallard mascot.</desc>
+      <media type="image" mime="image/png" src="figures/mallard.png"/>
+    </figure>
+  </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>Figures are displayed as block elements, with each of their child elements
+  being interpreted as block elements.  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>figure</code> is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/figure.html">figure</code>
+  element in DocBook.  DocBook only provides a title for figures, whereas
+  Mallard distinguishes between a title and a caption.</p>
+</section>
+<!-- END comparison -->
+
 </page>
-- 
cgit v1.2.1