The olink element is the equivalent for linking outside the current
Docbook document. It has the attribute targetdoc for the document ID that
contains the target element and the attribute targetptr for the ID (the
value of an id or xml:id attribute) of the target element.
The combination of those two attributes provides a unique identifier to locate cross
references.
For example, the Administrator Guide is a book with the document ID
MailAdminGuide and it contains a chapter about user accounts like the
following:
<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 in the
User Guide like the following:
You may need to update your
<olink targetdoc="MailAdminGuide" targetptr="user_accounts">user accounts
</olink>
when you get a new machine.
-
Decide what documents are included in the domain for cross referencing.
An ID should be assigned to each document that will be referenced with an
olink. Usually it is added as an id or
xml:id attribute to the root element of the document. A document ID
is a string that is unique for each document in your collection. For example the
documentation may include a user's guide, an administrator's guide, and a reference
document. These could have simple IDs like ug, ag, and
ref or more specific IDs like MailUserGuide,
MailAdminGuide, and MailReference.
-
Decide the output hierarchy.
For creating links between documents, the relative locations of the output documents
must be known. Generally the HTML files for multiple documents are output to different
directories if chunking is used. Before going further you must decide the names and
locations of the HTML 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. In the example
from the next step the hierarchy is documentation/guides/mailuser,
documentation/guides/mailadmin,
documentation/guides/reference.
-
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. An example is the following:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE targetset
SYSTEM "file:///tools/docbook-xsl/common/targetdatabase.dtd" [
<!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>
An example of a target.db file:
<!DOCTYPE div
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<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>
-
Generate the target data files.
These files are the target.db files from the above example of
target database document. They are created with the same DocBook transformation scenario
as the HTML or XHTML output. The XSLT parameter called
collect.xref.targets must be set to the value 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 XSLT parameter
targets.filename.
-
Insert olink elements in the DocBook XML documents.
When a DocBook XML document is edited in Author mode Oxygen provides the
Insert OLink action on the toolbar. This action allows selecting
the target of an olink from the list of all possible targets from a
specified target database document. In the following image the target database document is
called target.xml.
Insert OLink Dialog
-
Process each document for output.
That is done using a DocBook transformation scenario in which the URL of the target
database document is set in the target.database.document parameter. The
DocBook XSL stylesheets know how to resolve olinks in the output files
using the value of this parameter.