Structuring your webpages

You create the content and logical structure for your website by writing a layout.xml file. You can name the file whatever you like. For each webpage XML file, you add a tocentry element to layout.xml to indicate its location in the logical hierarchy. Think of it as writing a table of contents. By nesting tocentry elements, you create nested heading levels in the your table of contents similar to chapter, sect1, sect2, etc. in a book's table of contents. You can also put various config elements in the file to provide configuration parameters for your website.

The following shows the first part of the example layout.xml file included with the Website distribution:

Example 31.4. Example layout.xml file

<?xml version="1.0"?>
<!DOCTYPE layout PUBLIC "-//Norman Walsh//DTD Website Layout V2.5.0//EN"
       "http://docbook.sourceforge.net/release/website/2.5.0/layout.dtd"> 1
<layout>  2
  <config param="text-prefix" value="txt"/>

  <config param="homebanner-tabular" value="graphics/homebanner.png"  3
          altval="Home Banner"/>
  <config param="banner-tabular"     value="graphics/banner.png"
          altval="Banner"/>

  <config param="homebanner" value="graphics/homebanner.png"
          altval="Home Banner"/>
  <config param="banner"     value="graphics/icons/iconhome.gif"
          altval="Banner"/>

  <copyright>  4
    <year>1999</year><year>2000</year><year>2001</year>
    <holder role="http://nwalsh.com/~ndw/">Norman Walsh</holder>
  </copyright>

  <style src="example.css" type="text/css"/>  5
  
  <toc page="website.xml" 
       filename="index.html">  6
    <tocentry page="wslayout.xml" 
              revisionflag="changed" 
              filename="layout.html"/>  7
    <tocentry page="olink.xml" 
              filename="linking.html"/>
    <tocentry page="custom.xml" 
              filename="custom.html"/>
    <tocentry page="building.xml" 
              filename="building.html" 
              tocskip='1'>  8
      <tocentry page="build-make.xml" 
                filename="buildmake.html" 
                dir="build"/>  9
      <tocentry page="build-ext.xml" 
                filename="buildext.html" 
                dir="build"/>  10
      <tocentry page="build-textonly.xml" 
                filename="textonly.html" 
                dir="build"/>
    </tocentry>
    <tocentry page="test2.xml" 
              filename="formtest.html"/>
    ...

  </toc>
</layout>

1

The DTD is a separate layout.dtd. You may want to utilize an XML catalog to resolve the DTD location.

2

The root element must be layout.

3

Optional config elements specify configuration information for the whole site. The param attribute specifies the name of the parameter, and the value attribute holds the value for that parameter. This example specifies a graphics filename to be displayed at the top of the home page when the tabular presentation is used.

4

The copyright element prints copyright information in the footer of each webpage.

5

The style element specifies a CSS stylesheet name that each generated HTML file should reference. HTML files output to subdirectories will have proper relative pathnames generated for them so only a single stylesheet location need be specified. You will have to copy that stylesheet file into place, however.

6

The site starts with a single top-level toc element. That specifies the site's home page. It does not appear in the table of contents listing

7

Each tocentry element adds a line to the site's table of contents. The page attribute specifies the webpage XML file used to create the HTML file whose name is specified in the filename attribute. do not put subdirectory paths in filename. Instead use the dir attribute.

8

This tocentry contains three others, which become its subheadings in the table of contents. The tocskip attribute is set when you want the container link to skip directly to the first subpage.

9

These nested tocentry elements appear under the container element.

10

An optional dir attribute puts the generated HTML page in a subdirectory of that name. Such subdirectories nest if the tocentry elements nest, unless an absolute path is specified. You must create any subdirectories by hand since XSL stylesheets cannot create directories.


Note these features while creating the layout.xml file: