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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<!DOCTYPE webpage SYSTEM "../schema/dtd/website.dtd" [
<!NOTATION XML SYSTEM "xml">
<!ENTITY olink.xml SYSTEM "olink.xml" NDATA XML>
<!ENTITY about.xml SYSTEM "about.xml" NDATA XML>
<!ENTITY building.xml SYSTEM "building.xml" NDATA XML>
]>
<webpage id="layout">
<config param="desc" value="Navigation Layout"/>
<config param="rcsdate" value="$Date: 2003/01/16 15:05:46 $"/>
<head>
<title>Site Layout</title>
<summary>Site Navigation Layout Setup</summary>
</head>
<para>Breaking all of the web pages into separate XML documents
introduces a significant problem: the hierarchical structure of the website
is no longer manifest in the source document.</para>
<para>In order for the stylesheets to construct the navigation system,
you must describe the desired hierarchy explicitly in a
<emphasis>layout</emphasis> file. The layout file, which must
conform to <filename>layout.dtd</filename>, identifies all of the
pages in the website and defines how they fit into the navigational
hierarchy. Here is simple layout file:
</para>
<programlisting><![CDATA[<?xml version="1.0"?>
<layout>
<toc page="website.xml" filename="index.html">
<tocentry page="doc1.xml" filename="page1.html"/>
<tocentry page="doc2.xml" filename="page2.html"/>
</toc>
</layout>]]></programlisting>
<para>This website has three pages:</para>
<orderedlist>
<listitem><para><filename>index.html</filename>,
generated from <filename>website.xml</filename>;
</para></listitem>
<listitem><para><filename>page1.html</filename>,
generated from <filename>doc1.xml</filename>; and
</para></listitem>
<listitem><para><filename>page2.html</filename>,
generated from <filename>doc2.xml</filename>
</para></listitem>
</orderedlist>
<para>(See also: <ulink url="revflag.html">revision flags</ulink>)</para>
<para>Using this layout file, the hierarchical structure of the website
is a main page <filename>index.html</filename> with two subordinate
pages that are siblings:</para>
<programlisting>
+ index.html
+ page1.html
+ page2.html
</programlisting>
<para>Here's a slightly more complicated example:</para>
<programlisting><![CDATA[<?xml version="1.0"?>
<layout>
<toc page="website.xml" filename="index.html">
<tocentry page="doc1.xml" dir="subdir"
filename="index.html">
<tocentry page="doc1.1.xml" filename="page2.html"/>
<tocentry page="doc1.2.xml" filename="page3.html"/>
</tocentry>
<tocentry page="doc2.xml" filename="page2.html"/>
</toc>
</layout>]]></programlisting>
<para>This website has five pages:</para>
<orderedlist>
<listitem><para><filename>index.html</filename>,
generated from <filename>website.xml</filename>;
</para></listitem>
<listitem><para><filename>subdir/index.html</filename>,
generated from <filename>doc1.xml</filename>;
</para></listitem>
<listitem><para><filename>subdir/page2.html</filename>,
generated from <filename>doc1.1.xml</filename>;
</para></listitem>
<listitem><para><filename>subdir/page3.html</filename>,
generated from <filename>doc1.2.xml</filename>; and
</para></listitem>
<listitem><para><filename>page2.html</filename>,
generated from <filename>doc2.xml</filename>
</para></listitem>
</orderedlist>
<para>Using this layout file, the hierarchical structure of the website
is a main page <filename>index.html</filename> with two subordinate
pages that are siblings (<filename>subdir/index.html</filename>
and <filename>page2.html</filename>). The first sibling page has
two siblings of its own (<filename>subdir/page2.html</filename>
and <filename>subdir/page3.html</filename>):</para>
<programlisting>
+ index.html
+ subdir/index.html
+ subdir/page2.html
+ subdir/page3.html
+ page2.html
</programlisting>
<para>In brief, the hierarchy of <sgmltag>tocentry</sgmltag> elements
in a <sgmltag>toc</sgmltag> describes the logical navigation hierarchy
of the website. Each entry must identify the XML document (containing
a <sgmltag class="starttag">webpage</sgmltag>) that it represents and
may identify the directory and filename where the file will appear in
the HTML website.</para>
<para>By default, directories are inherited (hence
<filename>page2.html</filename> and <filename>page3.html</filename>
will appear in the <filename>subdir</filename> directory) which makes
it easy to build a website that has similar logical and physical
organization. It is not necessary for the logical and physical
hierarchy of your website to be consistent; you can specify an absolute
directory at any level and on any file by beginning the name with a
slash.</para>
<para>If a directory is not specified, the files will appear in the currently
inherited directory (or in the root, if no directory is specified anywhere
in the <sgmltag>tocentry</sgmltag> ancestry).</para>
<para>If a filename is not specified, <filename>index.html</filename> will
be used.</para>
<para>It is possible to map two different XML documents to the same HTML
filename. At present, the stylesheets do not detect this, but the result
will be a broken website. Exercise caution.</para>
<section><title>Global Parameters</title>
<para>The layout file can also contain a number of global parameters:
<sgmltag>config</sgmltag>,
<sgmltag>script</sgmltag>,
<sgmltag>style</sgmltag>, and
<sgmltag>copyright</sgmltag>. For the most part, these elements behave
as they do on individual pages, except that they apply to every page.
</para>
</section>
<section><title>Multiple <sgmltag>toc</sgmltag>s</title>
<para>If you put multiple <sgmltag>toc</sgmltag> elements in your
layout file, the result will be completely separate navigational hierarchies.
Note, however, that the restriction that a page can only appear once in
a website prevents a page from appearing in more than one hierarchy.
</para>
<para>Navigation between hierarchies is only possible if you insert
<olink targetdocent="olink.xml">links between pages</olink>
across hierarchies.
</para>
</section>
<section><title>Standalone Pages</title>
<para>Pages identified with <sgmltag>notoc</sgmltag> elements instead
of <sgmltag>tocentry</sgmltag>s will be in the website but will not appear
in any hierarchy. The <olink targetdocent="about.xml">about page</olink>
of this example website uses <sgmltag>notoc</sgmltag>.
</para>
</section>
<section><title><quote>Dummy</quote> Pages</title>
<para>Sometimes it's useful to have a page in the hierarchy in order to
make the TOC clearer, without actually wanting to construct the page.
Consider the <quote>Building</quote> page in this website. It's really
just a hierarchy placeholder for the different sorts of building that
are possible.</para>
<para>If you click on <quote>Building</quote> in the TOC, you'll discover
that you don't actually go to that page, instead you go to that page's
first child.</para>
<para>This effect is achieved by using the
<sgmltag class="attribute">tocskip</sgmltag> attribute on the
<sgmltag>tocentry</sgmltag> for the building page.</para>
<para>Note, however, that the skipped page must exist and it is still
possible to link directly to
<olink targetdocent="building.xml">the page</olink>.</para>
</section>
</webpage>
|
