Chapter 29. Website

Chapter 29. Website
	Part IV. Special DocBook features

Table of Contents

Creating a webpage XML file

Allowed DocBook elements

Structuring your webpages

Generating your webpages

Build with XSLT only
Build with make
Source files in multiple directories

Linking between pages

Olinks with XSLT build method
Olinks with Make method

Linking to other sites

Adding other content

Website with XML catalogs

Website formatting

Using CSS with Website
Website config attributes
Website stylesheet customization

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.

Note

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.
Process your layout.xml file with the autolayout.xsl Website stylesheet to generate the autolayout.xml file.
Process the autolayout.xml file with one of the Website stylesheet to generate HTML webpages in the location specified by the output-root parameter.

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.

Creating a webpage XML file

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 29.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: 2005/03/02 18:08:12 $"/>
  <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 `webpage` with a required `id` attribute. Each `id` value must be unique across all of your webpages in the website.
	Optional `config` elements provide metadata for this page.
	Required `head` element.
	Required `title` element, which appears in the HTML `TITLE` element in the HTML `HEAD` element. It also appears at the top of the HTML page, except for the home page.
	Optional `summary` is used in the `title` attribute in HTML links, and in any `webtoc` that is generated.
	The content to be displayed on this webpage, marked up with DocBook elements.

Allowed 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.

website.dtd: 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 website.dtd.
website-full.dtd: A subset of the full DocBook DTD. There are approximately 400 elements in the website-full.dtd

Although 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 set, book, chapter, article, or 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 29.2. Elements common to website.dtd and website-full.dtd

abbrev	computeroutput	imagedata	personblurb	subject
abstract	config	imageobject	personname	subjectset
acronym	copyright	informaltable	phrase	subjectterm
affiliation	coref	inlinemediaobject	programlisting	subtitle
answer	corpauthor	issuenum	pubdate	summary
appendix	date	itemizedlist	publishername	surname
attribution	edition	jobtitle	qandadiv	systemitem
audiodata	editor	keyword	qandaentry	table
audioobject	email	keywords	qandaset	tbody
author	emphasis	keywordset	question	term
authorblurb	entry	label	quote	textdata
authorgroup	entrytbl	legalnotice	rddl:resource	textobject
authorinitials	epigraph	lineage	refsectioninfo	tfoot
base	errortext	lineannotation	releaseinfo	tgroup
bibliocoverage	example	link	replaceable	thead
bibliodiv	figure	listitem	revdescription	title
bibliography	filename	literal	revhistory	titleabbrev
biblioid	firstname	literallayout	revision	trademark
bibliomisc	footnote	mediaobject	revnumber	ulink
bibliomixed	footnoteref	member	revremark	userinput
bibliomset	head	meta	row	variablelist
bibliorelation	holder	note	rss	varlistentry
bibliosource	honorific	objectinfo	script	videodata
blockinfo	html:button	olink	section	videoobject
blockquote	html:form	option	sectioninfo	volumenum
caption	html:input	orderedlist	sgmltag	webpage
citebiblioid	html:label	orgname	sidebar	webtoc
citetitle	html:option	othercredit	simplelist	xref
colspec	html:select	othername	spanspec	year
command	html:textarea	para	style

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 webpage element.

Example 29.3. Additional elements in website-full.dtd

address	glossary	informalequation	refentry	simplelist
anchor	glosslist	informalexample	remark	simplesect
bridgehead	graphic	informalfigure	screen	synopsis
calloutlist	graphicco	mediaobjectco	screenco	tip
caution	highlights	msgset	screenshot	warning
classsynopsis, etc.	important	procedure	sect1, sect2, etc.
equation	index	programlistingco	segmentedlist
formalpara	indexterm	qandaset	simpara

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 don't 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 website-full.dtd.

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 this to your existing catalog.xml file:

<nextCatalog catalog="catalog.xml"
        xml:base="file:///usr/share/xml/website/website-2.5.0/" />

See Chapter 4, XML catalogs for more information.