[gnome-doc-utils/mallard] [mallard] Adding info to mal_inline_link

[Shaun McCance <shaunm src gnome org>]

commit 094b53780f5de03aeaaaac107de3a9dd2b9d0e1c
Author: Shaun McCance <shaunm gnome org>
Date:   Tue May 12 19:47:33 2009 -0500

    [mallard] Adding info to mal_inline_link
---
 doc/mallard/C/mal_inline_link.xml |   74 +++++++++++++++++++++++++++++++++++-
 1 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/doc/mallard/C/mal_inline_link.xml b/doc/mallard/C/mal_inline_link.xml
index 257bbcc..043c476 100644
--- a/doc/mallard/C/mal_inline_link.xml
+++ b/doc/mallard/C/mal_inline_link.xml
@@ -27,6 +27,7 @@ mal_inline_link = element link {
     attribute href { text } |
     ( attribute xref { text }, attribute href { text } )
   ),
+  attribute role { text } ?,
   attribute style { xsd:NMTOKENS } ?,
   attribute * - (mal:* | local:*) { text } *,
 
@@ -42,6 +43,9 @@ mal_inline_link = element link {
     <item><p>The <code>link</code> element can contain a mixture of text and
     any <link xref="mal_inline">general inline elements</link>.</p></item>
 
+    <item><p>For links within the same document, content can be automatically
+    generated.</p></item>
+
     <item><p>The <code>link</code> element can occur in any
     general inline context, including inside most
     <link xref="mal_inline">inline elements</link>, some
@@ -49,13 +53,15 @@ mal_inline_link = element link {
     <link xref="mal_info">informational elements</link>.</p></item>
 
     <item><p>The <code>xref</code> attribute creates a link to another page
-    or section within the same document.  When text content is omitted, the
-    content is automatically taken from the title of the page or section
-    being linked to.</p></item>
+    or section within the same document, or to an external resource in some
+    document management system.</p></item>
 
     <item><p>The <code>href</code> attribute creates a link to a web page
     or other network-accessible resource.</p></item>
 
+    <item><p>The <code>role</code> attribute can be used to select alternative
+    titles of the target page or section to be used as automatic content.</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>
@@ -78,6 +84,52 @@ mal_inline_link = element link {
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
+
+  <p>A <code>link</code> element is displayed as hyperlink which can be
+  clicked on or otherwise activated to take the user to another page,
+  document, or resource.  In certain environments, such as print, it
+  may not be possible to make links activatable.  In these cases, the
+  target of the link may be displayed in the rendered output.</p>
+
+  <p>The target of <code>link</code> element is determined from the
+  <code>xref</code> and <code>href</code> exactly as it is for other
+  inline elements.  See <link xref="mal_attr_link"/> for information
+  on determining the link target.</p>
+
+  <p>If the <code>link</code> element is non-empty, its contents are
+  displayed as normal.  Otherwise, automatic link text is generated
+  as follows:</p>
+
+  <list type="bullet">
+    <item><p>If the <code>link</code> element has an <code>xref</code>
+    attribute that points to a page or section in the same document:</p>
+
+    <list type="bullet">
+      <item><p>If the <code>link</code> element has a <code>role</code>
+      attribute, and that page or section has an
+      <link xref="mal_info_title">informational title</link> with the
+      <code>type</code> attribute set to <code>"link"</code> and the
+      <code>role</code> set to the same value as the <code>role</code>
+      attribute of the <code>link</code> element, then the contents
+      of that <code>title</code> element are used.</p></item>
+
+      <item><p>Otherwise, if that page or section has an
+      <link xref="mal_info_title">informational title</link> with the
+      <code>type</code> attribute set to <code>"link"</code> and without
+      a <code>role</code> attribute, the contents of that <code>title</code>
+      element are used.</p></item>
+
+      <item><p>Otherwise, the contents of the primary title of that page
+      page or section are used.</p></item>
+    </list>
+    </item>
+
+    <item><p>Otherwise, if the <code>link</code> element has an <code>xref</code>
+    attribute that points to a portion of another document, and the processing
+    tool knows how to generate link contents, that content is used.</p></item>
+
+    <item><p>Otherwise, the link target is used as text content.</p></item>
+  </list>
 </section>
 <!-- END processing -->
 
@@ -85,6 +137,22 @@ mal_inline_link = element link {
 <!-- BEGIN comparison -->
 <section id="comparison">
   <title>Comparison to Other Formats</title>
+
+  <p>The <code>link</code> element combines the functionality of the
+  <code href="http://www.docbook.org/tdg/en/html/link.html";>link</code>,
+  <code href="http://www.docbook.org/tdg/en/html/xref.html";>xref</code>, and
+  <code href="http://www.docbook.org/tdg/en/html/ulink.html";>ulink</code>
+  elements in DocBook.  For the <code>link</code> and <code>xref</code>
+  elements, DocBook provides the <code>endterm</code> attribute to select
+  an alternative element from which to take content.  Mallard does not
+  provide this feature, although it allows you to select from alternative
+  titles for the linked-to element.</p>
+
+  <p>DocBook provides the <code>xrefstyle</code> attribute to control how
+  automatic link text is generated.  The behavior of this attribute is
+  unspecified.  Rather than attempt to use style hints, Mallard allows
+  writers to specify exact alternative link contents.  Alternative link
+  contents are important in languages with case declensions.</p>
 </section>
 <!-- END comparison -->