Linking between pages

Linking between pages
	Chapter 29. Website

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"/>

The targetdoc attribute identifies the document that contains the target of the link. In Website, the id attribute value on the webpage element is used as the document identifier since it must exist and it must be unique. Its value should be used in the targetdoc attribute of an olink.
The targetptr attribute must match an id attribute value on an element within that document. If you want to link to the top of the page, then the targetptr should have the same value as the targetdoc attribute.
If an olink has no content, then the stylesheet generates content in a manner similar to an xref. The content comes from a website database document that the stylesheets can create. If an olink element does have content, then that is used instead of the generated content.
Once you enter olinks between your webpages, you need to make sure the website.database.document parameter is set to process them. The following sections describe the processing steps for the two build methods in Website.
You have the option to use a second olink database to form olinks to a collection of documents outside of your webpage collection. That database is identified by the target.database.document and is discussed fully in Chapter 23, Olinking between documents.

Olinks with XSLT build method

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

Create your layout.xml file the same as before.
Process your layout.xml file as before with the autolayout.xsl stylesheet to create the autolayout.xml file.
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.

Create your layout.xml file the same as before.
Do the autolayout.xml and depends processing steps as before.
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.
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.


Generating your webpages		Linking to other sites