# Site Layout

Site Navigation Layout Setup

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:

1. `index.html`, generated from `website.xml`;

2. `page1.html`, generated from `doc1.xml`; and

3. `page2.html`, generated from `doc2.xml`

(See also: revision flags)

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:

1. `index.html`, generated from `website.xml`;

2. `subdir/index.html`, generated from `doc1.xml`;

3. `subdir/page2.html`, generated from `doc1.1.xml`;

4. `subdir/page3.html`, generated from `doc1.2.xml`; and

5. `page2.html`, generated from `doc2.xml`

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/page3.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.

# Global Parameters

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.

# Multiple `toc`s

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.

# Standalone Pages

Pages identified with `notoc` elements instead of `tocentry`s will be in the website but will not appear in any hierarchy. The about page of this example website uses `notoc`.

# Dummy Pages

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.