[gnome-doc-utils/mallard] [mallard] Finishing block_listing

[Shaun McCance <shaunm src gnome org>]

commit f2c9bbffe57e290b538c8a3237b4f663dd8c08f7
Author: Shaun McCance <shaunm gnome org>
Date:   Tue May 19 00:30:49 2009 -0500

    [mallard] Finishing block_listing
---
 doc/mallard/C/mal_block_listing.xml |   76 +++++++++++++++++++++++++++++++----
 1 files changed, 68 insertions(+), 8 deletions(-)

diff --git a/doc/mallard/C/mal_block_listing.xml b/doc/mallard/C/mal_block_listing.xml
index 8ed6fa3..646f9dd 100644
--- a/doc/mallard/C/mal_block_listing.xml
+++ b/doc/mallard/C/mal_block_listing.xml
@@ -3,7 +3,23 @@
       id="mal_block_listing">
 
 <info>
-  <version number="0.1" date="2009-05-02" status="stub"/>
+  <link type="seealso" xref="mal_block_code"/>
+  <link type="seealso" xref="mal_block_figure"/>
+
+  <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 name and description for a code block or other content.</desc>
 </info>
 
 <title>Listings</title>
@@ -19,10 +35,13 @@ mal_block_listing = element listing {
 }
 </code></synopsis>
 
-<comment>
-  <cite date="2009-05-02"><name>Shaun McCance</name></cite>
-  <p>Add explanation, examples, processing expectations</p>
-</comment>
+<p>Use the <code>listing</code> element to create named listing of file contents
+or other content.  Listings are usually used with <link xref="mal_block_code">code
+blocks</link> to provide a name for the file to enter the content into.  They may
+also be used to provide a name for an <link xref="mal_block_screen">interactive
+shell session</link> or any other type of content.  To provide a title for images
+or other multimedia objects, use the <link xref="mal_block_figure">figure</link>
+element.</p>
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -54,14 +73,55 @@ mal_block_listing = element listing {
 <section id="examples">
   <title>Examples</title>
 
+  <p>Use <code>listing</code> to provide a file name and description for a
+  code block:</p>
+
   <example>
+    <code><![CDATA[
+<listing>
+  <title><file>index.page</file></title>
+  <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>
-      <title>foo.c</title>
-      <desc>Some stuff in foo.c</desc>
-      <code>int foo ()</code>
+      <title><file>index.page</file></title>
+      <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>
 </section>
 <!-- END examples -->
 
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>Listings 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 -->
+<!--
+No direct analog in DocBook.  I'm sure people accomplish the same thing somehow,
+but my brain isn't working right now.  Also check DITA.
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+</section>
+-->
+<!-- END comparison -->
+
 </page>