Easily create DocBook olinks

A refresher about olinks

The DocBook olink element allows to create a link between two different documents. For example, it allows to create a link in document folder1/Article1.xml pointing to the section having "sectionA" as its ID which is found in document folderA/ArticleA.xml.

The olink element used to represent the aforementioned link is:

<olink targetdoc="articleA" targetptr="sectionA"></olink>

• Notice that the target document is specified by a symbolic name, "articleA", rather then by its URL, "folderA/ArticleA.xml".
• The value of the targetptr attribute is simply the ID of the target element as contained in the target document. This attribute is optional. Without it, the olink implicitly points to the root element of the target document.
• An olink can optionally contain some text. When this text is absent, the DocBook XSL stylesheets automatically use the content of the title child element of the target element.

Where to find the symbolic name of each document involved in olinking? The DocBook XSL stylesheets requires such documents to be declared in a special XML file called a sitemap. The sitemap file describes the directory structure of your HTML or PDF output tree. You must declare the symbolic names of your documents in this file. Example:

<!DOCTYPE targetset [
  <!ENTITY article1 SYSTEM "folder1/target.db">
  <!ENTITY articleA SYSTEM "folderA/target.db">
]>
<targetset>
  <sitemap>
    <dir name="docs">
      <dir name="folder1">
        <document targetdoc="article1">
          &article1;
        </document>
      </dir>

      <dir name="folderA">
        <document targetdoc="articleA">
          &articleA;
        </document>
      </dir>
    </dir>
  </sitemap>
</targetset>

It is customary to use the ID of the root element of a document as its symbolic name.

Processing a set of olinked documents using the DocBook XSL stylesheets is not a simple task and we'll not attempt to describe it in this tutorial. For more information please refer to DocBook XSL: The Complete Guide by Bob Stayton.

In the following section, we'll see how XMLmind XML Editor can help you create olink elements. However it is important to understand that XMLmind XML Editor (XXE for short) cannot help you in putting these olink elements into use when converting your DocBook document to HTML, PDF, etc. For example, XXE cannot assist you in creating the sitemap file, in populating it with link targets, etc. All these tasks must be performed “by hand”, outside XXE.

How XMLmind XML Editor can help you

XMLmind XML Editor does not offer any special authoring tool which could help you in inserting olink elements in your document. You'll have to use the Edit tool to insert an olink element at caret position. Then you'll have to use the Attributes tool to specify its targetdoc attribute and optionally, its targetptr attribute.

Obviously, specifying the values of the targetdoc and targetptr attributes without any assistance is tedious and error-prone. That's why, if and only if you first use DocBook→Set up olinks to declare all your DocBook documents (XMLmind XML Editor cannot read your sitemap file):

1. You'll be able to use the autocompletion facility of the Attributes tool when you'll specify the values of the targetdoc and targetptr attributes.
2. The Edit button which is next to the attribute value field will display chooser dialog boxes specialized in olink attributes.
   

Set up olinks

The DocBook→Set up olinks menu item displays the following dialog box:

Basically this dialog box allows to create a list of DocBook 4 and/or DocBook 5 documents., each document being specified by its URL (e.g. "file:/E:/docs/olinking/folderA/ArticleA.xml") and its symbolic name (e.g. "articleA"). This list is specified once for all.

Make sure to specify the same symbolic name as the one found in your sitemap. If, by convention, your organization always uses the ID of the root element of a document as its symbolic name, then suffice to click the button.

Watch the screencast

(same but in a new window )