Olink HOWTO

Robert Stayton

Caldera International, Inc.

<bobs@caldera.com>

18 October +Olink HOWTO

Olink HOWTO

Robert Stayton

Caldera International, Inc.

<bobs@caldera.com>

22 October 2001

Table of Contents

The basic idea
The olink toolkit
A working example
Example of modular files
Using Makefiles

This document describes a DocBook customization kit that implements olink in an easy-to-use fashion. This customization permits you to create and resolve cross references between DocBook documents. This means you no longer have to put everything you want to cross reference to in the same document.

The basic idea

When you form a conventional cross reference to another element within a DocBook document, you specify the value of that element's id attribute in the cross reference's linkend attribute. When you go beyond internal links to form a cross reference to another document, you have to also identify which document contains the id you are pointing to. If each document has some sort of document identifier, then a cross reference just needs to specify a document id and an element id.

In a given document, any element that has an id attribute is a potential target for a cross reference. In this customization, information about all the elements with ids is extracted ahead of time and saved in a separate target dataset for that document. Then a master target database is formed by assembling all the separate datasets for the documents you want to cross reference among. Within the database, each set of ids is associated with its particular document id. So to resolve a cross reference, a processor first looks up the document id in the database, and then searches among its element ids to find the match.

To form a cross reference to another DocBook document, you specify the document id and the element id as attributes in an olink element. You process documents with such olinks using the customized DocBook XSL stylesheet in this toolkit. That customization has a modified olink template that knows how to open a target database, find the the matching document id and element id, and form a proper cross reference. You inform the stylesheet what target database to use by passing a parameter value at runtime.

Keep in mind that once you start forming cross references between documents, you are creating dependencies between those documents. A document with olinks to other documents is no longer completely self-contained. If any of those documents changes, you may need to regenerate your output to ensure accurate cross references. You will need to set up your development environment to manage the new dependencies you will be creating. This is most efficiently handled using Makefiles which track the dependencies.

The olink toolkit

This olink toolkit has two parts. The first part consists of the stylesheets for extracting the cross reference data from all of your documents. The second part is the customization of the standard DocBook XSL stylesheets to resolve olinks. All of these files are in the tools directory of the toolkit. Here is a description of all the files.

targets.xsl: Stylesheet used to generate a target data set for a document that is to be output as one HTML file (not chunked). This stylesheet imports the standard DocBook XSL stylesheet and the targets-common.xsl file.
chunktargets.xsl: Similar to targets.xsl, but used to generate a target data set for a document that is to be chunked as multiple HTML files when output.
targets-common.xsl: Not used directly, but is imported by targets.xsl and chunktargets.xsl. It has the actual XSL templates for generating the cross reference database elements.
custom.xsl: Stylesheet used to generate HTML output for documents with olinks. It is a customization of the standard DocBook XSL stylesheet for generating output in a single HTML file. If you have other stylesheet customizations, they can be merged.
chunkcustom.xsl: Similar to custom.xsl, except it outputs the HTML into multiple files (chunked). If you have other chunking stylesheet customizations, they can be merged.
newolink.xsl: Not used directly, but is imported by custom.xsl and chunkcustom.xsl. It has the actual XSL template for generating the cross reference output for olinks.

The toolkit also includes an examples directory that has three documents that illustrate the use of olinks.

A working example

This section describes the procedure for setting up and using the toolkit for cross referencing between two documents. It includes the details of all the steps, and a simple running example to illustrate usage. The example files are in the examples subdirectory of the toolkit.

This procedure may seem long, but seven out of ten of the steps are setting up the system. Once that is done, writing and processing cross references between documents is quite easy.

Procedure 1.

Before you begin, you need to install the toolkit in some location relative to your document files. Then you'll need to adjust some relative paths. Edit the <xsl:import> statement in the following files to adjust the relative paths to the location of the standard Docbook stylesheet files on your system:
```
 Edit this line:
     <xsl:import href="../../docbook-xsl-1.45/html/docbook.xsl"/> 
@@ -13,7 +13,7 @@ And edit this similar line:
 
 in these files in the tools directory:
     chunkcustom.xsl
-    chunktargets.xsl
```
Alternatively, you can use full http URLs to resolve the references to the stylesheet files.
Decide which documents you want to cross reference among. You can designate different sets of documents for different projects as long as you give the database files different names. Generally each set of documents in a database will be processed in the same time frame so the cross references remain current, although that is not a requirement. Also, the HTML output from files in a set is generally installed under the same HTTP server so that the cross references have some place to go.
In the examples directory are three short documents that illustrate the use of olinks:
Document Description
userguide.xml A short article output as a single HTML file.
ref.xml A collection of reference pages output in chunks.
modular.xml A multichapter book set up using modular files.
For each document, assign a unique document identifier. The identifiers can follow whatever naming scheme you choose, as long as each string is unique among a given document set. If you share your documents, everyone in the group needs to agree to the naming scheme to keep the names unique.
In the examples, the assigned document identifiers are:
Document Document Identifier
userguide.xml ug
ref.xml ref
modular.xml modular
For HTML output, decide on how the HTML output of the documents will be located relative to each other. This is necessary for properly forming links that work in the resulting output. In general, a flattened directory arrangement is easiest to manage.
In the examples, the HTML output will go to three directories all at the same level:
Document HTML output directory
userguide.xml UserGuide
ref.xml Reference
modular.xml Modular
That arrangement permits cross references between documents to use relative URLs of the form:
```
../UserGuide/filename.html
```
For each document, generate a file that contains its target data set. This is done by applying the targets.xsl stylesheet to your document and saving the output in a file. If your document is to be chunked when processed, then use chunktargets.xsl instead. Process each document, saving the result in a different file.
In the examples, using xsltproc the commands would be:
```
xsltproc ../tools/targets.xsl userguide.xml > ugtargets.xml
+    chunktargets.xsl
```
Alternatively, you can use full http URLs to resolve the references to the stylesheet files.
Decide which documents you want to cross reference among. You can designate different sets of documents for different projects as long as you give the database files different names. Generally each set of documents in a database will be processed in the same time frame so the cross references remain current, although that is not a requirement. Also, the HTML output from files in a set is generally installed under the same HTTP server so that the cross references have some place to go.
In the examples directory are three short documents that illustrate the use of olinks:
Document Description
userguide.xml A short chapter output as a single HTML file.
ref.xml A collection of reference pages output in chunks.
modular.xml A multichapter book set up using modular files.
For each document, assign a unique document identifier. The identifiers can follow whatever naming scheme you choose, as long as each string is unique among a given document set. If you share your documents, everyone in the group needs to agree to the naming scheme to keep the names unique.
In the examples, the assigned document identifiers are:
Document Document Identifier
userguide.xml ug
ref.xml ref
modular.xml modular
For HTML output, decide on how the HTML output of the documents will be located relative to each other. This is necessary for properly forming links that work in the resulting output. In general, a flattened directory arrangement is easiest to manage.
In the examples, the HTML output will go to three directories all at the same level:
Document HTML output directory
userguide.xml UserGuide
ref.xml Reference
modular.xml Modular
That arrangement permits cross references between documents to use relative URLs of the form:
```
../UserGuide/filename.html
```
For each document, generate a file that contains its target data set. This is done by applying the targets.xsl stylesheet to your document and saving the output in a file. If your document is to be chunked when processed, then use chunktargets.xsl instead. Process each document, saving the result in a different file.
In the examples, using xsltproc the commands would be:
```
xsltproc ../tools/targets.xsl userguide.xml > ugtargets.xml
 xsltproc ../tools/chunktargets.xsl ref.xml > reftargets.xml
 xsltproc --xinclude ../tools/chunktargets.xsl modular.xml > modtargets.xml
```
See the section called “Example of modular files” for details on how the modular.xml file is handled.
Manually create a target database framework file. For an example, see targetdb.xml in the examples directory. This is an XML document that contains information about all of your documents. It contains information at the document level, and does not contain the target data sets for the documents. Instead, the information for each document includes a reference to its data set file. Keeping the data sets in separate files means that each can be updated when its document changes.
In the examples, the target database file looks like:
```
<?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE t:targetset SYSTEM "../tools/targetdatabase.dtd">
-- 
2.40.0
```

Document	Description
userguide.xml	A short article output as a single HTML file.
ref.xml	A collection of reference pages output in chunks.
modular.xml	A multichapter book set up using modular files.

Document	Description
userguide.xml	A short chapter output as a single HTML file.
ref.xml	A collection of reference pages output in chunks.
modular.xml	A multichapter book set up using modular files.