Linking in Docbook

Bob Stayton

That's correct, if you are trying to cross reference among the books using <xref> and <link>. Those elements use the ID/IDREF mechanism to resolve links, and the ID and IDREF must be in the same document.

Currently the olink in the XSL stylesheets can't quite do what you want. The scenario where it works best looks like this:

This is a collection of books not inside of a set element, and where you want to form links between the books. By using olink for those links between books, you can avoid having to create one huge set document just to form links. With this scenario, you can process a single book whenever something changes in that book.

But you have to be careful, because when you start using olinks, you create dependencies between your books. Let's say you change a chapter title in book1 and reprocess that book. If your book3 has an olink to that chapter, and that olink element contains no text, then the chapter title link text that was generated the last time book3 was processed is now wrong and needs to be updated. If you use Makefiles, you can have book3 be dependent on book1's target data file, which is generated for olinking. If you are careful to not alter the timestamp on the target data file unless it actually changes, then the dependency works. See sagehill.net (the section on Using Makefiles) for an example.

You can also split a book up into chapter files, and use olinks to link among the book's chapter files. If you use XInclude instead of system entities to assemble the book, then you can have fully valid chapter files. That's a nice feature for writing and editing.

But processing a single chapter with the current stylesheets will always yield "Chapter 1" in the output, because that's the 'document' the processor is seeing. There are two ways around that. One way is to put a fixed "label" attribute on each chapter element, but that loses autonumbering. Who wants to manually maintain chapter numbers? Not me. Or you can process your master book file with the 'rootid' parameter to select a single chapter for output. This still loads and parses the entire book though, so I don't think it speeds things up a lot.

Since all we need is to set the chapter number, I have in mind a new parameter that tells the stylesheet to get the chapter number from the target data file for the book. But that feature isn't implemented yet.

Taking that idea a step further, you could construct a mega table of contents from your target database. It contains all the hierarchy, text, and URL information it needs to do that. So theoretically you could generate something like a complete set TOC for your collection of books, even though you have no set element.

Bob Stayton

You want to use the new implementation of olinks in the DocBook XSL stylesheets that can generate link text from a link database that has data for all the documents within a cross referencing scope. The olink syntax would be:

<olink targetdoc="software" targetptr="emacs"/>

See: Sagehill.net

You will have to extend the target collection process to include your customization. See the common/targets.xsl stylesheet, in mode="olink.mode".

Bob Stayton

Website supports *two* olink databases, identified by two different parameters:

You are setting the parameter for the offsite targets. That leaves the stylesheet to look for the website targets in the default location, which is the current directory. Change the parameter name in your command to 'website.database.document' and it should work.

You only need target.database.document if some of your webpages contain olink references to documents outside of your Website.

Bob Stayton

The usual way to reference a figure is to put the ID attribute on the figure element, and then use that id value in the linkend attribute of an xref. That generates something like "Figure 3.2". The stylesheets don't support xrefs to the caption inside a mediaobject inside a figure.

If you don't want the reference to say "Figure 3.1", then you have a couple of options. You can use a link element instead of xref, and supply whatever text you want inside of it. Or you can put an xreflabel attribute on any element, and then any xref that points to the id of that element will use the text of the xreflabel as the generated text. See this refererence for more information on xref options: sagehill.net

Jirka Kosek

Use link instead of xref. xref creates text of link automatically, while link lets you specify your own.