[mallard] Finishing mal_page and mal_section

2 files changed, 102 insertions, 3 deletions

diff --git a/doc/mallard/C/mal_page.xml b/doc/mallard/C/mal_page.xml
index 00f3901..731e303 100644
--- a/doc/mallard/C/mal_page.xml
+++ b/doc/mallard/C/mal_page.xml
@@ -3,7 +3,20 @@
       id="mal_page">
 
 <info>
-  <version number="0.1" date="2008-02-21" status="stub"/>
+  <version number="0.1" date="2009-05-28" 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>Individual tutorials, overviews, references, and navigational guides.</desc>
 </info>
 
 <title>Pages</title>
@@ -122,6 +135,24 @@ guide pages serve as navigational aids.</p>
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
+
+  <p>In on-screen media, a <code>page</code> element is displayed as a single
+  page.  In this case, <em>page</em> is used in the sense of <em>web page</em>:
+  something which can be read top-to-bottom by scrolling.  This should not be
+  confused with physical pages — one side of a leaf of paper — or with any
+  fixed-height electronic pages such as those used by word processors and
+  e-books.</p>
+
+  <p>The <code>info</code> child element is not displayed directly, although
+  certain informational elements may be displayed or affect aspects of the
+  page display.  In particular, the <code>info</code> element may contain
+  <code>link</code> elements which will cause automatic links to be inserted
+  into the displayed output.  See <link xref="links"/> for more information.</p>
+
+  <p>The title of a page is displayed prominently at the top, followed by any
+  child block content, and finally by each child section.  Note that automatic
+  links, style hints, or other special features may insert material or change
+  the way pages are displayed.</p>
 </section>
 <!-- END processing -->
 
diff --git a/doc/mallard/C/mal_section.xml b/doc/mallard/C/mal_section.xml
index 75b9384..25467f0 100644
--- a/doc/mallard/C/mal_section.xml
+++ b/doc/mallard/C/mal_section.xml
@@ -3,7 +3,21 @@
       id="mal_section">
 
 <info>
-  <version number="0.1" date="2007-02-22" status="stub"/>
+  <version number="0.1" date="2009-05-28" 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>Break up pages into logical chunks to help readers find
+  information quickly.</desc>
 </info>
 
 <title>Sections</title>
@@ -17,8 +31,62 @@ mal_section = element section {
   <link xref="mal_info">mal_info</link> ?,
   <link xref="mal_block_title">mal_block_title</link>,
   <link xref="mal_block">mal_block</link> *,
-  <link xref="mal_section">mal_section</link> *
+  mal_section *
 }
 </code></synopsis>
 
+<p>A section is a prominent logical part of a page or another section.
+Breaking up material into sections can help readers find information
+more quickly.  In Mallard, sections can take part in
+<link xref="links">automatic linking</link> just as pages can.</p>
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list>
+    <item><p>The <code>section</code> element contains an optional
+    <code xref="mal_info">info</code> element, a <code xref="mal_block_title">title</code>
+    element, any <link xref="mal_block">general block content</link>, and
+    any number of <code xref="mal_section">section</code> elements.</p></item>
+
+    <item><p>The <code>section</code> can occur in <code xref="mal_page">page</code>
+    elements and other <code>section</code> elements.</p></item>
+
+    <item><p>The <code>id</code> attribute takes a unique identifier.  It should
+    be distinct from all other <code>id</code> attributes in the same page,
+    including those on other <code>section</code> elements and on the containing
+    <code xref="mal_page">page</code> element.</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>section</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 processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>Each section is displayed as a block.  The title of a section is displayed
+  prominently, followed by any child block content, and finally by each child
+  section.  Note that automatic links, style hints, or other special features
+  may insert material or change the way pages are displayed.  Sections should
+  be clearly separated from their surrounding content to make the beginning and
+  ending of each section obvious.  The depth of each section should be clear,
+  although this may not be feasible for deeply nested sections.</p>
+
+  <p>Sections may have links associated with them.  All sections should have
+  guide links and see also links displayed when applicable.  See
+  <link xref="links#guide"/> and <link xref="links#seealso"/> for more
+  information.  Sections in guide pages have topic links inserted following
+  their block content.  See <link xref="links#topic"/> for more information.</p>
+</section>
+<!-- END processing -->
+
 </page>