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
|
<page xmlns="http://www.gnome.org/~shaunm/mallard"
type="topic"
id="mal_page">
<info>
<version number="0.1" date="2008-02-21" status="stub"/>
</info>
<title>Pages</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
namespace local = ""
default namespace mal = "http://www.gnome.org/~shaunm/mallard"
start = mal_page
mal_page = element page {
attribute id { xsd:ID },
attribute type { "guide" | "topic"} ?,
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> *,
<link xref="mal_section">mal_section</link> *
}
</code></synopsis>
<p>The <code>page</code> element is the root element of any Mallard page file.
In Mallard, documents are composed of discrete pages which are interlinked
using various linking mechanisms. There are two types of pages in Mallard:
<link xref="#guide">guide pages</link> and <link xref="#topic">topic pages</link>.
Topic pages contain the bulk of the material discussed in a document, whereas
guide pages serve as navigational aids.</p>
<!-- BEGIN notes -->
<section id="notes">
<title>Notes</title>
<list>
<item><p>The <code>page</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>page</code> element is the top-level element in any
Mallard page file, and cannot occur in any other elements.</p></item>
<item><p>The <code>id</code> attribute takes a unique identifier, which
should match the base file name (without extension) of the file containing
the page.</p></item>
<item><p>The <code>type</code> attribute takes the values <code>"guide"</code> and
<code>"topic"</code>. <link xref="#guide">Guide pages</link> and <link xref="#topic">topic
pages</link> are discussed below. If the <code>type</code> attribute is
omitted, it is assumed to be <code>"topic"</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>page</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 guide -->
<section id="guide">
<title>Guide Pages</title>
<p>Guide pages have the <code>type</code> attribute set to
<code>"guide"</code>. They serve as navigational aids, linking to topics and
other guides. Readers can can browse through guides much as they would browse
through container sections in a linear document. Since page can be included
in multiple guides, however, readers are able to reach the same content by
navigating different paths.</p>
<p>Guide pages have links automatically inserted into their content based
on topic links within their own <code xref="mal_info">info</code> elements
and guide links within the <code>info</code> elements of other pages and
sections. Guide pages can contain sections to help organize content. Each
section in a guide page has automatic links inserted as well. See
<link xref="links#topic"/> for details on automatic topic links.</p>
<p>Guides also have see also links generated automatically. See
<link xref="links#seealso"/> for more information.</p>
<p>Generally, guide pages will contain some introductory content to help
readers understand the topics being presented. Introductory content should
be short and concise.</p>
</section>
<!-- END topic -->
<!-- BEGIN topic -->
<section id="topic">
<title>Topic Pages</title>
<p>Topic pages have the <code>type</code> attribute set to
<code>"topic"</code>, or have no <code>type</code> attribute at all. Topics
contain the bulk of the material in a document. A Topic may be a tutorial,
a conceptual overview, reference material, or any other type of content.
Mallard does not distinguish between different content types, although tools
may introduce special styling based on style hints. Topics are distinguished
from guides only in that their primary purpose is to convey information,
whereas guides serve as navigational aids.</p>
<p>Topic pages have links automatically inserted to all guides which link
to them. Topic pages can contain sections to help organize material and
present finer-grained chunks of information to the reader. Each section
in a topic page has automatic guide links inserted as well. See
<link xref="links#guide"/> for details on automatic guide links.</p>
<p>Topics also have see also links generated automatically. See
<link xref="links#seealso"/> for more information.</p>
</section>
<!-- END topic -->
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
</section>
<!-- END processing -->
</page>
|
