Chapter 29. Website

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:

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:

  1. For each individual webpage that you want to generate, create an XML file using the webpage element .

  2. Structure your hierarchy of webpages by creating a layout.xml file that has references to your webpage XML files.

  3. Process your layout.xml file with the autolayout.xsl Website stylesheet to generate the autolayout.xml file.

  4. 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"> 1

  <config param="desc" value="The Test Home Page"/>  2
  <config param="rcsdate" value="$Date: 2005/03/02 18:08:12 $"/>
  <config param="footer" value="about.html" altval="About..."/>

  <head> 3
    <title>Welcome to Website</title>  4
    <summary>Introduction</summary>  5
    <keywords>Norman Walsh, DSSSL, SGML, XML, DocBook, Website</keywords>
  </head>

<para>This small, somewhat contrived website demonstrates the  6
Website document type. Website provides a system for building static
Websites from XML content.</para>
...

</webpage>
1

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.

2

Optional config elements provide metadata for this page.

3

Required head element.

4

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.

5

Optional summary is used in the title attribute in HTML links, and in any webtoc that is generated.

6

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

abbrevcomputeroutputimagedatapersonblurbsubject
abstractconfigimageobjectpersonnamesubjectset
acronymcopyrightinformaltablephrasesubjectterm
affiliationcorefinlinemediaobjectprogramlistingsubtitle
answercorpauthorissuenumpubdatesummary
appendixdateitemizedlistpublishernamesurname
attributioneditionjobtitleqandadivsystemitem
audiodataeditorkeywordqandaentrytable
audioobjectemailkeywordsqandasettbody
authoremphasiskeywordsetquestionterm
authorblurbentrylabelquotetextdata
authorgroupentrytbllegalnoticerddl:resourcetextobject
authorinitialsepigraphlineagerefsectioninfotfoot
baseerrortextlineannotationreleaseinfotgroup
bibliocoverageexamplelinkreplaceablethead
bibliodivfigurelistitemrevdescriptiontitle
bibliographyfilenameliteralrevhistorytitleabbrev
biblioidfirstnameliterallayoutrevisiontrademark
bibliomiscfootnotemediaobjectrevnumberulink
bibliomixedfootnoterefmemberrevremarkuserinput
bibliomsetheadmetarowvariablelist
bibliorelationholdernoterssvarlistentry
bibliosourcehonorificobjectinfoscriptvideodata
blockinfohtml:buttonolinksectionvideoobject
blockquotehtml:formoptionsectioninfovolumenum
captionhtml:inputorderedlistsgmltagwebpage
citebiblioidhtml:labelorgnamesidebarwebtoc
citetitlehtml:optionothercreditsimplelistxref
colspechtml:selectothernamespanspecyear
commandhtml:textareaparastyle 

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

addressglossaryinformalequationrefentrysimplelist
anchorglosslistinformalexampleremarksimplesect
bridgeheadgraphicinformalfigurescreensynopsis
calloutlistgraphiccomediaobjectcoscreencotip
cautionhighlightsmsgsetscreenshotwarning
classsynopsis, etc.importantproceduresect1, sect2, etc. 
equationindexprogramlistingcosegmentedlist 
formalparaindextermqandasetsimpara 

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.