Docbook Links

Docbook offers several forms of links: link, olink, ulink, xref Examples. This page will one day explain, which form to use in which case.

Motivation

While document internal links are easy, cross references between different documents, here Guide and Help, are difficult.

• When we supported only xml for yelp, we used URLs with the protocol ghelp:.

It searchs for /usr/[locale/]share/gnome/help/<docname>/<LANG>/<docname>.<extension>.

With the XDG help-spec protocol help: was introduced, which searches /usr/[locale/]share/help/<LANG>/<docname>/index.<extension>. You can still use both as shorthand under Linux like to test the german help

LANG=de_DE-utf8 yelp ghelp:gnucash-help

But they do not work under other OSes or other file formats like html, chm, pdf, mobi or epub.

• One approach to circumvent this issue is the use of https: in a published resource at gnucash.org. The downside: you can not read it offline.

So we will have to use olinks. Because olinks are very powerful, they a complicated, not well documented and their elements changed over the time.

One easy to understand source is Chapter 24. Olinking between documents in DocBook XSL: The Complete Guide