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
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_block_synopsis">
<info>
<link type="seealso" xref="mal_block_listing"/>
<revision version="0.1" date="2009-05-19" 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>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_block_title">mal_block_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">Shaun McCance</cite>
<p>Add explanation, examples</p>
</comment>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>synopsis</code> element contains an optional
<link xref="mal_block_title">title</link> element, an optional
<link xref="mal_block_desc">desc</link> element, and any
<link xref="mal_block">general block content</link>.</p></item>
<item><p>The <code>synopsis</code> element can occur in any
general block context, including inside
<link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
and certain <link xref="mal_block">block elements</link>.</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>synopsis</code> element can have attributes from external
namespaces. See <link xref="mal_external"/> for more information
on external-namespace attributes.</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>When present, the title and description should be displayed in a
way that makes their respective roles clear.</p>
</section>
<!-- END processing -->
<!-- BEGIN comparison -->
<section id="comparison">
<title>Comparison to Other Formats</title>
<p>The <code>synopsis</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/synopsis.html">synopsis</code>
element in DocBook, although the DocBook element is not a formal element.
DocBook also provides the
<code href="http://www.docbook.org/tdg/en/html/cmdsynopsis.html">cmdsynopsis</code> and
<code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html">funcsynopsis</code>
elements, which attempt to model the data for command and function synopses,
respectively. Mallard does not provide modelling elements.</p>
</section>
<!-- END comparison -->
</page>
|
