diff options
author | Shaun McCance <shaunm@gnome.org> | 2008-12-16 18:35:22 -0600 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2009-04-19 11:13:32 -0500 |
commit | cc377e18607365f3edbf045af57b99786181238d (patch) | |
tree | 6d0846e68f044e5f2763bab2600b9d10d00299b9 | |
parent | 71d44d934a03ddcff9084e4a6f63557baf9c43b9 (diff) | |
download | gnome-doc-utils-cc377e18607365f3edbf045af57b99786181238d.tar.gz |
Adding more content for inline elements
-rw-r--r-- | doc/mallard/C/mal_inline_em.xml | 24 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_gui.xml | 79 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_guiseq.xml | 34 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_input.xml | 28 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_key.xml | 65 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_output.xml | 12 | ||||
-rw-r--r-- | 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> ▸ </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"/> |