Inserting an olink in DocBook Documents

The olink element is used for linking to resources outside the current DocBook document. The targetdoc attribute is used for the document ID that contains the target element and the targetptr attribute for the ID of the target element (the value of an id or xml:id attribute). The combination of those two attributes provides a unique identifier to locate cross references.

For example, a Mail Administrator Guide with the document ID MailAdminGuide might contain a chapter about user accounts, like this:

<chapter id="user_accounts">
<title>Administering User Accounts</title>
<para>blah blah</para>

You can form a cross reference to that chapter by adding an olink, as in the following example:

You may need to update your
<olink targetdoc="MailAdminGuide" targetptr="user_accounts">user accounts
</olink>
when you get a new machine.

To use an olink to create links between documents, follow these steps:

  1. Decide which documents are to be included in the domain for cross referencing.
    A unique ID must be assigned to each document that will be referenced with an olink. It is usually added as an id (or xml:id for DocBook5) attribute to the root element of the document.
  2. Decide on your output hierarchy.
    For creating links between documents, the relative locations of the output documents must be known. Before going further you must decide the names and locations of the output directories for all the documents from the domain. Each directory will be represented by an element: <dir name="directory_name">, in the target database document.
  3. Create the target database document.
    Each collection of documents has a master target database document that is used to resolve all olinks from that collection. The target database document is an XML file that is created once. It provides a framework that pulls in the target data for each document. The database document is static and all the document data is pulled in dynamically.
    The following is an example of a target database document. It structures a collection of documents in a sitemap element that provides the relative locations of the outputs (HTML in this example). Then it pulls in the individual target data using system entity references to target data files that will be created in the next step.
    <?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE targetset [
<!ENTITY ugtargets SYSTEM "file:///doc/userguide/target.db"> 
<!ENTITY agtargets SYSTEM "file:///doc/adminguide/target.db">
<!ENTITY reftargets SYSTEM "file:///doc/man/target.db">
]>
<targetset> 
  <targetsetinfo> 
    Description of this target database document,
    which is for the examples in olink doc.
  </targetsetinfo>

  <!-- Site map for generating relative paths between documents -->
  <sitemap> 
    <dir name="documentation"> 
      <dir name="guides"> 
        <dir name="mailuser"> 
          <document targetdoc="MailUserGuide" 
                    baseuri="userguide.html"> 
            &ugtargets;
          </document>
        </dir>
        <dir name="mailadmin">
          <document targetdoc="MailAdminGuide">
            &agtargets;
          </document>
        </dir>
      </dir>
      <dir name="reference">
        <dir name="mailref">
          <document targetdoc="MailReference">
            &reftargets;
          </document>
        </dir>
      </dir>
    </dir>
  </sitemap>
</targetset>
  4. Generate the target data files by executing a DocBook transformation scenario.
    Before applying the transformation, you need to edit the transformation scenario, go to the Parameters tab, and make sure the value of the collect.xref.targets parameter is set to yes. The default name of a target data file is target.db, but it can be changed by setting an absolute file path in the targets.filename parameter.
    An example of a target.db file:
    <div element="book" href="#MailAdminGuide" number="1" targetptr="user_accounts">
  <ttl>Administering User Accounts</ttl>
  <xreftext>How to administer user accounts</xreftext>
  <div element="part" href="#d5e4" number="I">
    <ttl>First Part</ttl>
    <xreftext>Part I, “First Part”</xreftext>
    <div element="chapter" href="#d5e6" number="1">
      <ttl>Chapter Title</ttl>
      <xreftext>Chapter 1, Chapter Title</xreftext>
      <div element="sect1" href="#src_chapter" number="1" targetptr="src_chapter">
        <ttl>Section1 Title</ttl>
        <xreftext>xreflabel_here</xreftext>
      </div>
    </div>
  </div>
</div>
  5. Insert olink elements in the DocBook documents.
    When editing a DocBook XML document in Author mode, the Insert OLink action is available in the Link drop-down menu from the toolbar. This action opens the Insert OLink dialog box that allows you to select the target of an olink from the list of all possible targets from a specified target database document (specified in the Targetset URL field). Once a Targetset URL is selected, the structure of the target documents is presented. For each target document (targetdoc), its content is displayed, allowing you to easily identify the appropriate targetptr. You can also use the search fields to quickly identify a target. If you already know the values for the targetdoc and targetptr attributes, you can insert them directly in the corresponding fields.
    In the following image, the target database document is called target.xml, dbadmin is selected for the target document (targetdoc), and bldinit is selected as the value for the targetptr attribute. Notice that you can also add XREF text into the olink by using the xreftext field.

    Figure: Insert OLink Dialog Box

  6. Process a DocBook transformation for each document to generate the output.
    1. Edit the transformation scenario and set the value of the target.database.document parameter to be the URL of the target database document.
    2. Apply the transformation scenario.