An olink is a type of link between two Docbook XML documents.
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.
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.
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.
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>
Insert OLink Dialog