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
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_inline_key">
<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>2007-2009</year>
<name>Shaun McCance</name>
</copyright>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Mark up a key to be pressed on the user's keyboard.</desc>
</info>
<title>Key Strokes</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_key = element key {
<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>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">
<title>Notes</title>
<list>
<item><p>The <code>key</code> element can contain a mixture of text and
any <link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>key</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>key</code> element can also occur inside the
<code xref="mal_inline_keyseq">keyseq</code> element, where it has
special meaning.</p></item>
<item><p>The <code>key</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>The <code>key</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>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.
Keys may be rendered with lightened text or other sublte styling effects to
distinguish them from the surrounding text.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>key</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/keycap.html">keycap</code>
element in DocBook. Mallard does not provide elements analogous to the
DocBook elements
<code href="http://www.docbook.org/tdg/en/html/keysym.html">keysym</code> and
<code href="http://www.docbook.org/tdg/en/html/keycode.html">keycode</code>.
In most cases, these should be marked simply with the
<code xref="mal_inline_sys">sys</code> element.</p>
</section>
<!-- END comparison -->
</page>
|
