Menu
▾
▴
[docbook-checkins] CVS: contrib/xsl-custom/newolink OlinkHOWTO.html,NONE,1.1
|
From: Robert S. <bob...@us...> - 2001-10-23 07:38:36
|
Update of /cvsroot/docbook/contrib/xsl-custom/newolink
In directory usw-pr-cvs1:/tmp/cvs-serv12114
Added Files:
OlinkHOWTO.html
Log Message:
Documentation on how to use the new olink toolkit.
--- NEW FILE ---
<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:bo...@ca...">bo...@ca...</a>></tt></div></div></div><div><p class="copyright">Copyright © 2001 Robert Stayton</p></div><div><p class="pubdate">18 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:
custom.xsl
targets.xsl
And edit this similar line:
<xsl:import href="../../docbook-xsl-1.45/html/chunk.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
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">
<t:targetset xmlns:t="http://sagehill.net/xsl/target/1.0">
<t:targetsetinfo>Information about this example
targets databas</t:targetsetinfo>
<t:document
targetdoc="ug"
uri="urn:x-omf:sagehill:userguide:1.0:en:html"
baseuri="../UserGuide/userguide.html"
href="../examples/ugtargets.xml" />
<t:document
targetdoc="ref"
uri="urn:x-omf:sagehill:ref:1.0:en:html"
baseuri="../Reference"
href="../examples/reftargets.xml" />
<t:document
targetdoc="modular"
uri="urn:x-omf:sagehill:modular:1.0:en:html"
baseuri="../Modular"
href="../examples/modtargets.xml" />
</t:targetset>
</pre></p><p>The top level element of the target database is a <tt>targetset</tt> element. In contains an optional <tt>targetsetinfo</tt> element to record a description of this particular database, and one or more <tt>document</tt> elements. Each document element has the following attributes:</p><div class="variablelist"><dl><dt><a name="N2983"></a><span class="term"><tt>targetdoc</tt></span></dt><dd><p><a name="N2987"></a>Document identifier for this document. It must be unique among your document set.</p></dd><dt><a name="N2990"></a><span class="term"><tt>uri</tt></span></dt><dd><p><a name="N2994"></a>Optional document identifier that is globally unique. This attribute comes into play only if you are publishing your target database as well as your documents, so that others may form cross references to your published documents. This naming scheme is still under development.</p></dd><dt><a name="N2997"></a><span class="term"><tt>baseuri</tt></span></dt><dd><p><a name="N3001"></a>In HTML output, this is the first part of each URL to be generated for this document. This forms a prefix for each <tt>href</tt> attribute for the resolved cross reference. The suffix is the <tt>href</tt> that would normally be generated for the target element by the DocBook stylesheet.</p><p>For a document that is processed whole (not chunked), the <tt>baseuri</tt> is the path to the single HTML output file. Then cross references to the document that are generated by the DocBook XSL stylesheets of the form <tt>#fragment</tt> are appended to form the complete HTML <tt>href</tt>.</p><p>For a document processed into chunked output, the <tt>baseuri</tt> is the path to the directory containing the collection of output files. Then cross references that are generated by the DocBook XSL stylesheet of the form <tt>filename.html</tt> (with an optional <tt>#fragment</tt>) are appended to form the complete HTML <tt>href</tt>.</p></dd><dt><a name="N3038"></a><span class="term"><tt>href</tt></span></dt><dd><p><a name="N3042"></a>Pathname to the file containing the target data set for this document. This file was generated using <tt>targets.xsl</tt> (or <tt>chunktargets.xsl</tt> for a chunked document).</p></dd></dl></div><p>When you start to set up, you might want to form a table like this one to summarize the information you'll need for all your documents. You can use that to write your targets database file.</p><div class="table"><p><a name="N3055"></a><b>Table 1. Document Information</b></p><table summary="Document Information" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>Document File</th><th><table class="simplelist" border="0" summary="Simple list"><tr><td>Document ID</td></tr><tr><td>(targetdoc)</td></tr></table></th><th><table class="simplelist" border="0" summary="Simple list"><tr><td>Output Directory</td></tr><tr><td>(used in baseuri)</td></tr></table></th><th><table class="simplelist" border="0" summary="Simple list"><tr><td>Target Dataset</td></tr><tr><td>(href)</td></tr></table></th><th> </th></tr></thead><tbody><tr><td>userguide.xml</td><td>ug</td><td>UserGuide</td><td>ugtargets.xml</td><td> </td></tr><tr><td>ref.xml</td><td>ref</td><td>Reference</td><td>reftargets.xml</td><td> </td></tr><tr><td>modular.xml</td><td>modular</td><td>Modular</td><td>modtargets.xml</td><td> </td></tr></tbody></table></div></li><li><a name="N3157"></a><p>In your document files that will be using olinks, alter the DOCTYPE declaration to add two new attributes to the olink element:<pre class="literallayout"><!DOCTYPE chapter SYSTEM "../../docbook412/docbookx.dtd" [
<!ENTITY % local.olink.attrib
"targetdoc CDATA #IMPLIED
targetid CDATA #IMPLIED"
>
]></pre></p></li><li><a name="N3165"></a><p>Add olinks to your documents as needed to create cross references to other documents. If you want the olink to generate the cross reference text the way an <tt>xref</tt> element does, then leave the content empty. It you want your own text as the hot spot, then add that text as the content of the olink element.</p><p>Each olink must have three attribute values to form a cross reference:<div class="variablelist"><dl><dt><a name="N3175"></a><span class="term"><tt>type="stylesheet"</tt></span></dt><dd><p><a name="N3179"></a>This fixed attribute value distinguishes this new type of olink from the original type that used other attributes to identify the link. It indicates that the XSL stylesheet is to resolve the olink, using the cross reference database that is passed to it as a parameter.</p></dd><dt><a name="N3182"></a><span class="term"><tt>targetdoc="<i><tt>docid</tt></i>"</tt></span></dt><dd><p><a name="N3189"></a>Identifies which document has the target of the cross reference. This must match a <tt>targetdoc</tt> attribute value in your target database.</p></dd><dt><a name="N3195"></a><span class="term"><tt>targetid="<i><tt>elementid</tt></i>"</tt></span></dt><dd><p><a name="N3202"></a>Identifies the id value of the element being referenced in the target document.</p></dd></dl></div></p><p>Here are two olink examples, one with content and one without:<pre class="literallayout"><olink type="stylesheet"
targetdoc="ref"
targetid="param.html.stylesheet">
html.stylesheet</olink>
<olink type="stylesheet"
targetdoc="ref"
targetid="param.html.stylesheet.type"/>
</pre></p></li><li><a name="N3211"></a><p>Process your document using the <tt>custom.xsl</tt> stylesheet for single file output, or use <tt>chunkcustom.xsl</tt> for chunked output. Whichever you choose should match the chunk style when you extracted the target data set for the document.</p><p>You'll also need to pass as a parameter the filename of your target database. The parameter name is <tt>target.database.document</tt>.</p><p>Here is how one of the example documents is processed with <b>xsltproc</b>:<pre class="literallayout">
xsltproc --param target.database.document '"../examples/targetdb.xml"' \
--output ../UserGuide/userguide.xml \
../tools/custom.xsl userguide.xml </pre></p></li><li><a name="N3239"></a><p>Browse your HTML output to make sure the olinks work. Here is how an olink is rendered in HTML:<pre class="literallayout"><a href="../Reference/rn01re03.html">html.stylesheet.type</a></pre></p></li></ol></div></div><div class="sect1"><a name="modulardoc"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="modulardoc"></a>Example of modular files</h2></div></div><p>The <tt>examples</tt> directory also contains a third document (<tt>modular.xml</tt>) that illustrates how you can use XInclude and olinks to create a large document from several smaller document modules. Modular files allow you to break up large unwieldy documents into manageable units, or reuse boilerplate material in several documents.</p><p>In traditional XML and SGML, you can break a large document into a single container document (say, at the book level) and several system entity files (say, one for each chapter). The main document consists primarily of a sequence of references to the system entities. The problem with this arrangement is that a system entity file is not a valid XML document because it cannot contain a DOCTYPE declaration. If it does, then most processors will generate an error when the module is pulled into the main document. Not having a DOCTYPE also means you cannot edit a modular file with a validating editor. You either have to temporarily add a DOCTYPE, or use an editor that fakes having a DOCTYPE. Even if you somehow add the DOCTYPE, you run into another problem with cross references. When a cross reference points to another chapter, it will fail validation. That is because the <tt>linkend</tt> attribute used in <tt>xref</tt> and <tt>link</tt> is an IDREF that must resolve to an ID in the current document. You can choose to ignore these kinds of validation errors, but it is cleaner if your files have no validation errors.</p><p>These problems are eliminated if instead of system entities you use modular XML files and olinks. The <tt>examples</tt> directory contains a modular book example in three files:<pre class="literallayout">
modular.xml Master book document.
preface.xml Preface document.
introduction.xml Chapter document.</pre></p><p>The modular book uses XInclude to pull in XML content from individual chapter files. The main <tt>modular.xml</tt> file looks like this:<pre class="literallayout"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book SYSTEM "../../docbook412/docbookx.dtd">
<book id="IncludeTest">
<bookinfo>
<title>Testing modular doc</title>
</bookinfo>
<xi:include href="preface.xml#mypreface"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="introduction.xml#intro"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</book>
</pre>The use of XInclude permits each chapter file to be a full XML document and not just a system entity. The <tt>preface.xml</tt> file looks like this:<pre class="literallayout"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE preface SYSTEM "../../docbook412/docbookx.dtd" >
<preface id="mypreface">
<title>Preface in modular doc</title>
<para>
My only paragraph in my preface so far to see
how it will work when I form an olink to
<olink targetdoc="incl" targetid="intro" type="stylesheet"/>
</para>
</preface>
</pre></p><p>When the <tt>modular.xml</tt> file is processed, the <tt><xi:include></tt> elements are resolved and the content pulled in. This is similar to a system entity reference, except an XInclude can be more selective. The href <tt>preface.xml#mypreface</tt> means to select the element in <tt>preface.xml</tt> with ID <tt>mypreface</tt>. That avoids pulling in the <tt><!DOCTYPE></tt> declaration, which generates an error.</p><p>The use of XInclude means each chapter file can have <tt><?xml></tt> and <tt><!DOCTYPE></tt> declarations, so it can be edited and processed individually without having to use a wrapper file to convert a system entity into a full document. To remove the problem of ID/IDREFs not resolving to other chapters, use <tt>olink</tt> instead of <tt>xref</tt> or <tt>link</tt>. The olinks are not validated, but neither do they generate errors. You test if an olink is not resolving when your main document is processed.</p><p>Processing a modular chapter file has one limitation. If chapters in a book are numbered, then processing a single chapter out of context will always number it as "Chapter 1". You don't get the proper numbering unless you process the main document. That is why the target database is generated by processing the main document that pulls in all the chapters so they are numbered correctly. Of course, this limitation can be worked around by setting up the processing environment to pass the chapter number as a parameter that the stylesheet can use.</p></div><div class="sect1"><a name="N3352"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="N3352"></a>Using Makefiles</h2></div></div><p>Because olinks create dependencies between documents, the use of Makefiles can facilitate the mangagement of those dependencies. For example:<div class="itemizedlist"><ul><li><p><a name="N3358"></a>The output for a given document is dependent on the target data file of every document it cross references. In the example files, the userguide is dependent on <tt>reftargets.xml</tt>.</p></li><li><p><a name="N3365"></a>A target data file is in turn dependent on the document it is generated from. So <tt>reftargets.xml</tt> is dependent on <tt>ref.xml</tt>. If a document is made up of modular files, then it is dependent on all of the modular files.</p></li></ul></div></p><p>See the <tt>Makefile</tt> in the <tt>examples</tt> directory for one implementation of these dependencies.</p></div></div></body></html>
|