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
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_block_synopsis">
<info>
<version number="0.1" date="2007-02-21" status="incomplete"/>
<credit type="author">
<name>Shaun McCance</name>
<email>shaunm@gnome.org</email>
</credit>
<copyright>
<year>2008-2009</year>
<name>Shaun McCance</name>
</copyright>
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
<desc>Create an overview of concepts.</desc>
</info>
<title>Synopses</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_synopsis = element synopsis {
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_title">mal_title</link> ?,
<link xref="mal_block_desc">mal_block_desc</link> ?,
<link xref="mal_block">mal_block</link> +
}
</code></synopsis>
<p>The <code>synopsis</code> element allows you to mark up a block as
providing an overview of the material being presented. It is useful
for providing a listing of functions, commands, or options in reference
material, or for enumerating the items in a menu or other graphical
control element.</p>
<comment>
<cite date="2006-11-16"><name>Shaun McCance</name></cite>
<p>Add explanation, examples</p>
</comment>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list type="bullet">
<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>synopsis</code> element can have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes on block elements.</p></item>
</list>
</section>
<!-- END notes -->
<!-- BEGIN examples -->
<section id="examples">
<title>Examples</title>
<p>Use <code>synopsis</code> to create an overview of functions:</p>
<example>
<code><![CDATA[<synopsis>
<title>Beanstalk Functions</title>
<desc>Use these methods on a <code>Beanstalk</code> object.</desc>
<code>
void add_bean (Bean bean);
int count_beans ();
</code>
</synopsis>
]]></code>
<synopsis>
<title>Beanstalk Functions</title>
<desc>Use these methods on a <code>beanstalk</code> object.</desc>
<code>
void add_bean (Bean bean);
int count_beans ();
</code>
</synopsis>
</example>
</section>
<!-- END examples -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>A <code>synopsis</code> element is rendered as a displayed block,
with each of its child elements interpreted as block elements. Since
a <code>synopsis</code> element often contains large blocks, and is
generally offset from the running text, display tools may opt to render
it inside a colored box, with a border, or otherwise differently from
the surrounding text.</p>
<p>If a <code xref="mal_title">title</code> element is provided, it
should appear at the top of the block and be clearly marked as the
title using font variations or other stylistic means.</p>
</section>
<!-- END processing -->
</page>
|
