By default, the text that is generated for an olink is the same text that would be generated for an xref in the other document pointing to an internal target. For example, an internal xref to a chapter might generate text like this:

Chapter 3: "Using a Mouse"

This is the same text that another document will get if it forms an olink to the chapter. That's because the olink data file contains a copy of the xref text for every element with an id attribute in the document. The default olink text is that preformed cross reference text.

The olink data file also contains the individual pieces of cross reference information, such as title, number, and element type. These can be used to assemble alternate text for an olink, as described in the sections that follow.

You may want to make it obvious that olinks are refering to another document rather than the current document. For example, if the reference just says Chapter 3: "Using a Mouse", the reader might think it was referring to Chapter 3 in the current book. To solve that problem, you can set the parameter olink.doctitle to yes, then the stylesheet will append the other document's title to the reference. The title is taken from the title child element of the root element in the external document. So if the other document is a book, then it will be the book's title.

See the section “Using xrefstyle attributes” for more options you can use in adding the target document's title.

The target data file for each document contains both the generated text and the pieces of text for each target. That is, it contains the fully formed cross reference text, as well as separate fields for the title, subtitle, element type, and number. That permits you to use the default preformed text, or to assemble the generated text in a different way.

The preformed text is based on the gentext templates in each language file in the common directory, using the gentext for resolving xref elements. For example, if you look in the file common/en.xml in the context element with attribute name="xref-number-and-title", you will find the gentext templates used to form xref text to target elements that have a number and title. The following is the gentext template for chapter, where %n refers to its number and %t refers to its title:

<l:template name="chapter" text="Chapter&#160;%n, %t"/>

Although these gentext templates were written for xref elements, they are also used for olinks. But what if you have customized these gentext templates? How does that change the generated text for olinks?

The answer depends on which stylesheet was used to generate the target data file for a document. That is the stylesheet that determines how the preformed olink text will look. If that stylesheet was customized, then the stored olink text will have those customizations. If another document olinks to that data, they get the customized version.

But what if you prefer that all your olinks use the cross reference styles of the current stylesheet? You can do that by setting the parameter use.local.olink.style to a value of 1 instead of the default zero. Then instead of using the preformed text from the target data file, the current stylesheet extracts the element name, title, and number from the target data, and forms the text using the current stylesheet's gentext templates.

So this parameter is useful only if you are processing a document with a stylesheet whose cross references are styled differently from the stylesheet that generated the target data file.

There are many situations where the default preformed text doesn't look right. For example, you might create a list of section title references. The default formatting would put each title in quotes, but the list would look more inviting without the quotes. What you need is a way to specify how you want an individual olink to look. You can do that with the xrefstyle attribute.

Olinks support the xrefstyle attribute that was introduced in version 4.3 of the DocBook DTD. The xrefstyle attribute on an xref or olink element is used to pass hints to the XSL stylesheet about how to generate the text for the current cross reference instance. You can specify a named style, a select list of keywords, or a gentext template. Starting with version 1.66 of the stylesheets, olinks support the same features of xrefstyle as for the xref element. See the section “Customizing with an xrefstyle attribute” for a complete description of using xrefstyle.

In the select: type of xrefstyle, you use keywords to specify what text pieces to include. Two new keywords were added for olinks. The docname keyword will generate the title of the other document, and the docnamelong keyword can be used to generate a longer reference to the title. These keywords are resolved using the following gentext templates for English:

<l:template name="docname" text=" in %o"/>
<l:template name="docnamelong" text=" in the document titled %o"/>

The %o placeholder is filled in with the other document's title. It is taken from the title associated with the root element of the other document in the olink database. You can customize the wording of these two gentext templates to suit your needs, and translate them for other languages. You can also use the %o in named xrefstyles in the gentext templates as well.

You can also use the %o placeholder in a template: type of xrefstyle. That syntax lets you word a cross reference instance as you like and include the other document's title.

You can also globally control the addition of the other document's title using the olink.doctitle stylesheet parameter. There are three possible values for this parameter:

You can also use the %p placeholder to generate a page number reference for an olink. If it is an internal olink, then it will be handled like an xref. If it is an external olink, this requires your olink database to have page attribute values on the div and obj elements, something that the stylesheet currently cannot generate. But if you find a way to collect such page number information, the olink template will use the data to generate a page number reference.

If you have set up page number processing for external olinks, then you can also turn them on or off globally using the insert.olink.page.number parameter. The values and behavior of this parameter are like that of olink.doctitle. If insert.olink.page.number is set to yes, then the stylesheet will try to append a page reference to each external olink. It will use the gentext template named olink.page.citation to generate the text, so you can customize that. If the page data for an olink is empty, then no text is generated. If you set the parameter to maybe, then you will get a page reference only if the xrefstyle calls for it. If you set the parameter to no, then no external olinks will get a page reference, even if the xrefstyle calls for it. The no setting lets you turn off the feature for all external olinks. The default value of insert.olink.page.number is no.