diff options
-rw-r--r-- | doc/mallard/C/links.xml | 33 | ||||
-rw-r--r-- | doc/mallard/C/mal_page.xml | 89 | ||||
-rw-r--r-- | 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> *, |