1.2.2. Specifying the set of olink-ed documents

Procedure:

Select DocBook → Set up olinks. This will display the following dialog box:
Click Add. This will display this other dialog box.
Use the Browse button to specify the URL of a document which is a member of the collection. In the above screenshot, this URL is "file:/C:/src/4xxe/docsrc/help/help.xml".
You can mix DocBook 4 and DocBook 5 documents within the same collection.


You can mix DocBook 4 and DocBook 5 documents within the same collection.

Type the symbolic name of the document in the Document name text field. In the above screenshot, this name is "help".

This name, which cannot contain space characters, corresponds to a possible value for the targetdoc attribute. The same symbolic name must also be used in the target database document. Example:

<!DOCTYPE targetset 
  SYSTEM "../../addon/config/docbook/xsl/common/targetdatabase.dtd" [
  ...
  <!ENTITY help SYSTEM "help_html.targets">
  ...
]>
<targetset>
  <sitemap>
    <dir name="doc">
      ...
      <dir name="help">
        <document targetdoc="help">
          &help;
        </document>
      </dir>
      ...
    </dir>
  </sitemap>
</targetset>


Instead of typing the symbolic name of the document referenced in the Document location text field, it's also possible to click the button. This button allows to use the ID of the root element (if any) of the document referenced in the Document location text field as a symbolic name. Using the ID of the root element as the symbolic name of an “olink-ed document” is a common practice. However, before using this button, make sure that this practice is actually used in your organization.

Instead of typing the symbolic name of the document referenced in the Document location text field, it's also possible to click the button. This button allows to use the ID of the root element (if any) of the document referenced in the Document location text field as a symbolic name.

Using the ID of the root element as the symbolic name of an “olink-ed document” is a common practice. However, before using this button, make sure that this practice is actually used in your organization.

Repeat steps 1 to 4 until you have declared all the members of your document collection.

This setup is done once for all for both the DocBook 4 and 5 configurations. However you may add or remove members to/from your document collection at any time.


XXE can help you create `olink` elements. However it is important to understand that XXE 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. More information in DocBook XSL: The Complete Guide, by Bob Stayton.

XXE can help you create olink elements. However it is important to understand that XXE 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. More information in DocBook XSL: The Complete Guide, by Bob Stayton.