Table of Contents
The DocBook Website package is a customization of the DocBook XSL stylesheets that can be used to generate a set of webpages that make up a website. You write the webpages in XML and use the Website stylesheets to convert them to HTML. Here are some of its features:
You can create a hierarchy of webpages that descend from the home page.
You can display a table of contents on the left side of each generated page that shows the content of the whole website. The table of contents is repeated on all generated pages, with the current page marked with an arrow graphic.
The table of contents list can expand and collapse to expose or hide the hierarchy of content.
You can incorporate references to other HTML content, using website to organize and present the content.
Website is not meant to be used to dynamically generate webpages on request by a browser. Rather, it is used to produce a set of relatively static pages from XML source.
The overall process of using Website can be summarized in these steps:
For each individual webpage that you want to generate, create an XML file using the
webpage element .
Structure your hierarchy of webpages by creating a
layout.xml file that has references to your webpage XML files.
layout.xml file with the
autolayout.xsl Website stylesheet to generate the
autolayout.xml file with one of the Website stylesheet to generate HTML webpages in the location specified by the
This document does not cover all the details and options for using Website. See the Website documentation at http://docbook.sourceforge.net/release/website/example/index.html for more information.
Also, there is available an extended version of DocBook Website. See the section “SilkPage: enhanced Website”.
Each webpage is written using DocBook XML elements and some additional Website elements. The document root element of each webpage file must be
webpage, followed by any optional
config elements, a required
head element, and then the content of the page marked up with DocBook elements. The following is the top of the home page example file that is included with the Website distribution:
Example 31.1. Sample webpage XML file
<?xml version="1.0"?> <!DOCTYPE webpage ... > <webpage id="home"> <config param="desc" value="The Test Home Page"/> <config param="rcsdate" value="$Date: 2007/09/02 18:19:18 $"/> <config param="footer" value="about.html" altval="About..."/> <head> <title>Welcome to Website</title> <summary>Introduction</summary> <keywords>Norman Walsh, DSSSL, SGML, XML, DocBook, Website</keywords> </head> <para>This small, somewhat contrived website demonstrates the Website document type. Website provides a system for building static Websites from XML content.</para> ... </webpage>
The document root element is
The content to be displayed on this webpage, marked up with DocBook elements.
Not all DocBook elements are available to be used within a
webpage element. That's because the hierarchical relationship of the pages is expressed in a separate website layout file.
The allowed elements are determined by the DOCTYPE in each webpage file. There are two Website DTDs to choose from.
A subset of the Simplified DocBook DTD. The Simplified DocBook DTD is itself a subset of the Docbook DTD, and was designed for cases where the full DTD is not needed. There are approximately 150 elements in the
A subset of the full DocBook DTD. There are approximately 400 elements in the
website-full.dtd is much bigger, most of the extra elements are not usable within a
webpage element. For example, none of the elements
index can be used, although they are included in the
website-full.dtd. It helps to think of each webpage as roughly equivalent to a
section element, with a title, various block elements like paragraphs and lists, and possibly subsections. The
website-full.dtd has a somewhat richer selection of elements that can appear on a webpage.
The following is a list of elements that can be used with either DTD:
Example 31.2. Elements common to website.dtd and website-full.dtd
The only additions beyond the standard DocBook elements are the handful with the
html: namespace for inserting HTML form elements.
The following is a list of additional elements in
website-full.dtd that can be used within a
Example 31.3. Additional elements in website-full.dtd
|classsynopsis, etc.||important||procedure||sect1, sect2, etc.|
The choice of DTD is specified in the DOCTYPE declaration in each webpage XML file. You would use one of these:
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.5.0//EN" "website.dtd" > or <!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website Full V2.5.0//EN" "website-full.dtd">
For each file you can choose the appropriate DTD; you do not have to be consistent among your webpage files. In general, you should use the smaller
website.dtd unless you need one of the elements from the larger set in
When you process your files, the processor will need to resolve the DTD location. You might want to use the XML catalog file that comes with the Website distribution to resolve the PUBLIC identifiers in the DOCTYPE to the actual file locations on your system. This is most easily done by adding an entry like the following to your existing
<nextCatalog catalog="catalog.xml" xml:base="file:///usr/share/xml/website/website-2.5.0/" />
See Chapter 5, XML catalogs for more information.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises