diff options
author | Shaun McCance <shaunm@gnome.org> | 2009-05-29 16:34:16 -0500 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2009-05-29 16:34:16 -0500 |
commit | 752a0526ad47b8524952756edb20c10f45449504 (patch) | |
tree | fa7212bc032763a655c6006b7291f7529bc67d73 | |
parent | 66ae687e3209ab2e194c609bec38d300b33aa934 (diff) | |
download | gnome-doc-utils-752a0526ad47b8524952756edb20c10f45449504.tar.gz |
[mallard] Finished info_title
-rw-r--r-- | doc/mallard/C/mal_info_title.xml | 97 |
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> |