From 752a0526ad47b8524952756edb20c10f45449504 Mon Sep 17 00:00:00 2001
From: Shaun McCance <shaunm@gnome.org>
Date: Fri, 29 May 2009 16:34:16 -0500
Subject: [mallard] Finished info_title

---
 doc/mallard/C/mal_info_title.xml | 97 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 95 insertions(+), 2 deletions(-)

diff --git a/doc/mallard/C/mal_info_title.xml b/doc/mallard/C/mal_info_title.xml
index 67c1c85..3eaffb5 100644
--- a/doc/mallard/C/mal_info_title.xml
+++ b/doc/mallard/C/mal_info_title.xml
@@ -5,10 +5,23 @@
 <info>
   <link type="guide" xref="mal_info#elements"/>
 
-  <revision version="0.1" date="2009-05-28" status="stub"/>
+  <revision version="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 alternate titles for automatic link text and sorting.</desc>
 </info>
 
-<title>Tiltes</title>
+<title>Informational Tiltes</title>
 
 <synopsis><code mime="application/relax-ng-compact-syntax">
 mal_info_title = element title {
@@ -20,28 +33,108 @@ mal_info_title = element title {
 }
 </code></synopsis>
 
+<p>Use the <code>title</code> element inside an <code xref="mal_info">info</code>
+to list alternative titles for pages and sections.  These titles can be used
+as alternative link text, for sorting, or for other application-specific
+purposes.</p>
+
+
 <!-- BEGIN notes -->
 <section id="notes">
   <title>Notes</title>
+  <list>
+    <item><p>The <code>title</code> element can contain a mixture of text and
+    any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+    <item><p>The <code>title</code> element can occur in any
+    <code xref="mal_info">info</code> element.</p></item>
+
+    <item><p>The <code>type</code> attribute specifies what purpose this
+    informational title is serving.  The following values are currently
+    recognized:</p>
+    <table rules="rows">
+      <tr>
+        <td><p><code>"link"</code></p></td>
+        <td><p>specifies alternate link text; see <link xref="#link"/></p></td>
+      </tr>
+      <tr>
+        <td><p><code>"sort"</code></p></td>
+        <td><p>specifies a sort key; see <link xref="#sort"/></p></td>
+      </tr>
+    </table></item>
+
+    <item><p>The <code>role</code> attribute can be used for link titles
+    to specify multiple alternate link texts.</p></item>
+
+    <item><p>The <code>title</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 primary -->
 <section id="primary">
   <title>Primary Titles</title>
+
+  <p>The <em>primary title</em> of a page or section is the one specified in
+  the block context and used for display purpose.  While this title is not
+  an informational title as specified here, it is used as fallback for all
+  informational titles.</p>
 </section>
 <!-- END primary -->
 
+
 <!-- BEGIN link -->
 <section id="link">
   <title>Link Titles</title>
+
+  <p>Pages and sections can have multiple link titles.  These are used as
+  alternate content for automatic link text.  When automatic text must be
+  generated for a <code xref="mal_block_link">link</code> element, it is
+  taken first from the link titles, falling back to the primary title if
+  no suitable link title is found.</p>
+
+  <p>You can use the <code>role</code> attribute to specify multiple link
+  titles.  These can be selected using the <code>role</code> attribute of
+  the <code>link</code> element.  This can be used for a variety of purposes.
+  One common purpose is to specify link text for different parts of speech
+  in languages which have case declensions.  Without this feature, it can
+  be difficult to provide grammatically correct automatic link text in
+  some languages.</p>
 </section>
 <!-- END link -->
 
+
 <!-- BEGIN sort -->
 <section id="sort">
   <title>Sort Titles</title>
+
+  <p>Sort titles allow you to specify alternate text to be used when sorting
+  the page or section.  Certain automatic link sections will sort the nodes
+  they link to.  When this happens, providing a sort title allows you to
+  control how the node is collated.  This is useful for excluding leading
+  articles such as “an” and “the”.</p>
 </section>
 <!-- END sort -->
 
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>Informational titles are not displayed directly, although they will
+  affect the output of any material which links to the given page or
+  section.</p>
+
+  <p>The content model of the <code xref="mal_info">info</code> element
+  allows for any mixture of informational titles.  As such, it is entirely
+  possible for multiple titles to exist for some specified combination of
+  the <code>type</code> and <code>role</code> attributes.  When such an
+  ambiguity arrises, processing tools should select the first informational
+  title that matches the desired criteria.</p>
+</section>
+<!-- END processing -->
+
 </page>
-- 
cgit v1.2.1