Options for resolving olinks

Options for resolving olinks
	Chapter 24. Olinking between documents

The stylesheets have a few options for locating the target of an olink.

If you want to point to the top of another document, you can omit the targetptr attribute on the olink element. The stylesheet will use the targetdoc attribute to locate the data file for the document, and will use the targetptr of the root element in the target data to resolve the link.

In one special circumstance you can omit the targetdoc attribute from your olinks. You can do this only if you include a targetptr attribute, and there is a single document in the olink database. When is that useful? When you are using olinks only within a modular document that is assembled by XInclude. Using olink instead of xref for modular documents is described in the section “Modular cross referencing”. When you process the document, the olinks must have an olink database to resolve such olinks. If you are not using olinks for external cross references, then the olink database just needs to include the single document.

Another feature to support modular source files is the prefer.internal.olink stylesheet parameter. This is useful when you reuse a content module in more than one document. If you cross reference to such a module, you do not want to open another document if the content exists in the current document. Setting prefer.internal.olink to 1 causes the stylesheet to first test the current document's olink data to see if it has the id or xml:id value of the targetptr. If it does not, then the stylesheet falls back to the requested targetdoc data set.

Language fallback option

Olinks will try to resolve to a document in the same language as the source document. If that fails, then the stylesheet can fall back through a sequence of languages that you specify in the olink.lang.fallback.sequence parameter. This is similar to the language negotiation performed by an HTTP browser and server.

This means olinks can work within a collection in which only some of the documents are currently translated. In general you want an olink to resolve to a target document in the same language. This means the olink database should include the data for all translated versions of a document. You can do this by including multiple document elements in the database and setting the lang attribute in each to different values. You can have document elements with duplicate targetdoc attributes only if their lang attributes differ.

During processing, an olink's source language is determined by the closest ancestor lang attribute in the source document. The stylesheet looks for the olink's targetdoc in that language first. That is, it looks in the olink database for a document element that has both of the matching targetdoc and lang attributes. If that fails, then it tries the first language in the fallback sequence. If that fails, it goes on to the next, etc.

For example, if you set the olink.lang.fallback.sequence parameter to de en, and the olink's closest ancestor lang attribute in the source document is fr, then the stylesheet first looks in the olink database for a document element with a matching targetdoc and with lang="fr". If that combination is not found, then stylesheet looks for the same targetdoc with lang="de", and finally lang="en".

Debugging olinks

Because olink resolution is more complex now, a new stylesheet parameter olink.debug was added. When set to 1, the stylesheet will output messages on how each olink is being resolved. The messages are verbose, and you will likely need to study the XSL templates that generate the messages to understand them fully.


Formatting olinks		Processing options