[gnome-doc-utils/mallard] [mallard] Work on mal_page and mal_section pages

[Shaun McCance <shaunm src gnome org>]

commit cf1f309a9c9159e150308e2bcbd24795265dfc63
Author: Shaun McCance <shaunm gnome org>
Date:   Wed May 27 16:30:34 2009 -0500

    [mallard] Work on mal_page and mal_section pages
---
 doc/mallard/C/links.xml       |   33 +++++++++++++++
 doc/mallard/C/mal_page.xml    |   89 +++++++++++++++++++++++++++++++++--------
 doc/mallard/C/mal_section.xml |    1 +
 3 files changed, 106 insertions(+), 17 deletions(-)

diff --git a/doc/mallard/C/links.xml b/doc/mallard/C/links.xml
new file mode 100644
index 0000000..a158eaf
--- /dev/null
+++ b/doc/mallard/C/links.xml
@@ -0,0 +1,33 @@
+<page xmlns="http://www.gnome.org/~shaunm/mallard";
+      type="topic"
+      id="links">
+
+<info>
+  <link type="seealso" xref="mal_page"/>
+  <link type="seealso" xref="mal_section"/>
+
+  <version number="0.1" date="2008-02-21" status="stub"/>
+</info>
+
+<title>Automatic Links</title>
+
+
+<!-- BEGIN topic -->
+<section id="topic">
+  <title>Topic Links</title>
+</section>
+<!-- END topic -->
+
+<!-- BEGIN guide -->
+<section id="guide">
+  <title>Guide Links</title>
+</section>
+<!-- END guide -->
+
+<!-- BEGIN seealso -->
+<section id="seealso">
+  <title>See Also Links</title>
+</section>
+<!-- END seealso -->
+
+</page>
diff --git a/doc/mallard/C/mal_page.xml b/doc/mallard/C/mal_page.xml
index f6b4c16..00f3901 100644
--- a/doc/mallard/C/mal_page.xml
+++ b/doc/mallard/C/mal_page.xml
@@ -12,37 +12,55 @@
 namespace local = ""
 default namespace mal = "http://www.gnome.org/~shaunm/mallard";
 start = mal_page
-mal_page = (mal_page_guide | mal_page_topic)
-mal_page_guide = element page {
+mal_page = element page {
   attribute id { xsd:ID },
-  attribute type { "guide" },
+  attribute type { "guide" | "topic"} ?,
   attribute style { xsd:NMTOKENS } ?,
   attribute * - (mal:* | local:*) { text } *,
-  <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_page_topic = element page {
-  attribute id { xsd:ID },
-  attribute type { "topic" },
-  attribute style { xsd:NMTOKENS } ?,
-  attribute * - (mal:* | local:*) { text } *,
-  <link xref="mal_info">mal_info</link>,
+
+  <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> *
 }
 </code></synopsis>
 
+<p>The <code>page</code> element is the root element of any Mallard page file.
+In Mallard, documents are composed of discrete pages which are  interlinked
+using various linking mechanisms.  There are two types of pages in Mallard:
+<link xref="#guide">guide pages</link> and <link xref="#topic">topic pages</link>.
+Topic pages contain the bulk of the material discussed in a document, whereas
+guide pages serve as navigational aids.</p>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
   <title>Notes</title>
   <list>
+    <item><p>The <code>page</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>page</code> element is the top-level element in any
+    Mallard page file, and cannot occur in any other elements.</p></item>
+
+    <item><p>The <code>id</code> attribute takes a unique identifier, which
+    should match the base file name (without extension) of the file containing
+    the page.</p></item>
+
     <item><p>The <code>type</code> attribute takes the values <code>"guide"</code> and
     <code>"topic"</code>.  <link xref="#guide">Guide pages</link> and <link xref="#topic">topic
-    pages</link> are discussed below.</p></item>
+    pages</link> are discussed below.  If the <code>type</code> attribute is
+    omitted, it is assumed to be <code>"topic"</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>page</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 -->
@@ -51,6 +69,27 @@ mal_page_topic = element page {
 <!-- BEGIN guide -->
 <section id="guide">
   <title>Guide Pages</title>
+
+  <p>Guide pages have the <code>type</code> attribute set to
+  <code>"guide"</code>.  They serve as navigational aids, linking to topics and
+  other guides.  Readers can can browse through guides much as they would browse
+  through container sections in a linear document.  Since page can be included
+  in multiple guides, however, readers are able to reach the same content by
+  navigating different paths.</p>
+
+  <p>Guide pages have links automatically inserted into their content based
+  on topic links within their own <code xref="mal_info">info</code> elements
+  and guide links within the <code>info</code> elements of other pages and
+  sections.  Guide pages can contain sections to help organize content.  Each
+  section in a guide page has automatic links inserted as well.  See
+  <link xref="links#topic"/> for details on automatic topic links.</p>
+
+  <p>Guides also have see also links generated automatically.  See
+  <link xref="links#seealso"/> for more information.</p>
+
+  <p>Generally, guide pages will contain some introductory content to help
+  readers understand the topics being presented.  Introductory content should
+  be short and concise.</p>
 </section>
 <!-- END topic -->
 
@@ -58,10 +97,26 @@ mal_page_topic = element page {
 <!-- BEGIN topic -->
 <section id="topic">
   <title>Topic Pages</title>
-</section>
-<!-- END topic -->
 
+  <p>Topic pages have the <code>type</code> attribute set to
+  <code>"topic"</code>, or have no <code>type</code> attribute at all.  Topics
+  contain the bulk of the material in a document.  A Topic may be a tutorial,
+  a conceptual overview, reference material, or any other type of content.
+  Mallard does not distinguish between different content types, although tools
+  may introduce special styling based on style hints.  Topics are distinguished
+  from guides only in that their primary purpose is to convey information,
+  whereas guides serve as navigational aids.</p>
+
+  <p>Topic pages have links automatically inserted to all guides which link
+  to them.  Topic pages can contain sections to help organize material and
+  present finer-grained chunks of information to the reader.  Each section
+  in a topic page has automatic guide links inserted as well.  See
+  <link xref="links#guide"/> for details on automatic guide links.</p>
 
+  <p>Topics also have see also links generated automatically.  See
+  <link xref="links#seealso"/> for more information.</p>
+</section>
+<!-- END topic -->
 
 
 <!-- BEGIN processing -->
diff --git a/doc/mallard/C/mal_section.xml b/doc/mallard/C/mal_section.xml
index b2c20da..75b9384 100644
--- a/doc/mallard/C/mal_section.xml
+++ b/doc/mallard/C/mal_section.xml
@@ -13,6 +13,7 @@ mal_section = element section {
   attribute id { xsd:ID },
   attribute style { xsd:NMTOKENS } ?,
   attribute * - (mal:* | local:*) { text } *,
+
   <link xref="mal_info">mal_info</link> ?,
   <link xref="mal_block_title">mal_block_title</link>,
   <link xref="mal_block">mal_block</link> *,