1.2.2. Specifying the set of olink-ed documents

Procedure:

  1. Select DocBookSet up olinks. This will display the following dialog box:

  2. Click Add. This will display this other dialog box.

  3. 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".

    Tip

    You can mix DocBook v4+ and DocBook v5+ documents within the same collection.

  4. 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>

    Tip

    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.

  5. 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 and DocBook v5+ configurations. However you may add or remove members to/from your document collection at any time.

Important

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.