blob: 577b9878bf00cd79266ad57244263dcb1c4347fa (
plain)
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
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_block_desc">
<info>
<link type="seealso" xref="mal_block_figure"/>
<link type="seealso" xref="mal_block_listing"/>
<link type="seealso" xref="mal_block_synopsis"/>
<version number="0.1" date="2009-05-19" 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>Provide a caption for a formal block element.</desc>
</info>
<title>Block Descriptions</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_desc = element desc {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_inline">mal_inline</link>
}
</code></synopsis>
<p>The <code>desc</code> element marks a short text description for
formal block elements like <link xref="mal_block_figure">figure</link>.
The description provided by <code>desc</code> is formatted as a caption
for the formal element.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<ulist>
<item><p>The <code>desc</code> element can contain a mixture of text and
any <link xref="mal_inline">general inline elements</link>.</p></item>
<item><p>The <code>desc</code> element can occur in the formal block elements
<code xref="mal_block_figure">figure</code>,
<code xref="mal_block_listing">listing</code>, and
<code xref="mal_block_synopsis">synopsis</code>.</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>desc</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>desc</code> element can also be used in an informational
context. See <link xref="mal_info_desc"/> for more information.</p></item>
</ulist>
</section>
<!-- END notes -->
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
<p>Use <code>desc</code> to provide a caption for a
<link xref="mal_block_figure">figure</link>:</p>
<example>
<code><![CDATA[
<figure>
<desc>Drake, the Mallard mascot</desc>
<media type="image" mime="image/png" src="figures/mallard.png"/>
</figure>
]]></code>
<figure>
<desc>Drake, the Mallard mascot</desc>
<media type="image" mime="image/png" src="figures/mallard.png"/>
</figure>
</example>
<p>Use <code>desc</code> to provide a caption for a
<link xref="mal_block_figure">listing</link>:</p>
<example>
<code><![CDATA[
<listing>
<desc>A first Mallard page</desc>
<code><![CDATA[
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="guide"
id="index">
<!-- Content goes here -->
</page>]]]>]><![CDATA[</code>
</listing>]]></code>
<listing>
<desc>A first Mallard page</desc>
<code><![CDATA[
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="guide"
id="index">
<!-- Content goes here -->
</page>]]></code>
</listing>
</example>
<p>More exaples can be found on the pages <link xref="mal_block_figure"/>,
<link xref="mal_block_listing"/>, and <link xref="mal_block_synopsis"/>.</p>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>The exact display of a description will depend on how the enclosing formal
element is displayed. A description is a block of text that is displayed
directly above or below the normal contents of the enclosing element.</p>
<p>A description should be displayed in a way that makes its role clearn and
which clearly distinguishes it from the normal block content of the enclosing
element.</p>
</section>
<!-- END processing -->
</page>
|
