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
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_section">
<info>
<revision version="0.1" date="2009-05-28" 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>Break up pages into logical chunks to help readers find
information quickly.</desc>
</info>
<title>Sections</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_section = element section {
attribute id { xsd:ID },
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_info">mal_info</link> ?,
<link xref="mal_block_title">mal_block_title</link>,
<link xref="mal_block">mal_block</link> *,
mal_section *
}
</code></synopsis>
<p>A section is a prominent logical part of a page or another section.
Breaking up material into sections can help readers find information
more quickly. In Mallard, sections can take part in
<link xref="links">automatic linking</link> just as pages can.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>section</code> element contains an optional
<code xref="mal_info">info</code> element, a <code xref="mal_block_title">title</code>
element, any <link xref="mal_block">general block content</link>, and
any number of <code xref="mal_section">section</code> elements.</p></item>
<item><p>The <code>section</code> can occur in <code xref="mal_page">page</code>
elements and other <code>section</code> elements.</p></item>
<item><p>The <code>id</code> attribute takes a unique identifier. It should
be distinct from all other <code>id</code> attributes in the same page,
including those on other <code>section</code> elements and on the containing
<code xref="mal_page">page</code> element.</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>section</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 processing -->
<section id="processing">
<title>Processing Expectations</title>
<p>Each section is displayed as a block. The title of a section is displayed
prominently, followed by any child block content, and finally by each child
section. Note that automatic links, style hints, or other special features
may insert material or change the way pages are displayed. Sections should
be clearly separated from their surrounding content to make the beginning and
ending of each section obvious. The depth of each section should be clear,
although this may not be feasible for deeply nested sections.</p>
<p>Sections may have links associated with them. All sections should have
guide links and see also links displayed when applicable. See
<link xref="links#guide"/> and <link xref="links#seealso"/> for more
information. Sections in guide pages have topic links inserted following
their block content. See <link xref="links#topic"/> for more information.</p>
</section>
<!-- END processing -->
</page>
|
