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
178
179
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_inline_cmd">
<info>
<link type="guide" xref="mal_inline#elements"/>
<link type="seealso" xref="mal_block_screen"/>
<version number="0.1" date="2008-12-01" 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 command to be entered at an interactive shell.</desc>
</info>
<title>Commands</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_cmd = element cmd {
<link xref="mal_attr_link">mal_attr_link</link> ?,
attribute style { xsd:NMTOKENS } ?,
attribute mime { text } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_inline">mal_inline</link>
}
</code></synopsis>
<p>Use the <code>cmd</code> element to mark up a command or a portion of a
command to run in an interactive shell. It is frequently used to mark up
the command to run an application. Do not use the <code>cmd</code> element
to mark up the human-readable name of an application; use
<code xref="mal_inline_app">app</code> for this purpose instead.</p>
<p>You may use the <code>cmd</code> element to mark up the entire command,
including all arguments. Mallard does not contain elements to mark up the
arguments specifically, as there is rarely a need to distinguish them.
You may also use the <code>cmd</code> element to mark up parts of a command,
such as options and arguments, when these need to be referenced alone.</p>
<p>Use the <code xref="mal_inline_var">var</code> element inside a
<code>cmd</code> element to indicate text that should be replaced
by the user.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<ulist>
<item><p>The <code>cmd</code> element can contain a mixture of text and
any <link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>cmd</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>cmd</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>mime</code> attribute takes a valid MIME type. Processing
tools may adjust their behavior for particular MIME types.</p></item>
<item>
<p>Typical values for the <code>mime</code> attribute include:</p>
<table><tr>
<td><p><code>application/x-sh</code></p></td>
<td>Command to execute with the Bourne shell</td>
</tr><tr>
<td><p><code>application/x-csh</code></p></td>
<td>Command to execute with the C shell</td>
</tr></table>
</item>
<item><p>The <code>cmd</code> element can have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes.</p></item>
</ulist>
</section>
<!-- END notes -->
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
<p>Use <code>cmd</code> to mark up a simple command to run:</p>
<example>
<code><![CDATA[
To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at
the command line.
]]></code>
<p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at the
command line.</p>
</example>
<p>Use <code>cmd</code> with <code xref="mal_inline_var">var</code> to mark
up a command with a placeholder for an argument the user should supply:</p>
<example>
<code><![CDATA[
To view a file in <app>Totem Movie Player</app>, enter <cmd>totem
<var>file</var></cmd> at the command line, replacing <var>file</var>
with the name of the file.
]]></code>
<p>To view a file in <app>Totem Movie Player</app>, enter <cmd>totem <var>file</var></cmd>
at the command line, replacing <var>file</var> with the name of the file.</p>
</example>
<p>Use <code>cmd</code> to mark up command names and options:</p>
<example>
<code><![CDATA[
The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows
you to filter files based on their modification times.
]]></code>
<p>The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows you to
filter files based on their modification times.</p>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Commands are displayed in a fixed-width font. This mimics the look
of a typical environment where commands are executed. More importantly,
fixed-width fonts tend to have more distinction between visually similar
characters. This is particularly important in commands, since letters often
appear without the context of a known word that helps make them discernable
in normal prose.</p>
<p>Commands in documentation are often provided with options to illustrate
how to use them to a particular effect. This can make it difficult to find
the end of the command quickly. Surrounding text content, especially
punctuation, can sometimes be confused for part of the command. For this
reason, it is recommended that commands be displayed with a border or
background color.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>cmd</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/command.html">command</code>
element in DocBook. In DocBook, writers frequently use the
<code href="http://www.docbook.org/tdg/en/html/option.html">option</code>
element inside <code>command</code>. Mallard does not provide an element
for this purpose.</p>
<p>In DocBook, the <code>option</code> element is also used outside the
<code>command</code> element. In Mallard, simply use the <code>cmd</code>
element for options outside of an entire command.</p>
<p>See <link xref="principle-justenough"/> for more background.</p>
</section>
<!-- END comparison -->
</page>
|
