[mallard] Finishing info_desc

1 files changed, 54 insertions, 2 deletions

diff --git a/doc/mallard/C/mal_info_desc.xml b/doc/mallard/C/mal_info_desc.xml
index 84e39aa..0986ea2 100644
--- a/doc/mallard/C/mal_info_desc.xml
+++ b/doc/mallard/C/mal_info_desc.xml
@@ -5,17 +5,69 @@
 <info>
   <link type="guide" xref="mal_info#elements"/>
 
-  <version number="0.1" date="2007-02-23" status="stub"/>
+  <version number="0.1" date="2009-05-29" 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 short description of a page or section.</desc>
 </info>
 
-<title>FIXME</title>
+<title>Page Descriptions</title>
 
 <synopsis><code mime="application/relax-ng-compact-syntax">
 mal_info_desc = element desc {
+  attribute * - (mal:* | local:*) { text } *,
+
   <link xref="mal_inline">mal_inline</link>
 }
 </code></synopsis>
 
+<p>The <code>desc</code> element can be used to provide a short description
+for a page or section.  While this description is generally not shown on the
+page itself, it is used in automatic links to the page or section.  It may
+also be used for various other purposes by different tools.</p>
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+
+  <list>
+    <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 any
+    <code xref="mal_info">info</code> element.</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 a block context.
+    See <link xref="mal_block_desc"/> for more information.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>The <code>desc</code> is not necessarily displayed on the page in which it
+  appears.  It is, however, used for <link xref="links">automatic links</link>,
+  which usually display a link block showing the title and description of the
+  linked-to page or section.  When it is displayed, its contents are treated
+  as inline content.</p>
+</section>
+<!-- END processing -->
+
 </page>