Linking between pages

As with any website, you will probably want to create links between your webpages. In a DocBook document, you would use xref and link to form links between parts of your document. But in Website, each webpage is a separate XML document, so you cannot use xref or link because they only work within a document.

To link between your webpages, you can use olink. Starting with Website version 2.5, olink became much easier to use. That version adopted the new XSL-based olink mechanism that is described in this book. See Chapter 23, Olinking between documents for general background information on using olinks. In Website, olinking is even easier than it is for regular DocBook documents. That's because Website maintains information about the separate webpage documents in the layout.xml file, so it can set up the olink data files automatically. Website can also handle a second olink database to generate links to other documents besides webpages.

Olink differs from other linking elements in that it requires two attributes: one to locate the document and one to locate an ID value within that document. Here is an example of an olink:

<olink targetdoc="home" targetptr="whatsnew"/>

Olinks with XSLT build method

Here is how you process a website with olinks using the XSLT build method.

  1. Create your layout.xml file the same as before.

  2. Process your layout.xml file as before with the autolayout.xsl stylesheet to create the autolayout.xml file.

  3. Process your autolayout.xml file as before with either the chunk-tabular.xsl or chunk-website.xsl stylesheet. But set the parameter collect.xref.targets to the value “yes”.

    xsltproc \
       --stringparam  collect.xref.targets yes \
        --stringparam  output-root  htdocs \
        ../website/xsl/chunk-tabular.xsl  \
        autolayout.xml
    

    That command will generate a database file named website.database.xml in the current directory, and use that to resolve olinks.

Olinks with Make method

Here is how you process a website with olinks using the Makefile method.

  1. Create your layout.xml file the same as before.

  2. Do the autolayout.xml and depends processing steps as before.

  3. Generate the website database file by processing your autolayout.xml file with the website-targets.xsl stylesheet, saving the output to a file named website.database.xml.

  4. Process your website as you would normally (usually by typing make website), but add the website.database.document parameter whose value is the pathname of the generated database file. If you use the default filename website.database.xml, then you can omit the parameter on the command line.

The following is a sample Makefile using xsltproc and XML catalogs. The extra steps for olinking are highlighted.

PROC = XML_CATALOG_FILES=../catalog.xml  xsltproc

all:
        make website

include depends.tabular

autolayout.xml:  layout.xml
        $(PROC) \
        --output  $@ \
        autolayout.xsl  $<

        make depends

depends:  autolayout.xml
        $(PROC) \
        --output depends.tabular \
        --stringparam  output-root  htdocs  \
        makefile-dep.xsl  $<


website.database.xml:  autolayout.xml
        $(PROC) \
        --output $@ \
       website-targets.xsl  $<

%.html: autolayout.xml
        $(PROC) \
        --output $@  \
        --stringparam  website.database.document website.database.xml \
        --stringparam  output-root  htdocs \
        tabular.xsl  \
        $(filter-out autolayout.xml,$^)

This Makefile proceeds as before, except it also builds a website targets database website.database.xml. It then passes that filename as the website.database.document parameter to the stylesheet when it processes the webpages. These two steps make the target information available to the XSLT processor so it can resolve the olinks in the webpages.