Structuring your webpages

Structuring your webpages
	Chapter 29. Website

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 29.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"> 
<layout>  
  <config param="text-prefix" value="txt"/>

  <config param="homebanner-tabular" value="graphics/homebanner.png"  
          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>  
    <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"/>  
  
  <toc page="website.xml" 
       filename="index.html">  
    <tocentry page="wslayout.xml" 
              revisionflag="changed" 
              filename="layout.html"/>  
    <tocentry page="olink.xml" 
              filename="linking.html"/>
    <tocentry page="custom.xml" 
              filename="custom.html"/>
    <tocentry page="building.xml" 
              filename="building.html" 
              tocskip='1'>  
      <tocentry page="build-make.xml" 
                filename="buildmake.html" 
                dir="build"/>  
      <tocentry page="build-ext.xml" 
                filename="buildext.html" 
                dir="build"/>  
      <tocentry page="build-textonly.xml" 
                filename="textonly.html" 
                dir="build"/>
    </tocentry>
    <tocentry page="test2.xml" 
              filename="formtest.html"/>
    ...

  </toc>
</layout>

	The DTD is a separate `layout.dtd`. You may want to utilize an XML catalog to resolve the DTD location.
	The root element must be `layout`.
	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.
	The `copyright` element prints copyright information in the footer of each webpage.
	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.
	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
	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. Don't put subdirectory paths in `filename`. Instead use the `dir` attribute.
	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.
	These nested `tocentry` elements appear under the container element.
	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:

Your XML webpage files do not have to be stored in one directory, nor do their locations have to reflect the website's logical hierarchy. You can place them individually in any locations that the stylesheets can reach from the current location.
The HTML output hierarchy also does not have to reflect the website's logical hierarchy. You can use dir attributes to create any convenient set of subdirectories for the HTML output.
All HTML output will be placed below a location specified by the output-root parameter, whose default value is "." (current directory). It can be a relative or absolute path.
If you specify a relative path in a dir attribute, it is taken as relative to the dir value of any ancestor tocentry elements. That way you don't have to specify complete pathnames. This is useful if you want the HTML output tree to reflect the website's logical hierarchy.
If you specify an absolute path (starting with "/") in a dir attribute, it is taken as relative to the output-root.