Site Layout
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.
In order for the stylesheets to construct the navigation system, you must describe the desired hierarchy explicitly in a layout file. The layout file, which must conform to layout.dtd, identifies all of the pages in the website and defines how they fit into the navigational hierarchy. Here is simple layout file:
<?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>
This website has three pages:
Using this layout file, the hierarchical structure of the website is a main page index.html with two subordinate pages that are siblings:
+ index.html
+ page1.html
+ page2.html
Here's a slightly more complicated example:
<?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>
This website has five pages:
Using this layout file, the hierarchical structure of the website is a main page index.html with two subordinate pages that are siblings (subdir/index.html and page2.html). The first sibling page has two siblings of its own (subdir/page2.html and subdir/page3.html):
+ index.html
+ subdir/index.html
+ subdir/page2.html
+ subdir/page2.html
+ page2.html
In brief, the hierarchy of tocentry elements in a toc describes the logical navigation hierarchy of the website. Each entry must identify the XML document (containing a <webpage>) that it represents and may identify the directory and filename where the file will appear in the HTML website.
By default, directories are inherited (hence page2.html and page3.html will appear in the subdir 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.
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 tocentry ancestry).
If a filename is not specified, index.html will be used.
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.
The layout file can also contain a number of global parameters: config, script, style, and copyright. For the most part, these elements behave as they do on individual pages, except that they apply to every page.
If you put multiple toc 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.
Navigation between hierarchies is only possible if you insert links between pages across hierarchies.
Pages identified with notoc elements instead of tocentrys will be in the website but will not appear in any hierarchy. The about page of this example website uses notoc.
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 “Building” page in this website. It's really just a hierarchy placeholder for the different sorts of building that are possible.
If you click on “Building” in the TOC, you'll discover that you don't actually go to that page, instead you go to that page's first child.
This effect is achieved by using the tocskip attribute on the tocentry for the building page.
Note, however, that the skipped page must exist and it is still possible to link directly to the page.