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
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_inline_code">
<info>
<link type="guide" xref="mal_inline#elements"/>
<revision version="0.1" date="2008-12-12" status="review"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
<years>2008-2009</years>
</credit>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Mark up code from a programming, markup, or other machine-readable format.</desc>
</info>
<title>Code Snippets</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_code = element code {
<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>code</code> element to mark up a portion of text from a
computer language. This includes programming languages, markup languages,
and the contents of any type of file with a structured syntax. For commands
which are run in an interactive shell, however, you should use the
<code xref="mal_inline_cmd">cmd</code> element, even though they may
include snippets of shell programming.</p>
<p>You can use the <code>code</code> element to mark up any portion of
code, including comments or textual content that doesn't strictly follow
any syntax.</p>
<p>Use the <code xref="mal_inline_var">var</code> element inside a
<code>code</code> element to indicate text that should be replaced
by the user.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>code</code> element can contain a mixture of text and
any <link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>code</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>code</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>The <code>code</code> element can have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes.</p></item>
<item><p>The <code>code</code> element may also be used in a block context.
See <link xref="mal_block_code"/> for more information.</p></item>
</list>
</section>
<!-- END notes -->
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
<p>Use <code>code</code> to mark up the name of a function, struct, or other
constuct in a programming language:</p>
<example>
<code><![CDATA[
Use <code>gtk_container_add</code> to add a child widget to a
<code>GtkButton</code>.
]]></code>
<p>Use <code>gtk_container_add</code> to add a child widget to a <code>GtkButton</code>.</p>
</example>
<p>Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
up code with a placeholder for an argument the user should supply:</p>
<example>
<code><![CDATA[
To create a new button with a label, use
<code>gtk_button_new_with_label(<var>label</var>)</code>,
replacing <var>label</var> with the text of the label.
]]></code>
<p>To create a new button with a label, use
<code>gtk_button_new_with_label(<var>label</var>)</code>,
replacing <var>label</var> with the text of the label.</p>
</example>
<p>Link to a web page directly with a <code>code</code> element:</p>
<example>
<code><![CDATA[
Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
up code with a placeholder for an argument the user should supply.
]]></code>
<p>Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
up code with a placeholder for an argument the user should supply.</p>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Code snippets are displayed in a fixed-width font. This mimics
the look of a typical environment where code is typed. More importantly,
fixed-width fonts tend to have more distinction between visually similar
characters. This is particularly important in code, since letters often
appear without the context of a known word that helps make them discernable
in normal prose.</p>
<p>For particularly long code snippets, display tools may use a background
color or border to make the beginning and end clear, although authors should
prefer <link xref="mal_block_code">code blocks</link> for long code snippets.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>code</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/code.html">code</code> element
in DocBook. Since Mallard does not attempt to model programming languages,
<code>code</code> may be used in place of numerous DocBook elements, including
<code href="http://www.docbook.org/tdg/en/html/classname.html">classname</code>,
<code href="http://www.docbook.org/tdg/en/html/constant.html">constant</code>,
<code href="http://www.docbook.org/tdg/en/html/function.html">function</code>,
<code href="http://www.docbook.org/tdg/en/html/interfacename.html">interfacename</code>,
<code href="http://www.docbook.org/tdg/en/html/methodname.html">methodname</code>,
<code href="http://www.docbook.org/tdg/en/html/parameter.html">parameter</code>,
<code href="http://www.docbook.org/tdg/en/html/structfield.html">structfield</code>,
<code href="http://www.docbook.org/tdg/en/html/structname.html">structname</code>, and
<code href="http://www.docbook.org/tdg/en/html/varname.html">varname</code>.
Additionally, since Mallard does not provide separate elements for marking
portions of markup languages, the <code>code</code> element should be used
in place of the DocBook elements
<code href="http://www.docbook.org/tdg/en/html/markup.html">markup</code> and
<code href="http://www.docbook.org/tdg/en/html/sgmltag.html">sgmltag</code>.</p>
</section>
<!-- END comparison -->
</page>
|
