<html><head>
-<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Olink HOWTO</title><meta name="generator" content="DocBook XSL Stylesheets V1.42"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h2 class="title"><a name="N2593"></a>Olink HOWTO</h2></div><div><h3 class="author">Robert Stayton</h3><div class="affiliation"><span class="orgname">Caldera International, Inc.<br></span><div class="address"><tt><<a href="mailto:bobs@caldera.com">bobs@caldera.com</a>></tt></div></div></div><div><p class="copyright">Copyright © 2001 Robert Stayton</p></div><div><p class="pubdate">18 October
+<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Olink HOWTO</title><meta name="generator" content="DocBook XSL Stylesheets V1.42"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h2 class="title"><a name="N2593"></a>Olink HOWTO</h2></div><div><h3 class="author">Robert Stayton</h3><div class="affiliation"><span class="orgname">Caldera International, Inc.<br></span><div class="address"><tt><<a href="mailto:bobs@caldera.com">bobs@caldera.com</a>></tt></div></div></div><div><p class="copyright">Copyright © 2001 Robert Stayton</p></div><div><p class="pubdate">22 October
2001</p></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#N2626">The basic idea</a></dt><dt><a href="#N2658">The olink toolkit</a></dt><dt><a href="#N2750">A working example</a></dt><dt><a href="#modulardoc">Example of modular files</a></dt><dt><a href="#N3352">Using Makefiles</a></dt></dl></div><p>This document describes a DocBook customization kit that implements <tt>olink</tt> 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.</p><div class="sect1"><a name="N2626"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="N2626"></a>The basic idea</h2></div></div><p>When you form a conventional cross reference to another element within a DocBook document, you specify the value of that element's <tt>id</tt> attribute in the cross reference's <tt>linkend</tt> attribute. When you go beyond internal links to form a cross reference to another document, you have to also identify which document contains the <tt>id</tt> 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.</p><p>In a given document, any element that has an <tt>id</tt> attribute is a potential target for a cross reference. In this customization, information about all the elements with <tt>id</tt>s 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 <tt>id</tt>s 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. </p><p>To form a cross reference to another DocBook document, you specify the document id and the element id as attributes in an <tt>olink</tt> 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.</p><p>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.</p></div><div class="sect1"><a name="N2658"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="N2658"></a>The olink toolkit</h2></div></div><p>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 <tt>tools</tt> directory of the toolkit. Here is a description of all the files.</p><div class="variablelist"><dl><dt><a name="N2668"></a><span class="term"><tt>targets.xsl</tt></span></dt><dd><p><a name="N2673"></a>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 <tt>targets-common.xsl</tt> file. </p></dd><dt><a name="N2680"></a><span class="term"><tt>chunktargets.xsl</tt></span></dt><dd><p><a name="N2685"></a>Similar to <tt>targets.xsl</tt>, but used to generate a target data set for a document that is to be chunked as multiple HTML files when output. </p></dd><dt><a name="N2692"></a><span class="term"><tt>targets-common.xsl</tt></span></dt><dd><p><a name="N2697"></a>Not used directly, but is imported by <tt>targets.xsl</tt> and <tt>chunktargets.xsl</tt>. It has the actual XSL templates for generating the cross reference database elements.</p></dd><dt><a name="N2708"></a><span class="term"><tt>custom.xsl</tt></span></dt><dd><p><a name="N2713"></a>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.</p></dd><dt><a name="N2716"></a><span class="term"><tt>chunkcustom.xsl</tt></span></dt><dd><p><a name="N2721"></a>Similar to <tt>custom.xsl</tt>, except it outputs the HTML into multiple files (chunked). If you have other chunking stylesheet customizations, they can be merged.</p></dd><dt><a name="N2728"></a><span class="term"><tt>newolink.xsl</tt></span></dt><dd><p><a name="N2733"></a>Not used directly, but is imported by <tt>custom.xsl</tt> and <tt>chunkcustom.xsl</tt>. It has the actual XSL template for generating the cross reference output for olinks.</p></dd></dl></div><p>The toolkit also includes an <tt>examples</tt> directory that has three documents that illustrate the use of olinks.</p></div><div class="sect1"><a name="N2750"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="N2750"></a>A working example</h2></div></div><p>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 <tt>examples</tt> subdirectory of the toolkit.</p><p>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.</p><div class="procedure"><p><a name="N2761"></a><b>Procedure 1. </b></p><ol type="1"><li><a name="N2762"></a><p>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 <tt><xsl:import></tt> statement in the following files to adjust the relative paths to the location of the standard Docbook stylesheet files on your system:<pre class="literallayout">
Edit this line:
<xsl:import href="../../docbook-xsl-1.45/html/docbook.xsl"/>
in these files in the tools directory:
chunkcustom.xsl
- chunktargets.xsl</pre>Alternatively, you can use full http URLs to resolve the references to the stylesheet files.</p></li><li><a name="N2774"></a><p>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.</p><p>In the <tt>examples</tt> directory are three short documents that illustrate the use of olinks:<div class="informaltable" id="N2784"><a name="N2784"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Document</th><th>Description</th></tr></thead><tbody><tr><td>userguide.xml</td><td>A short
article output as a single HTML file.</td></tr><tr><td>ref.xml</td><td>A collection of reference pages output in chunks.</td></tr><tr><td>modular.xml</td><td>A multichapter book set up using modular files.</td></tr></tbody></table></div></p></li><li><a name="N2825"></a><p>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.</p><p>In the examples, the assigned document identifiers are:<div class="informaltable" id="N2831"><a name="N2831"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Document</th><th>Document Identifier</th></tr></thead><tbody><tr><td>userguide.xml</td><td>ug</td></tr><tr><td>ref.xml</td><td>ref</td></tr><tr><td>modular.xml</td><td>modular</td></tr></tbody></table></div></p></li><li><a name="N2872"></a><p>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.</p><p>In the examples, the HTML output will go to three directories all at the same level:<div class="informaltable" id="N2878"><a name="N2878"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Document</th><th>HTML output directory</th></tr></thead><tbody><tr><td>userguide.xml</td><td>UserGuide</td></tr><tr><td>ref.xml </td><td>Reference</td></tr><tr><td>modular.xml</td><td>Modular</td></tr></tbody></table></div>That arrangement permits cross references between documents to use relative URLs of the form:<pre class="literallayout">../UserGuide/<i><tt>filename</tt></i>.html</pre></p></li><li><a name="N2927"></a><p>For each document, generate a file that contains its target data set. This is done by applying the <tt>targets.xsl</tt> stylesheet to your document and saving the output in a file. If your document is to be chunked when processed, then use <tt>chunktargets.xsl</tt> instead. Process each document, saving the result in a different file.</p><p>In the examples, using <b>xsltproc</b> the commands would be:<pre class="literallayout">xsltproc ../tools/targets.xsl userguide.xml > ugtargets.xml
+ chunktargets.xsl</pre>Alternatively, you can use full http URLs to resolve the references to the stylesheet files.</p></li><li><a name="N2774"></a><p>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.</p><p>In the <tt>examples</tt> directory are three short documents that illustrate the use of olinks:<div class="informaltable" id="N2784"><a name="N2784"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Document</th><th>Description</th></tr></thead><tbody><tr><td>userguide.xml</td><td>A short
chapter output as a single HTML file.</td></tr><tr><td>ref.xml</td><td>A collection of reference pages output in chunks.</td></tr><tr><td>modular.xml</td><td>A multichapter book set up using modular files.</td></tr></tbody></table></div></p></li><li><a name="N2825"></a><p>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.</p><p>In the examples, the assigned document identifiers are:<div class="informaltable" id="N2831"><a name="N2831"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Document</th><th>Document Identifier</th></tr></thead><tbody><tr><td>userguide.xml</td><td>ug</td></tr><tr><td>ref.xml</td><td>ref</td></tr><tr><td>modular.xml</td><td>modular</td></tr></tbody></table></div></p></li><li><a name="N2872"></a><p>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.</p><p>In the examples, the HTML output will go to three directories all at the same level:<div class="informaltable" id="N2878"><a name="N2878"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Document</th><th>HTML output directory</th></tr></thead><tbody><tr><td>userguide.xml</td><td>UserGuide</td></tr><tr><td>ref.xml </td><td>Reference</td></tr><tr><td>modular.xml</td><td>Modular</td></tr></tbody></table></div>That arrangement permits cross references between documents to use relative URLs of the form:<pre class="literallayout">../UserGuide/<i><tt>filename</tt></i>.html</pre></p></li><li><a name="N2927"></a><p>For each document, generate a file that contains its target data set. This is done by applying the <tt>targets.xsl</tt> stylesheet to your document and saving the output in a file. If your document is to be chunked when processed, then use <tt>chunktargets.xsl</tt> instead. Process each document, saving the result in a different file.</p><p>In the examples, using <b>xsltproc</b> the commands would be:<pre class="literallayout">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</pre>See <a href="#modulardoc" title="Example of modular files">the section called “Example of modular files”</a> for details on how the modular.xml file is handled.</p></li><li><a name="N2953"></a><p>Manually create a target database framework file. For an example, see <tt>targetdb.xml</tt> in the <tt>examples</tt> 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.</p><p>In the examples, the target database file looks like:<pre class="literallayout"><?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE t:targetset SYSTEM "../tools/targetdatabase.dtd">
projects / docbook-dsssl / commitdiff