In Website, the website pages are separate XML documents, so it is not possible to use xref or link to make links between them. Instead, you must use olink.
Olink differs from other linking elements because 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"/>
Here is how you process a website with olinks using the XSLT build method.
That command will generate a database file named website.database.xml in the current directory and use it for processing olinks. The database contains cross reference data for all the potential olink targets in your website pages. That database filename is referenced by the stylesheet using the website.database.document parameter, whose value by default is set to website.database.xml in the current directory.
Here is how you process a website with olinks using the Makefile method.
Below is a simple example Makefile (using xsltproc and XML catalogs) that does a olink-aware build of a website.
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.
You can link from your Website table of contents or from Website pages to content outside of your Website. In your Website table of contents, you might want to point to content from other websites. The tocentry element in your layout.xml file can take an href attribute instead of page and file attributes. Such a tocentry adds a link in your generated table of contents to other content. The href value can be any URL, so it can be used to point to other content on your website, or to other websites. All you need to supply is a URL in the hrefattribute, an id attribute (required), and a title element. The following section has an example.
If you need to link from within your webpages to other sites, then you have two choices:
The olink solution requires careful set up, but it can reduce link maintenance time in the long run because the links are resolved from a database of targets. You just have to keep the targets database up to date, a process that can be automated. If, after a database update, one of your olinks no longer resolves, the stylesheet reports the error so you can fix it. Also, olinks can be empty, which causes their link text to be generated from the targets database. That ensures that the link text is kept up to date.
The process of generating and using an olink database for a collection of DocBook documents is described in http://www.sagehill.net/docbookxsl/Olinking.html. Once you have the target database, you can pass its pathname to the XSLT processor using the target.database.document stylesheet parameter. This database is in addition to (and separate from) the olink database that resolves olinks between webpages in your website. The database of internal olinks is identified with the website.database.document parameter. When the processor encounters an olink, it first checks the website database before consulting the offsite database. Here is a Makefile example that uses both.
%.html: autolayout.xml $(PROC) \ --output $@ \ --stringparam website.database.document website.database.xml \ --stringparam target.database.document olinkdb.xml \ --stringparam output-root htdocs tabular.xsl \ $(filter-out autolayout.xml,$^)
The original system for olinks uses SYSTEM entities referenced by a targetdocent attribute instead of a targetdoc attribute. And it uses the localinfo attribute instead of targetptr to locate a reference point within the document. Here is how you process the original kind of olinks with Website.
 It's also possible to use ulink and make links directly to the generated HTML pages, but that's a bad idea; if you change the hierarchy or rename a page, the link will become stale. With olink this won't happen.