[gnome-doc-utils/mallard] [mallard] Finishing up some inline elements: input, sys, span

[Shaun McCance <shaunm src gnome org>]

commit d1ca9f057261dc155e628b4af86a397b7cea0c17
Author: Shaun McCance <shaunm gnome org>
Date:   Wed May 13 16:17:09 2009 -0500

    [mallard] Finishing up some inline elements: input, sys, span
---
 doc/mallard/C/mal_inline_input.xml |   28 +++++++++++++++--
 doc/mallard/C/mal_inline_span.xml  |   57 +++++++++++++++++++++++++++++++++++-
 doc/mallard/C/mal_inline_sys.xml   |   31 +++++++++++++++++--
 3 files changed, 108 insertions(+), 8 deletions(-)

diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml
index 1165e6c..1b49bdc 100644
--- a/doc/mallard/C/mal_inline_input.xml
+++ b/doc/mallard/C/mal_inline_input.xml
@@ -11,11 +11,11 @@
     <email>shaunm gnome org</email>
   </credit>
   <copyright>
-    <year>2008</year>
+    <year>2008-2009</year>
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-12-16" status="incomplete"/>
+  <version number="0.1" date="2009-06-13" status="review"/>
 
   <desc>Mark up text the user should input into a computer program.</desc>
 </info>
@@ -74,8 +74,28 @@ or into a text field in a graphical application.</p>
 <section id="examples">
   <title>Examples</title>
 
-  <comment><cite date="2008-12-16"><name>Shaun McCance</name></cite>
-  <p>Add examples</p></comment>
+  <p>Use <code>input</code> to mark up a user response to a prompt:</p>
+
+  <example>
+    <code><![CDATA[Type <input>Y</input> at the prompt to proceed.]]></code>
+    <p>Type <input>Y</input> at the prompt to proceed.</p>
+  </example>
+
+  <p>Use <code>input</code> and <code xref="mal_inline_output">output</code>
+  inside a <code xref="mal_block_screen">screen</code> element:</p>
+
+  <example>
+    <code><![CDATA[
+<screen>
+<output style="prompt">$ </output><input>ls mal_inline_output.xml</input>
+<output>mal_inline_output.xml</output>
+</screen>
+]]></code>
+<screen>
+<output style="prompt">$ </output><input>ls mal_inline_output.xml</input>
+<output>mal_inline_output.xml</output>
+</screen>
+  </example>
 </section>
 <!-- END examples -->
 
diff --git a/doc/mallard/C/mal_inline_span.xml b/doc/mallard/C/mal_inline_span.xml
index 5ad4a32..5749c6b 100644
--- a/doc/mallard/C/mal_inline_span.xml
+++ b/doc/mallard/C/mal_inline_span.xml
@@ -6,7 +6,18 @@
   <link type="guide" xref="mal_inline#elements"/>
   <link type="seealso" xref="mal_attr_link"/>
 
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <version number="0.1" date="2009-05-13" status="review"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm gnome org</email>
+  </credit>
+  <copyright>
+    <year>2007-2009</year>
+    <name>Shaun McCance</name>
+  </copyright>
+
+  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
 
   <desc>A generic inline element that can be used for semantic,
   localization, and styling purpose.</desc>
@@ -24,6 +35,11 @@ mal_inline_span = element span {
 }
 </code></synopsis>
 
+<p>Use the <code>span</code> element to surround a run of text
+without using any of the semantic <link xref="mal_inline">inline
+elements</link>.  This is frequently necessary for extensions
+using attributes from external namespaces.</p>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -52,4 +68,43 @@ mal_inline_span = element span {
 </section>
 <!-- END notes -->
 
+
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Use <code>span</code> with an external-namespace attribute to mark a word
+  as untranslatable using the
+  <link href="http://www.w3.org/TR/its/";>Internationalization Tag Set</link>:</p>
+
+  <example>
+    <code><![CDATA[
+This <phrase its:translate="no">word</phrase> should not be translated.]]></code>
+    <p>This <phrase xmlns:its="http://www.w3.org/2005/11/its"; its:version="1.0"
+    its:translate="no">word</phrase> should not be translated.</p>
+  </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>No particular special rendering is required for <code>span</code> elements.
+  Processing tools may have special processing rules for certain style hints or
+  external-namespace attributes.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+  <p>The <code>span</code> element is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/phrase.html";>phrase</code>
+  element in DocBook.</p>
+</section>
+<!-- END comparison -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_sys.xml b/doc/mallard/C/mal_inline_sys.xml
index 3eea0f8..3dbb736 100644
--- a/doc/mallard/C/mal_inline_sys.xml
+++ b/doc/mallard/C/mal_inline_sys.xml
@@ -5,7 +5,16 @@
 <info>
   <link type="guide" xref="mal_inline#elements"/>
 
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm gnome org</email>
+  </credit>
+  <copyright>
+    <year>2008-2009</year>
+    <name>Shaun McCance</name>
+  </copyright>
+
+  <version number="0.1" date="2009-05-13" status="review"/>
 
   <desc>Mark up general identifiers found on computer systems.</desc>
 </info>
@@ -22,6 +31,11 @@ mal_inline_sys = element sys {
 }
 </code></synopsis>
 
+<p>Use the <code>sys</code> element to mark up any type of system item that
+isn't covered by other elements such as <code xref="mal_inline_file">file</code>,
+<code xref="mal_inline_cmd">cmd</code>, or
+<code xref="mal_inline_code">code</code>.</p>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -54,6 +68,13 @@ mal_inline_sys = element sys {
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
+
+  <p>Use <code>sys</code> to mark up a domain name:</p>
+
+  <example>
+    <code><![CDATA[The Linux kernel is hosted on <sys>git.kernel.org</sys>.]]></code>
+    <p>The Linux kernel is hosted on <sys>git.kernel.org</sys>.</p>
+  </example>
 </section>
 <!-- END examples -->
 
@@ -61,6 +82,12 @@ mal_inline_sys = element sys {
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
+
+  <p>System items are displayed in a fixed-width font.  Fixed-width fonts
+  tend to have more distinction between visually similar characters. This
+  is particularly important in system items, since letters often appear
+  without the context of a known word that helps make them discernable in
+  normal prose.</p>
 </section>
 <!-- END processing -->
 
@@ -75,8 +102,6 @@ mal_inline_sys = element sys {
   element.  Since Mallard does not provide the level of markup specificity
   that DocBook does, the <code>sys</code> element should be used in place
   of these and various other elements.</p>
-
-  <p>See <link xref="principle-justenough"/> for more background.</p>
 </section>
 <!-- END comparison -->