GNOME.org
 

[gnome-doc-utils/mallard] [mallard] Adding info about external namespaces

commit 565fc95e66f78943cc6bdd52472de1ebd435c69a
Author: Shaun McCance <shaunm gnome org>
Date:   Tue May 12 17:39:18 2009 -0500

    [mallard] Adding info about external namespaces
    
    Moved mal_attr_external to mal_external.  It will have content about
    both external namespace attributes and external namespace elements.
---
 doc/mallard/C/mal_attr_external.xml  |   25 -----------
 doc/mallard/C/mal_attr_link.xml      |    2 +-
 doc/mallard/C/mal_block_cite.xml     |    2 +-
 doc/mallard/C/mal_block_code.xml     |    2 +-
 doc/mallard/C/mal_block_comment.xml  |    2 +-
 doc/mallard/C/mal_block_example.xml  |    2 +-
 doc/mallard/C/mal_block_media.xml    |    2 +-
 doc/mallard/C/mal_block_screen.xml   |    2 +-
 doc/mallard/C/mal_block_synopsis.xml |    2 +-
 doc/mallard/C/mal_external.xml       |   75 ++++++++++++++++++++++++++++++++++
 doc/mallard/C/mal_inline.xml         |   10 ++--
 doc/mallard/C/mal_inline_app.xml     |    2 +-
 doc/mallard/C/mal_inline_cmd.xml     |    2 +-
 doc/mallard/C/mal_inline_code.xml    |    2 +-
 doc/mallard/C/mal_inline_em.xml      |    2 +-
 doc/mallard/C/mal_inline_file.xml    |    2 +-
 doc/mallard/C/mal_inline_gui.xml     |    2 +-
 doc/mallard/C/mal_inline_guiseq.xml  |    2 +-
 doc/mallard/C/mal_inline_input.xml   |    2 +-
 doc/mallard/C/mal_inline_key.xml     |    2 +-
 doc/mallard/C/mal_inline_keyseq.xml  |    2 +-
 doc/mallard/C/mal_inline_link.xml    |    2 +-
 doc/mallard/C/mal_inline_media.xml   |    2 +-
 doc/mallard/C/mal_inline_output.xml  |    2 +-
 doc/mallard/C/mal_inline_quote.xml   |    2 +-
 doc/mallard/C/mal_inline_span.xml    |    2 +-
 doc/mallard/C/mal_inline_sys.xml     |    2 +-
 doc/mallard/C/mal_inline_var.xml     |    2 +-
 28 files changed, 105 insertions(+), 55 deletions(-)

diff --git a/doc/mallard/C/mal_attr_external.xml b/doc/mallard/C/mal_attr_external.xml
deleted file mode 100644
index cdc745f..0000000
--- a/doc/mallard/C/mal_attr_external.xml
+++ /dev/null
@@ -1,25 +0,0 @@
-<page xmlns="http://www.gnome.org/~shaunm/mallard";
-      type="topic"
-      id="mal_attr_external">
-
-<info>
-  <credit type="author">
-    <name>Shaun McCance</name>
-    <email>shaunm gnome org</email>
-  </credit>
-  <copyright>
-    <year>2008</year>
-    <name>Shaun McCance</name>
-  </copyright>
-
-  <version number="0.1" date="2008-02-19" status="incomplete"/>
-</info>
-
-<title>External Attributes</title>
-
-<comment>
-  <cite date="2008-12-01"><name>Shaun McCance</name></cite>
-  <p>Add content</p>
-</comment>
-
-</page>
diff --git a/doc/mallard/C/mal_attr_link.xml b/doc/mallard/C/mal_attr_link.xml
index 1e0bfe1..750bb3e 100644
--- a/doc/mallard/C/mal_attr_link.xml
+++ b/doc/mallard/C/mal_attr_link.xml
@@ -3,7 +3,7 @@
       id="mal_attr_link">
 
 <info>
-  <link type="guide" xref="mal_inline" weight="1"/>
+  <link type="seealso" xref="mal_inline"/>
 
   <credit type="author">
     <name>Shaun McCance</name>
diff --git a/doc/mallard/C/mal_block_cite.xml b/doc/mallard/C/mal_block_cite.xml
index 4cadc63..528897a 100644
--- a/doc/mallard/C/mal_block_cite.xml
+++ b/doc/mallard/C/mal_block_cite.xml
@@ -55,7 +55,7 @@ element.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>cite</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
 
     <item><p>The <code>href</code> attribute provides a URL to identify the
diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index 75c54e4..c4a78a6 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -55,7 +55,7 @@ by the user.</p>
     tools may adjust their behavior for particular MIME types.</p></item>
 
     <item><p>The <code>code</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes on block elements.</p></item>
 
     <item><p>The <code>code</code> element may also be used in an inline context.
diff --git a/doc/mallard/C/mal_block_comment.xml b/doc/mallard/C/mal_block_comment.xml
index 2b277ec..8abe7bb 100644
--- a/doc/mallard/C/mal_block_comment.xml
+++ b/doc/mallard/C/mal_block_comment.xml
@@ -57,7 +57,7 @@ to provide a <code>date</code> attribute.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>comment</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_block_example.xml b/doc/mallard/C/mal_block_example.xml
index d349b7a..0e4ab80 100644
--- a/doc/mallard/C/mal_block_example.xml
+++ b/doc/mallard/C/mal_block_example.xml
@@ -50,7 +50,7 @@ paragraphs together.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>example</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes on block elements.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_block_media.xml b/doc/mallard/C/mal_block_media.xml
index 78ee252..9f634fa 100644
--- a/doc/mallard/C/mal_block_media.xml
+++ b/doc/mallard/C/mal_block_media.xml
@@ -56,7 +56,7 @@ for details on how fallback elements are handled.</p>
     object that is being inserted.</p></item>
 
     <item><p>The <code>media</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes on block elements.</p></item>
 
     <item><p>The <code>media</code> element may also be used in an inline context.
diff --git a/doc/mallard/C/mal_block_screen.xml b/doc/mallard/C/mal_block_screen.xml
index 94aa940..4e93a3a 100644
--- a/doc/mallard/C/mal_block_screen.xml
+++ b/doc/mallard/C/mal_block_screen.xml
@@ -74,7 +74,7 @@ by the user.</p>
     </item>
 
     <item><p>The <code>screen</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes on block elements.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_block_synopsis.xml b/doc/mallard/C/mal_block_synopsis.xml
index c1b7a5d..dd11cbf 100644
--- a/doc/mallard/C/mal_block_synopsis.xml
+++ b/doc/mallard/C/mal_block_synopsis.xml
@@ -53,7 +53,7 @@ control element.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>synopsis</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes on block elements.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_external.xml b/doc/mallard/C/mal_external.xml
new file mode 100644
index 0000000..a06235c
--- /dev/null
+++ b/doc/mallard/C/mal_external.xml
@@ -0,0 +1,75 @@
+<page xmlns="http://www.gnome.org/~shaunm/mallard";
+      type="topic"
+      id="mal_external">
+
+<info>
+  <link type="seealso" xref="mal_inline"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm gnome org</email>
+  </credit>
+  <copyright>
+    <year>2008</year>
+    <name>Shaun McCance</name>
+  </copyright>
+
+  <version number="0.1" date="2008-02-19" status="incomplete"/>
+
+  <desc>Use elements and attributes from other namespaces in Mallard
+  documents.</desc>
+</info>
+
+<title>External Namespaces</title>
+
+<comment>
+  <cite date="2008-12-01"><name>Shaun McCance</name></cite>
+  <p>Add content</p>
+</comment>
+
+
+<!-- BEGIN attributes -->
+<section id="attributes">
+  <info>
+    <title type="link">External Namespace Attributes</title>
+  </info>
+  <title>Attributes</title>
+
+  <p>All elements in Mallard can have attributes from external namespaces.
+  This can be used to clarify the meaning of an element in a particular
+  context, to provide additional information to processing tools, or to
+  embed richer semantic data in a document.</p>
+
+  <p>For example, a translation tool might copy
+  <link xref="mal_block_code">code blocks</link> directly into the translated
+  document without presenting them to translators.  Some code blocks, however,
+  may contain human-readable comments which should be translated.  In order to
+  force translation tools to present these code blocks for translation, authors
+  could use the <code>its:translate</code> attribute from the
+  <link href="http://www.w3.org/TR/its/";>Internationalization Tag Set</link>,
+  as in the following:</p>
+
+  <code><![CDATA[
+<code xmlns:its="http://www.w3.org/2005/11/its"; 
+      its:version="1.0" its:translate="yes">
+// This code block should be translated because it contains this comment.
+some_code ()
+</code>
+]]></code>
+
+  <p>Processing tools should ignore any attributes from external namespaces
+  they do not understand.</p>
+</section>
+<!-- END attributes -->
+
+
+<!-- BEGIN elements -->
+<section id="elements">
+  <info>
+    <title type="link">External Namespace Elements</title>
+  </info>
+  <title>Elements</title>
+</section>
+<!-- END elements -->
+
+</page>
diff --git a/doc/mallard/C/mal_inline.xml b/doc/mallard/C/mal_inline.xml
index f7b7468..0f76d20 100644
--- a/doc/mallard/C/mal_inline.xml
+++ b/doc/mallard/C/mal_inline.xml
@@ -42,7 +42,7 @@ mal_inline = mixed {
   <link xref="mal_inline_span">mal_inline_span</link> *,
   <link xref="mal_inline_sys">mal_inline_sys</link> *,
   <link xref="mal_inline_var">mal_inline_var</link> *,
-  element * - (mal:* | local:*) { text } *
+  element * - (mal:* | local:*) { mal_inline } *
 }
 </code></synopsis>
 
@@ -56,7 +56,7 @@ well.</p>
 richer information in their documents.  While this information may not
 be conveyed by display tools, it may be used for various internal tracking
 purposes.  Mallard allows elements to be extended with attributes from
-external namespaces.  See <link xref="mal_attr_external"/> for more
+external namespaces.  See <link xref="mal_external"/> for more
 information.</p>
 
 <p>Furthermore, Mallard allows elements from external namespaces to be
@@ -88,9 +88,9 @@ more information.</p>
   descendant elements, unless explicitly overridden.</p>
 
   <p>Mallard allows elements from external namespaces to be used in any inline
-  context.  Display tools may have special behavior for particular elements they
-  understand.  Otherwise, display tools should process an unknown element as if
-  the element were replaced by its child content.</p>
+  context.  Processing tools may have special behavior for particular elements
+  they understand.  Otherwise, an unknown inline element should be processed
+  as if it were replaced by its child content.</p>
 </section>
 <!-- END processing -->
 
diff --git a/doc/mallard/C/mal_inline_app.xml b/doc/mallard/C/mal_inline_app.xml
index b0b6fbe..efa8a60 100644
--- a/doc/mallard/C/mal_inline_app.xml
+++ b/doc/mallard/C/mal_inline_app.xml
@@ -61,7 +61,7 @@ use <code xref="mal_inline_cmd">cmd</code> for this purpose instead.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>app</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_cmd.xml b/doc/mallard/C/mal_inline_cmd.xml
index 41537c4..b0833e7 100644
--- a/doc/mallard/C/mal_inline_cmd.xml
+++ b/doc/mallard/C/mal_inline_cmd.xml
@@ -87,7 +87,7 @@ by the user.</p>
     </item>
 
     <item><p>The <code>cmd</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_code.xml b/doc/mallard/C/mal_inline_code.xml
index 189011a..d9659d3 100644
--- a/doc/mallard/C/mal_inline_code.xml
+++ b/doc/mallard/C/mal_inline_code.xml
@@ -72,7 +72,7 @@ by the user.</p>
     tools may adjust their behavior for particular MIME types.</p></item>
 
     <item><p>The <code>code</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
 
     <item><p>The <code>code</code> element may also be used in a block context.
diff --git a/doc/mallard/C/mal_inline_em.xml b/doc/mallard/C/mal_inline_em.xml
index 506796e..e2bb822 100644
--- a/doc/mallard/C/mal_inline_em.xml
+++ b/doc/mallard/C/mal_inline_em.xml
@@ -58,7 +58,7 @@ display tools.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>em</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_file.xml b/doc/mallard/C/mal_inline_file.xml
index f8e5308..92ccac2 100644
--- a/doc/mallard/C/mal_inline_file.xml
+++ b/doc/mallard/C/mal_inline_file.xml
@@ -57,7 +57,7 @@ filenames, such as search paths and file extensions.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>file</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_gui.xml b/doc/mallard/C/mal_inline_gui.xml
index 205f165..f1e7ff2 100644
--- a/doc/mallard/C/mal_inline_gui.xml
+++ b/doc/mallard/C/mal_inline_gui.xml
@@ -99,7 +99,7 @@ control is being marked up.</p>
     </table></item>
 
     <item><p>The <code>gui</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_guiseq.xml b/doc/mallard/C/mal_inline_guiseq.xml
index 78d9da4..a85f036 100644
--- a/doc/mallard/C/mal_inline_guiseq.xml
+++ b/doc/mallard/C/mal_inline_guiseq.xml
@@ -54,7 +54,7 @@ items.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>guiseq</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml
index 1a91d77..1165e6c 100644
--- a/doc/mallard/C/mal_inline_input.xml
+++ b/doc/mallard/C/mal_inline_input.xml
@@ -58,7 +58,7 @@ or into a text field in a graphical application.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>input</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
 
     <item><p>The <code>input</code> element, together with the
diff --git a/doc/mallard/C/mal_inline_key.xml b/doc/mallard/C/mal_inline_key.xml
index e79ff19..391357d 100644
--- a/doc/mallard/C/mal_inline_key.xml
+++ b/doc/mallard/C/mal_inline_key.xml
@@ -65,7 +65,7 @@ these instead.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>key</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_keyseq.xml b/doc/mallard/C/mal_inline_keyseq.xml
index bc053c0..e977909 100644
--- a/doc/mallard/C/mal_inline_keyseq.xml
+++ b/doc/mallard/C/mal_inline_keyseq.xml
@@ -64,7 +64,7 @@ key press.  You can use text without markup to indicate a class of keys, such as
     The default is <code>"combo"</code>.</p></item>
 
     <item><p>The <code>keyseq</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_link.xml b/doc/mallard/C/mal_inline_link.xml
index 478fe0c..257bbcc 100644
--- a/doc/mallard/C/mal_inline_link.xml
+++ b/doc/mallard/C/mal_inline_link.xml
@@ -61,7 +61,7 @@ mal_inline_link = element link {
     those style hints they understand.</p></item>
 
     <item><p>The <code>link</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_media.xml b/doc/mallard/C/mal_inline_media.xml
index 1b10547..3b1da7b 100644
--- a/doc/mallard/C/mal_inline_media.xml
+++ b/doc/mallard/C/mal_inline_media.xml
@@ -58,7 +58,7 @@ for details on how fallback elements are handled.</p>
     object that is being inserted.</p></item>
 
     <item><p>The <code>media</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
 
     <item><p>The <code>media</code> element may also be used in a block context.
diff --git a/doc/mallard/C/mal_inline_output.xml b/doc/mallard/C/mal_inline_output.xml
index 569e5d8..0e08ad6 100644
--- a/doc/mallard/C/mal_inline_output.xml
+++ b/doc/mallard/C/mal_inline_output.xml
@@ -79,7 +79,7 @@ differently.</p>
     </item>
 
     <item><p>The <code>output</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
 
     <item><p>The <code>output</code> element, together with the
diff --git a/doc/mallard/C/mal_inline_quote.xml b/doc/mallard/C/mal_inline_quote.xml
index f28e191..02396f5 100644
--- a/doc/mallard/C/mal_inline_quote.xml
+++ b/doc/mallard/C/mal_inline_quote.xml
@@ -60,7 +60,7 @@ mal_inline_quote = element quote {
     those style hints they understand.</p></item>
 
     <item><p>The <code>quote</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_span.xml b/doc/mallard/C/mal_inline_span.xml
index 0d1745b..5ad4a32 100644
--- a/doc/mallard/C/mal_inline_span.xml
+++ b/doc/mallard/C/mal_inline_span.xml
@@ -46,7 +46,7 @@ mal_inline_span = element span {
     those style hints they understand.</p></item>
 
     <item><p>The <code>span</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_sys.xml b/doc/mallard/C/mal_inline_sys.xml
index df0bd9f..3eea0f8 100644
--- a/doc/mallard/C/mal_inline_sys.xml
+++ b/doc/mallard/C/mal_inline_sys.xml
@@ -44,7 +44,7 @@ mal_inline_sys = element sys {
     those style hints they understand.</p></item>
 
     <item><p>The <code>sys</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
   </list>
 </section>
diff --git a/doc/mallard/C/mal_inline_var.xml b/doc/mallard/C/mal_inline_var.xml
index fd22eb9..19216d0 100644
--- a/doc/mallard/C/mal_inline_var.xml
+++ b/doc/mallard/C/mal_inline_var.xml
@@ -52,7 +52,7 @@ an indicated argument.</p>
     those style hints they understand.</p></item>
 
     <item><p>The <code>var</code> element can have attributes from external
-    namespaces.  See <link xref="mal_attr_external"/> for more information
+    namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
 
     <item><p>See <link xref="mal_inline_cmd"/> and <link xref="mal_inline_code"/>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]