summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorShaun McCance <shaunm@gnome.org>2009-05-29 16:34:16 -0500
committerShaun McCance <shaunm@gnome.org>2009-05-29 16:34:16 -0500
commit752a0526ad47b8524952756edb20c10f45449504 (patch)
treefa7212bc032763a655c6006b7291f7529bc67d73
parent66ae687e3209ab2e194c609bec38d300b33aa934 (diff)
downloadgnome-doc-utils-752a0526ad47b8524952756edb20c10f45449504.tar.gz
[mallard] Finished info_title
-rw-r--r--doc/mallard/C/mal_info_title.xml97
1 files 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>