Fixed typos in mal_inline_output and code tutorial
[projectmallard:projectmallard.git] / about / learn / code.page
1 <page xmlns="http://projectmallard.org/1.0/"
2       type="topic"
3       id="code">
4
5 <info>
6   <link type="guide" xref="index"/>
7
8   <credit type="author">
9     <name>Shaun McCance</name>
10     <email>shaunm@gnome.org</email>
11     <years>2010</years>
12   </credit>
13
14   <desc>Add code snippets, file contents, and command lines to your
15   Mallard document.</desc>
16 </info>
17
18 <title>Code and Commands</title>
19
20 <note style="pmo-source">
21 <title>Learn by Example</title>
22 <p>This page was written in a Mallard extension format called Mallard Sites.
23 <link xref="code-src">Read the source markup</link> for this page to
24 learn Mallard from real-world examples.</p>
25 </note>
26
27 <p>In technical documentation, you often need to write commands, code
28 snippets, or file contents.  Mallard provides elements that help you do
29 this with a consistent style, helping your readers easily identify information
30 they need.  In this tutorial, you will learn how to write inline code and
31 commands, create code blocks and command-line sessions, and provide a title
32 for your code blocks.</p>
33
34 <section id="inline">
35 <title>Inline Code and Commands</title>
36
37 <p>You can use the <code xref="/1.0/mal_inline_code">code</code>
38 element inside a paragraph to mark up a snippet of code.  You will typically
39 use <code>code</code> as an inline element to refer to something short like a
40 function name or variable.</p>
41
42 <example>
43 <code><![CDATA[
44 <p>Call the <code>bean_grow</code> function to grow your magic beans.</p>
45 ]]></code>
46 <p>Call the <code>bean_grow</code> function to grow your magic beans.</p>
47 </example>
48
49 <p>You can use the <code>code</code> element for more than programming languages.
50 Use the <code>code</code> element to mark up the name of an XML element,
51 a key in a configuration file, or anything else you might find in a file
52 you would edit in a text editor.</p>
53
54 <example>
55 <code><![CDATA[
56 <p>Use the <code>code</code> element to mark up the name of an XML element.</p>
57 ]]></code>
58 <p>Use the <code>code</code> element to mark up the name of an XML element.</p>
59 </example>
60
61 <example>
62 <code><![CDATA[
63 <p>Set the <code>Name</code> key to the name of your application.</p>
64 ]]></code>
65 <p>Set the <code>Name</code> key to the name of your application.</p>
66 </example>
67
68 <p>Use the <code xref="/1.0/mal_inline_cmd">cmd</code> element
69 to provide a command for a user to run in a command-line environment.</p>
70
71 <example>
72 <code><![CDATA[
73 <p>Use <cmd>yelp-tool</cmd> to create HTML from your Mallard document.</p>
74 ]]></code>
75 <p>Use <cmd>yelp-tool</cmd> to create HTML from your Mallard document.</p>
76 </example>
77
78 <p>Sometimes you need to refer to options or arguments to commands.  In
79 Mallard, you mark up command arguments with the <code>cmd</code> element
80 as well.</p>
81
82 <example>
83 <code><![CDATA[
84 <p>Use the <cmd>-o</cmd> option to specify an output directory.</p>
85 ]]></code>
86 <p>Use the <cmd>-o</cmd> option to specify an output directory.</p>
87 </example>
88 </section>
89
90 <section id="block">
91 <title>Code Blocks</title>
92
93 <p>Sometimes you need to provide multiple lines of code or file contents,
94 or you may want to put a long line of code on its own line to make it
95 easier to read.  You can use the <code xref="/1.0/mal_block_code">code</code>
96 element outside of a paragraph to create a code block.</p>
97
98 <example>
99 <code><![CDATA[
100 <code>
101 if (bean_is_magic(bean)) {
102   bean_grow(bean);
103 }
104 </code>
105 ]]></code>
106 <code>
107 if (bean_is_magic(bean)) {
108   bean_grow(bean);
109 }
110 </code>
111 </example>
112
113 <note style="tip">
114 <p>In Mallard, the first line break in a code block is ignored.  This allows
115 you to write the contents more naturally.  Indentation, however, is not ignored.
116 If you indent your code block to match the indentation in your XML file, it
117 will show up in the output.</p>
118 </note>
119
120 <p>The contents of your code block might contain special XML characters like
121 <code>&lt;</code>.  You can write these with standard XML escape sequences like
122 <code>&amp;lt;</code>, but that can become cumbersome, especially when writing
123 the contents of an XML file.  Fortunately, XML provides a special syntax called
124 <code>CDATA</code> to escape large amounts of text.</p>
125
126 <example>
127 <code><![CDATA[
128 <code><![CDATA[
129 <page xmlns="http://projectmallard.org/1.0/
130       type="guide" id="index">
131   <info>
132     <!-- Page information goes here -->
133   </info>
134   <!-- Page contents go here -->
135 </page>
136 ]]>]]&gt;&lt;/code></code>
137 <code><![CDATA[
138 <page xmlns="http://projectmallard.org/1.0/
139       type="guide" id="index">
140   <info>
141     <!-- Page information goes here -->
142   </info>
143   <!-- Page contents go here -->
144 </page>
145 ]]></code>
146 </example>
147
148 <p>You can use the <code>CDATA</code> syntax anywhere you need to escape a lot
149 of special characters.  It is a standard XML feature, not specific to Mallard
150 or code blocks.</p>
151
152 </section>
153
154 <section id="cmd">
155 <title>Command-line Sessions</title>
156
157 <p>If you need to provide a long command to your readers, you may want to
158 show the command in its own block.  Long commands can be difficult to read
159 when embedded inline in a paragraph.  You can use the
160 <code xref="/1.0/mal_block_screen">screen</code>
161 element to show a command in a block.</p>
162
163 <example>
164 <code><![CDATA[
165 <screen>
166 xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
167   `pkg-config --variable mal2html.xsl yelp-xsl` \
168   index.page
169 </screen>
170 ]]></code>
171 <screen>
172 xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
173   `pkg-config --variable mal2html.xsl yelp-xsl` \
174   index.page
175 </screen>
176 </example>
177
178 <note style="tip">
179 <p>Just as in code blocks, a leading line break is ignored in
180 <code>screen</code> elements.</p>
181 </note>
182
183 <p>You can also use the <code>screen</code> element to show commands along
184 with their output.  To mark up the input and output, use the
185 <code xref="/1.0/mal_inline_input">input</code> and
186 <code xref="/1.0/mal_inline_output">output</code> elements.</p>
187
188 <example>
189 <code><![CDATA[
190 <screen>
191 <input>ls *.page</input>
192 <output>index.page  planting.page  uses.page</output>
193 </screen>
194 ]]></code>
195 <screen>
196 <input>ls *.page</input>
197 <output>index.page  planting.page  uses.page</output>
198 </screen>
199 </example>
200
201 <p>If you want to provide more complicated command-line sessions, you can
202 use the <code>style</code> attribute on the <code>output</code> element
203 to mark up prompts and error output.</p>
204
205 <example>
206 <code><![CDATA[
207 <screen>
208 <output style="prompt">$ </output><input>ls *.page</input>
209 <output>index.page  planting.page  uses.page</output>
210 <output style="prompt">$ </output><input>rm uses.page</input>
211 <output style="prompt">$ </output><input>ls *.page</input>
212 <output>index.page  planting.page</output>
213 <output style="prompt">$ </output><input>rm uses.page</input>
214 <output style="error">rm: cannot remove `uses.page': No such file or directory</output>
215 </screen>
216 ]]></code>
217 <screen>
218 <output style="prompt">$ </output><input>ls *.page</input>
219 <output>index.page  planting.page  uses.page</output>
220 <output style="prompt">$ </output><input>rm uses.page</input>
221 <output style="prompt">$ </output><input>ls *.page</input>
222 <output>index.page  planting.page</output>
223 <output style="prompt">$ </output><input>rm uses.page</input>
224 <output style="error">rm: cannot remove `uses.page': No such file or directory</output>
225 </screen>
226 </example>
227
228 </section>
229
230 <section id="listing">
231 <title>Code Listings</title>
232
233 <p>When you use code blocks to show the contents of a file, you often want
234 to provide a name or title for the file.  You can do this in introductory
235 text in a paragraph before the code block, but displaying the title with
236 the code block makes it more clear to the reader.</p>
237
238 <p>The <code>code</code> element takes inline content and treats all its
239 contents as part of the code block, so you can't place a title inside the
240 <code>code</code> element.  Mallard provides the
241 <code xref="/1.0/mal_block_listing">listing</code>
242 element to allow you to specify a title for code blocks and similiar
243 content.</p>
244
245 <example>
246 <code><![CDATA[
247 <listing>
248 <title><file>index.page</file></title>
249 <code><![CDATA[
250 <page xmlns="http://projectmallard.org/1.0/
251       type="guide" id="index">
252   <info>
253     <!-- Page information goes here -->
254   </info>
255   <!-- Page contents go here -->
256 </page>
257 ]]>]]&gt;<![CDATA[</code>
258 </listing>
259 ]]></code>
260 <listing>
261 <title><file>index.page</file></title>
262 <code><![CDATA[
263 <page xmlns="http://projectmallard.org/1.0/
264       type="guide" id="index">
265   <info>
266     <!-- Page information goes here -->
267   </info>
268   <!-- Page contents go here -->
269 </page>
270 ]]></code>
271 </listing>
272 </example>
273
274 <p>The title is supplied by the <code xref="/1.0/mal_block_title">title</code>
275 element. This example also uses the <code xref="/1.0/mal_inline_file">file</code>
276 element, an inline element that allows you to provide a file name.</p>
277
278 <p>You can also use the <code>listing</code> element around any other
279 type of block content.  For example, you can use the <code>listing</code>
280 element to provide a title for a command inside a <code>screen</code>
281 element.</p>
282
283 <example>
284 <code><![CDATA[
285 <listing>
286 <title>Process a Mallard Document</title>
287 <screen>
288 xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
289   `pkg-config --variable mal2html.xsl yelp-xsl` \
290   index.page
291 </screen>
292 </listing>
293 ]]></code>
294 <listing>
295 <title>Process a Mallard Document</title>
296 <screen>
297 xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
298   `pkg-config --variable mal2html.xsl yelp-xsl` \
299   index.page
300 </screen>
301 </listing>
302 </example>
303
304 <p>Finally, you can also supply a short description for a listing using
305 the <code xref="/1.0/mal_block_desc">desc</code> element.</p>
306
307 <example>
308 <code><![CDATA[
309 <listing>
310 <title>Process a Mallard Document</title>
311 <desc>Note that the <cmd>pkg-config</cmd> command is surrounded by backticks.</desc>
312 <screen>
313 xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
314   `pkg-config --variable mal2html.xsl yelp-xsl` \
315   index.page
316 </screen>
317 </listing>
318 ]]></code>
319 <listing>
320 <title>Process a Mallard Document</title>
321 <desc>Note that the <cmd>pkg-config</cmd> command is surrounded by backticks.</desc>
322 <screen>
323 xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
324   `pkg-config --variable mal2html.xsl yelp-xsl` \
325   index.page
326 </screen>
327 </listing>
328 </example>
329
330 </section>
331
332 </page>