Website contains two basic forms of links. Internal and external to the site. This reflects the Docbook usage. For the target of a link to be considered internal, the id value must be on an element which is a part of the Website. Within these internal links a distinction is made based on html restrictions, between targets in the same file and targets in another file (generated from xml) within the same Website. I.e. if the source file were prep.xml and the target file was teapot.xml then this is classed as an external link, for which olink support is called for. This page describes it well, but for the sake of clarity it is repeated here using the earlier example.

Olink is different from the other linking mechanisms that you may be familiar with. Instead of using a URI (E.g. http://site/directory/file.html), or an IDREF (which results in a link to an ID value on another element in the same document) to form the link, it uses an XML unparsed entity. If that sounds Greek, don't worry too much, it's easy to do.

For this example, I'll create a link within file prep.xml to file brew.xml, to an imaginary paragraph with an id value of spout.

Firstly, within prep.xml, create an entity declaration that identifies the target page. As you are (may be?) aware, an entity declaration is a remnant of the SGML way of working, so must be declared as part of the doctype declaration. Now, since we are using the relax NG schema, we need to carefully mix and match, as shown in Example 14.

<!DOCTYPE webpage [
  <!ENTITY linking SYSTEM "brew.xml" NDATA XML>
]>

The name that you use for the entity, linking in this case, is irrelevant. The important thing is that the entity point to the right target file. Note also that the links are made at the xml level, so that the processor can transform them into correct links in the final html files that the reader will see

Keep in mind that the system identifier specified here must be either an absolute URI or a relative URI that will resolve to the target page (in other words, you may need to prefix it with a partial path name, if you keep your XML webpages in different directories). Since for the example site, all XML files are within the same directory, this is not the case. If, as a counter example, the target file was in a directory named procs which might hold all the source files for the second section of the site, and the source file was in a directory named prep which holds all the first section files. In this case the definition should be

      <!ENTITY linking SYSTEM "../procs/brew.xml" NDATA XML>

which is a relative path from the current file to the

If you want to link to several different pages, you will need an entity declaration for each page.

In the source file (prep.xml), to create the link, use the targetdoc attribute of olink element to identify the the page you want to link to: For this example it would be

<olink targetdoc="linking">link text</olink>

That will link to the correct page in the resulting Website. If you want to link to a specific anchor in that web page, use the targetptr attribute to specify the XML ID. So for this example, where the target is brew.xml, to a paragraph with an id value of spout, the link would be

  <olink 
    targetdoc="linking"
    targetptr="spout">link text</olink>

This would then be transformed into html with the appropriate link text as the link, which correctly links to the html file created from brew.xml (brew.html in the example).

This may seem like a lot of trouble to go to for a simple link. It is. The rewards are to be gained in the future, when you re-arrange the Website and the links still work. If the links are made directly in the more straightforward way, using ulink, then it is more likely that you won't realise the error. As usual, it's your choice.