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
|
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="mal_page">
<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>Individual tutorials, overviews, references, and navigational guides.</desc>
</info>
<title>Pages</title>
<synopsis><code mime="application/relax-ng-compact-syntax">
namespace local = ""
default namespace mal = "http://projectmallard.org/1.0/"
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 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>
<p>In on-screen media, a <code>page</code> element is displayed as a single
page. In this case, <em>page</em> is used in the sense of <em>web page</em>:
something which can be read top-to-bottom by scrolling. This should not be
confused with physical pages — one side of a leaf of paper — or with any
fixed-height electronic pages such as those used by word processors and
e-books.</p>
<p>The <code>info</code> child element is not displayed directly, although
certain informational elements may be displayed or affect aspects of the
page display. In particular, the <code>info</code> element may contain
<code>link</code> elements which will cause automatic links to be inserted
into the displayed output. See <link xref="links"/> for more information.</p>
<p>The title of a page is displayed prominently at the top, 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.</p>
</section>
<!-- END processing -->
</page>
|
