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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="guide"
id="mal_block">
<info>
<link type="guide" xref="spec"/>
<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>Paragraphs, lists, tables, and various semantic elements for
building simple yet stunning pages.</desc>
</info>
<title>Block Elements</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block = (
<link xref="#basic">mal_block_basic</link> |
<link xref="#formal">mal_block_formal</link> |
<link xref="#lists">mal_block_list</link> |
<link xref="mal_table">mal_table</link>
)
</code></synopsis>
<p>Block elements are the building blocks of pages. Mallard provides block
elements for most common needs in software documentation, from simple paragraphs
to example blocks to powerful tables. Pages and sections in Mallard are built
up of block elements, which in turn contain either further block elements or
inline content.</p>
<p>Authors, editors, or other content producers sometimes need to supply
richer information in their documents. While this information may not
be conveyed by display tools, it may be used for various internal tracking
purposes. Mallard allows elements to be extended with attributes from
external namespaces. See <link xref="mal_external"/> for more
information.</p>
<!-- BEGIN basic -->
<section id="basic" style="2column">
<info>
<title type="link">Basic Block Elements</title>
<link type="topic" xref="mal_block_code"/>
<link type="topic" xref="mal_block_example"/>
<link type="topic" xref="mal_block_media"/>
<link type="topic" xref="mal_block_p"/>
<link type="topic" xref="mal_block_screen"/>
</info>
<title>Basic Elements</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_basic = (
<link xref="mal_block_code">mal_block_code</link> |
<link xref="mal_block_example">mal_block_example</link> |
<link xref="mal_block_media">mal_block_media</link> |
<link xref="mal_block_p">mal_block_p</link> |
<link xref="mal_block_screen">mal_block_screen</link>
)</code></synopsis>
<p>Basic block elements are elements that do not contain a title and which
have either general block content or <link xref="mal_inline">inline
content</link>. Using basic block elements, you can build up simple pages
which convey information clearly.</p>
</section>
<!-- END basic -->
<!-- BEGIN formal -->
<section id="formal" style="2column">
<info>
<title type="link">Formal Block Elements</title>
<link type="topic" xref="mal_block_comment"/>
<link type="topic" xref="mal_block_figure"/>
<link type="topic" xref="mal_block_listing"/>
<link type="topic" xref="mal_block_note"/>
<link type="topic" xref="mal_block_quote"/>
<link type="topic" xref="mal_block_synopsis"/>
</info>
<title>Formal Elements</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_formal = (
<link xref="mal_block_comment">mal_block_comment</link> |
<link xref="mal_block_figure">mal_block_figure</link> |
<link xref="mal_block_listing">mal_block_listing</link> |
<link xref="mal_block_note">mal_block_note</link> |
<link xref="mal_block_quote">mal_block_quote</link> |
<link xref="mal_block_synopsis">mal_block_synopsis</link>
)</code></synopsis>
<p>Formal block elements contain a <link xref="mal_title">title</link>
and general block content. Formal block elements allow you to provide
richer information in your pages.</p>
</section>
<!-- END formal -->
<!-- BEGIN lists -->
<section id="lists">
<info>
<link type="topic" xref="mal_block_dlist"/>
<link type="topic" xref="mal_block_olist"/>
<link type="topic" xref="mal_block_ulist"/>
</info>
<title>List Elements</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_list = (
<link xref="mal_block_dlist">mal_block_dlist</link> |
<link xref="mal_block_olist">mal_block_olist</link> |
<link xref="mal_block_ulist">mal_block_ulist</link> |
<link xref="mal_block_tree">mal_block_tree</link>
)</code></synopsis>
<p>Mallard provides list elements for most common needs, including the common
defintion, ordered, and unordered lists. Mallard also provides simple trees,
which are useful for representing heirarchies such as class inheritance or
directory layouts.</p>
</section>
<!-- END lists -->
<!-- BEGIN tables -->
<section id="tables">
<info>
<link type="topic" xref="mal_table"/>
</info>
<title>Tables</title>
<p>Mallard provides a simple table model based on HTML tables. While not
allowing the level of styling flexibility as HTML and CSS, Mallard tables
provides simple solutions to common styling needs, such as alternate-row
shading.</p>
</section>
<!-- END tables -->
<!-- BEGIN other -->
<section id="other">
<info>
<title type="link">Other Block Elements</title>
<link type="topic" xref="mal_title"/>
<link type="topic" xref="mal_subtitle"/>
<link type="topic" xref="mal_block_desc"/>
<link type="topic" xref="mal_block_cite"/>
</info>
<title>Other Block-like Elements</title>
<p>Mallard contains various block-like elements which are only used in
specific contexts, and are not allowed in general block content. These
elements allow for richer content models for the elements they appear
in.</p>
</section>
<!-- END other -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Block elements all begin on a new line in rendered output. Pages can
be visualized as a sequence of vertically-stacked block elements. Some
block elements contain other block elements. In these cases, the
containing element may introduce certain styling effects, and each of
the child elements is rendered as normal.</p>
<p>Each block element should be clearly distinguishable from its surrounding
block elements. Typically, vertical padding is placed between block elements
to set them apart. Certain block elements, especially those that have block
content, may use a border, background color, or other styling effects. See
each block element's specification for more details.</p>
</section>
<!-- END processing -->
</page>
|
