1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_inline_gui">
<info>
<link type="guide" xref="mal_inline#elements"/>
<version number="0.1" date="2008-12-16" status="review"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
</credit>
<copyright>
<year>2008-2009</year>
<name>Shaun McCance</name>
</copyright>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Mark up control labels from a graphical user interface.</desc>
</info>
<title>GUI Labels</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_gui = element gui {
<link xref="mal_attr_link">mal_attr_link</link> ?,
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_inline">mal_inline</link>
}
</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">
<title>Notes</title>
<list type="bullet">
<item><p>The <code>gui</code> element can contain a mixture of text and
any <link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>gui</code> element can occur in any
general inline context, including inside most
<link xref="mal_inline">inline elements</link>, some
<link xref="mal_block#basic">basic block elements</link>, and certain
<link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>gui</code> element can also occur inside the
<code xref="mal_inline_guiseq">guiseq</code> element, where it has
special meaning.</p></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>
<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>
<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 have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
<!-- 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 -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>No particular special rendering is required for <code>gui</code> elements.
Interface labels may be rendered with lightened text or other sublte styling
effects to distinguish them from the surrounding text.</p>
<p>In certain environments, interface labels may be decorated 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 -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>gui</code> element is similar to the deprecated
<code href="http://www.docbook.org/tdg/en/html/interface.html">interface</code>
element in DocBook. DocBook 3 introduced more specific elements for marking up
parts of a user interface:
<code href="http://www.docbook.org/tdg/en/html/guibutton.html">guibutton</code>,
<code href="http://www.docbook.org/tdg/en/html/guiicon.html">guiicon</code>,
<code href="http://www.docbook.org/tdg/en/html/guilabel.html">guilabel</code>,
<code href="http://www.docbook.org/tdg/en/html/guimenu.html">guimenu</code>,
<code href="http://www.docbook.org/tdg/en/html/guimenuitem.html">guimenuitem</code>, and
<code href="http://www.docbook.org/tdg/en/html/guisubmenu.html">guisubmenu</code>.
In practice, there is rarely a need to distinguish between types of interface
elements in markup. When such a need arises, it can be handled using attributes
on a single element. Furthermore, DocBook's various elements are nowhere near
exhaustive. Thus, authors must frequently either abuse a specific element or
use the deprecated <code>interface</code> element.</p>
</section>
<!-- END comparison -->
</page>
|
