GNOME.org
 

[gnome-doc-utils/mallard: 78/87] Adding more content for inline elements

commit cc377e18607365f3edbf045af57b99786181238d
Author: Shaun McCance <shaunm gnome org>
Date:   Tue Dec 16 18:35:22 2008 -0600

    Adding more content for inline elements
---
 doc/mallard/C/mal_inline_em.xml       |   24 ++++++++--
 doc/mallard/C/mal_inline_gui.xml      |   79 ++++++++++++++++++++++++++++++--
 doc/mallard/C/mal_inline_guiseq.xml   |   34 ++++++++++++++-
 doc/mallard/C/mal_inline_input.xml    |   28 ++++++++++-
 doc/mallard/C/mal_inline_key.xml      |   65 ++++++++++++++++++++++++++-
 doc/mallard/C/mal_inline_output.xml   |   12 ++++-
 xslt/mallard/html/mal2html-inline.xsl |   45 +++++++++++++++++-
 7 files changed, 267 insertions(+), 20 deletions(-)

diff --git a/doc/mallard/C/mal_inline_em.xml b/doc/mallard/C/mal_inline_em.xml
index d0df6f0..3eaa5e1 100644
--- a/doc/mallard/C/mal_inline_em.xml
+++ b/doc/mallard/C/mal_inline_em.xml
@@ -14,7 +14,7 @@
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-02-19" status="incomplete"/>
+  <version number="0.1" date="2008-12-16" status="review"/>
 
   <desc>Emphasize important text.</desc>
 </info>
@@ -59,10 +59,24 @@ processing tools.</p>
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
-  <comment>
-    <cite date="2008-02-19"><name>Shaun McCance</name></cite>
-    <p>Add examples.</p>
-  </comment>
+
+  <p>Use <code>em</code> to stress a word in a sentence:</p>
+
+  <example>
+    <code><![CDATA[
+You should <em>never</em> run a graphical application as root.
+]]></code>
+    <p>You should <em>never</em> run a graphical application as root.</p>
+  </example>
+
+  <p>Use <code>em</code> to mark the first occurance of a term:</p>
+
+  <example>
+    <code><![CDATA[
+Note that <em>accelerators</em> are different from <em>mnemonics</em>.
+]]></code>
+    <p>Note that <em>accelerators</em> are different from <em>mnemonics</em>.</p>
+  </example>
 </section>
 <!-- END examples -->
 
diff --git a/doc/mallard/C/mal_inline_gui.xml b/doc/mallard/C/mal_inline_gui.xml
index c3e4a08..5d794c2 100644
--- a/doc/mallard/C/mal_inline_gui.xml
+++ b/doc/mallard/C/mal_inline_gui.xml
@@ -14,7 +14,7 @@
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-02-19" status="incomplete"/>
+  <version number="0.1" date="2008-12-16" status="review"/>
 
   <desc>Mark up control labels from a graphical user interface.</desc>
 </info>
@@ -31,6 +31,12 @@ mal_inline_gui = element gui {
 }
 </code></synopsis>
 
+<p>Use the <code>gui</code> element to mark up the label of a control in
+a graphical user interface.  You can use <code>gui</code> for all sorts
+of controls, including buttons, check boxes, and menu items.  If necessary,
+you can use the <code>style</code> attribute to indicate what kind of
+control is being marked up.</p>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -40,6 +46,42 @@ mal_inline_gui = element gui {
     style hints.  Processing tools should adjust their rendering according to
     those style hints they understand.</p></item>
 
+    <item><p>Typical style hints include:</p>
+    <table>
+      <tr>
+        <td><p><code>button</code></p></td>
+        <td><p>The text of a button</p></td>
+      </tr>
+      <tr>
+        <td><p><code>checkbox</code></p></td>
+        <td><p>The label for a check box</p></td>
+      </tr>
+      <tr>
+        <td><p><code>group</code></p></td>
+        <td><p>The label for a group of controls</p></td>
+      </tr>
+      <tr>
+        <td><p><code>input</code></p></td>
+        <td><p>The label for any text entry control</p></td>
+      </tr>
+      <tr>
+        <td><p><code>menu</code></p></td>
+        <td><p>The name of a menu</p></td>
+      </tr>
+      <tr>
+        <td><p><code>menuitem</code></p></td>
+        <td><p>The name of an item in a menu</p></td>
+      </tr>
+      <tr>
+        <td><p><code>radiobutton</code></p></td>
+        <td><p>The label for a radio button</p></td>
+      </tr>
+      <tr>
+        <td><p><code>tab</code></p></td>
+        <td><p>The label on a tab</p></td>
+      </tr>
+    </table></item>
+
     <item><p>The <code>gui</code> element can link to other pages or documents.
     See <link xref="mal_attr_link"/> for more information.</p></item>
 
@@ -54,6 +96,27 @@ mal_inline_gui = element gui {
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
+
+  <p>Use <code>gui</code> to mark up the text of a button:</p>
+
+  <example>
+    <code><![CDATA[
+Click the <gui>Close</gui> button to close the window.
+]]></code>
+    <p>Click the <gui>Close</gui> button to close the window.</p>
+  </example>
+
+  <p>Use <code>gui</code> to mark up the label on a tab:</p>
+
+  <example>
+    <code><![CDATA[
+The <gui>Filters</gui> tab contains options to change the behavior
+of your keyboard to meet certain accessibility needs.
+]]></code>
+    <p>The <gui>Filters</gui> tab contains options to change the behavior
+    of your keyboard to meet certain accessibility needs.</p>
+  </example>
+
 </section>
 <!-- END examples -->
 
@@ -61,10 +124,16 @@ mal_inline_gui = element gui {
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
-  <comment>
-    <cite date="2008-11-09"><name>Shaun McCance</name></cite>
-    <p>Add processing expectations.</p>
-  </comment>
+
+  <p>No particular special rendering is required for <code>gui</code> elements.
+  Processing tools may use subtle effects such as lightened text to distinguish
+  interface labels elements from the surrounding text.</p>
+
+  <p>In certain environments, processing tools may decorate interface labels
+  with an icon or other effect based on the <code>style</code> attribute.
+  For example, in a table of options where the first element of each row is
+  a <code>gui</code> element, those with the <code>checkbox</code> style
+  hint could be decorated with a check box icon.</p>
 </section>
 <!-- END processing -->
 
diff --git a/doc/mallard/C/mal_inline_guiseq.xml b/doc/mallard/C/mal_inline_guiseq.xml
index 9fa7ce0..c76a30a 100644
--- a/doc/mallard/C/mal_inline_guiseq.xml
+++ b/doc/mallard/C/mal_inline_guiseq.xml
@@ -15,7 +15,7 @@
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-02-19" status="incomplete"/>
+  <version number="0.1" date="2008-12-16" status="review"/>
 
   <desc>Mark up a sequence of interface controls to navigate.</desc>
 </info>
@@ -52,6 +52,38 @@ items.</p>
 <!-- END notes -->
 
 
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Use <code>guiseq</code> to mark up a sequence of menu items:</p>
+
+  <example>
+    <code><![CDATA[
+Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open
+a new document.
+]]></code>
+    <p>Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open
+    a new document.</p>
+  </example>
+
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>Display tools should show each of the child <code>gui</code> elements as
+  normal, adding a separator between them.  The exact separator may vary according
+  to the language and style preferences, but it will typically be some sort of
+  right-pointing arrow or triangle, or left-pointing for right-to-left
+  languages.</p>
+</section>
+<!-- END processing -->
+
+
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml
index 57b80f0..7e94c06 100644
--- a/doc/mallard/C/mal_inline_input.xml
+++ b/doc/mallard/C/mal_inline_input.xml
@@ -15,7 +15,7 @@
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-02-19" status="stub"/>
+  <version number="0.1" date="2008-12-16" status="incomplete"/>
 
   <desc>Mark up text the user should input into a computer program.</desc>
 </info>
@@ -32,8 +32,9 @@ mal_inline_input = element input {
 }
 </code></synopsis>
 
-<comment><cite date="2008-12-12"><name>Shaun McCance</name></cite>
-<p>Add intro text</p></comment>
+<p>Use the <code>input</code> element to mark up text that is input b
+the user.  This may be text entered into a command-line environment
+or into a text field in a graphical application.</p>
 
 
 <!-- BEGIN notes -->
@@ -60,6 +61,27 @@ mal_inline_input = element input {
 <!-- END notes -->
 
 
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <comment><cite date="2008-12-16"><name>Shaun McCance</name></cite>
+  <p>Add examples</p></comment>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>User input should be displayed in a fixed-width or wide font.  Fixed-width
+  fonts tend to have more distinction between visually similar characters.
+  Processing tools may use a background color or border to make the beginning
+  and end of the intut clear.</p>
+</section>
+
+
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
diff --git a/doc/mallard/C/mal_inline_key.xml b/doc/mallard/C/mal_inline_key.xml
index def3800..4c691b2 100644
--- a/doc/mallard/C/mal_inline_key.xml
+++ b/doc/mallard/C/mal_inline_key.xml
@@ -5,7 +5,7 @@
 <info>
   <link type="guide" xref="mal_inline#elements"/>
 
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <version number="0.1" date="2008-12-16" status="review"/>
 
   <desc>Mark up a key to be pressed on the user's keyboard.</desc>
 </info>
@@ -22,6 +22,23 @@ mal_inline_key = element key {
 }
 </code></synopsis>
 
+<p>Use the <code>key</code> element to mark up a key on the keyboard.
+You can use this for letter keys, such as <key>Q</key>, or for keys
+with names, such as <key>Ctrl</key>.  Generally, the contents of the
+<code>key</code> element should be what is printed on the physical
+key, although it may be a textual description for keys with symbols
+printed on them.</p>
+
+<p>Do not use <code>key</code> to mark up a class of keys, such as
+<em>arrow keys</em>.  These do not require markup in running prose.
+Inside a <code xref="mal_inline_keyseq">keyseq</code> element, you
+are allowed to use text without a <code>key</code> element exactly
+for this purpose.</p>
+
+<p>Do not use <code>key</code> to mark up a symbolic key code or a numeric
+key value; if necesarry, use <code xref="mal_inline_sys">sys</code> for
+these instead.</p>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -42,6 +59,52 @@ mal_inline_key = element key {
 <!-- END notes -->
 
 
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+
+  <p>Use <code>key</code> to mark up a letter key:</p>
+
+  <example>
+    <code><![CDATA[
+Press <key>M</key> to mark the selected message as read.
+]]></code>
+    <p>Press <key>M</key> to mark the selected message as read.</p>
+  </example>
+
+  <p>Use <code>key</code> to mark up a function key:</p>
+
+  <example>
+    <code><![CDATA[
+Press <key>F9</key> to check for new messages.
+]]></code>
+    <p>Press <key>F9</key> to check for new messages.</p>
+  </example>
+
+  <p>Use <code>key</code> to refer to a specific key by a
+  textual description:</p>
+
+  <example>
+    <code><![CDATA[
+Press the <key>Down</key> key to select the next item.
+]]></code>
+    <p>Press the <key>Down</key> key to select the next item.</p>
+  </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>No particular special rendering is required for <code>key</code> elements.
+  Processing tools may use subtle effects such as lightened text or borders to
+  distinguish interface keys from the surrounding text.</p>
+</section>
+<!-- END processing -->
+
+
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
diff --git a/doc/mallard/C/mal_inline_output.xml b/doc/mallard/C/mal_inline_output.xml
index 6c2e3d4..bdb1f2e 100644
--- a/doc/mallard/C/mal_inline_output.xml
+++ b/doc/mallard/C/mal_inline_output.xml
@@ -14,7 +14,7 @@
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-02-19" status="stub"/>
+  <version number="0.1" date="2008-12-16" status="incomplete"/>
 
   <desc>Mark up the output from a computer program.</desc>
 </info>
@@ -31,6 +31,10 @@ mal_inline_output = element output {
 }
 </code></synopsis>
 
+<comment><cite date="2008-12-16"><name>shaunm</name></cite>
+<p>This is marked incomplete because the example with screen is
+not yet rendered correctly.  The content is finished.</p></comment>
+
 <p>Use the <code>output</code> element to mark up text that is output
 by a computer program.  Typically, this is text output in a command-line
 environment, although you may use the <code>output</code> element for
@@ -134,7 +138,11 @@ if you use the Bourne-again shell.
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
-  <comment><cite date="2008-12-15"><name>shaunm</name></cite><p>Add processing expectations</p></comment>
+
+  <p>Computer output should be displayed in a fixed-width or wide font.
+  Fixed-width fonts tend to have more distinction between visually similar
+  characters.  Processing tools may use a background color or border to
+  make the beginning and end of the ouptut clear.</p>
 </section>
 
 
diff --git a/xslt/mallard/html/mal2html-inline.xsl b/xslt/mallard/html/mal2html-inline.xsl
index 61beefc..644e441 100644
--- a/xslt/mallard/html/mal2html-inline.xsl
+++ b/xslt/mallard/html/mal2html-inline.xsl
@@ -106,9 +106,33 @@ span.code { font-family: monospace; }
 span.em { font-style: italic; }
 span.email { color: red; }
 span.file { font-family: monospace; }
-span.gui { color: red; }
+span.gui, span.guiseq { color: </xsl:text>
+  <xsl:call-template name="theme.get_color">
+    <xsl:with-param name="id" select="'text-light'"/>
+  </xsl:call-template>
+  <xsl:text>;
+}
 span.input { font-family: monospace; }
-span.key { /* FIXME */ }
+span.key {
+  color: </xsl:text>
+  <xsl:call-template name="theme.get_color">
+    <xsl:with-param name="id" select="'text-light'"/>
+  </xsl:call-template>
+  <xsl:text>;
+  border: solid 1px </xsl:text>
+  <xsl:call-template name="theme.get_color">
+    <xsl:with-param name="id" select="'gray-border'"/>
+  </xsl:call-template>
+  <xsl:text>;
+  padding: 0 0.2em 0 0.2em;
+}
+span.keyseq {
+  color: </xsl:text>
+  <xsl:call-template name="theme.get_color">
+    <xsl:with-param name="id" select="'text-light'"/>
+  </xsl:call-template>
+  <xsl:text>;
+}
 span.output { font-family: monospace; }
 span.sys { font-family: monospace; }
 span.var { font-style: italic; }
@@ -155,10 +179,25 @@ span.var { font-style: italic; }
 
 <!-- = gui = -->
 <xsl:template mode="mal2html.inline.mode" match="mal:gui">
-  <!-- FIXME: menu -->
   <xsl:call-template name="mal2html.span"/>
 </xsl:template>
 
+<!-- = guiseq = -->
+<xsl:template mode="mal2html.inline.mode" match="mal:guiseq">
+  <xsl:call-template name="mal2html.span"/>
+</xsl:template>
+
+<!-- = guiseq % mal2html.inline.content.mode = -->
+<xsl:template mode="mal2html.inline.content.mode" match="mal:guiseq">
+  <xsl:for-each select="mal:gui">
+    <xsl:if test="position() != 1">
+      <!-- FIXME: rtl -->
+      <xsl:text>&#x00A0;&#x25B8; </xsl:text>
+    </xsl:if>
+    <xsl:apply-templates mode="mal2html.inline.mode" select="."/>
+  </xsl:for-each>
+</xsl:template>
+
 <!-- = input = -->
 <xsl:template mode="mal2html.inline.mode" match="mal:input">
   <xsl:call-template name="mal2html.span"/>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]