Olinks provide the tremendous power of cross referencing between documents, but they have a price. Olinks introduce dependencies between documents that are not an issue with standalone documents. The documents in a collection must "play together", and so they must follow a few rules.
If you change a document, you should always regenerate its
target.db data file. Once a collection is set up, this step is most easily done by processing a modified document with the parameter
collect.xref.targets set to the value
yes. That will make two passes through the document, the first
to regenerate the target data file and the second to generate the
If you change a document, then you may need to reprocess other documents that make cross references to that data file. Such dependencies are most easily tracked using Makefiles or Ant tasks, so the update process can be automated.
The output locations specified in the
sitemap element in the target database document must match where the HTML output actually lands. If they don't match, then the hot links you generate between documents won't reach the actual documents.
Whatever DocBook stylesheet (standard or customized) that you use to process a document for output should also be used to process the document for extracting the target data. Only then can you be sure that the style and content of the cross references will match the document.
If you use profiling (conditional text), you need to keep your target data separate for the different profiles. See the section “Olinks with profiling (conditional text)” for how to do that.
One of the most powerful features of the olink system is the
sitemap in the target database document. The sitemap is an XML structure that parallels the directory structure of your HTML output tree. By recording the output locations for all the documents in your olink database, the stylesheet can compute relative
hrefs for links between any two documents. The stylesheets compute the correct number of
../ steps to move up, and the right sequence of directory names to move down to locate a file. Relative
hrefs make your HTML highly portable, as long as you keep the same directory structure when you move the files.
Keep in mind that the sitemap records the HTML output hierarchy, not the XML source hierarchy. The location of your XML documents does not matter. Creating an output sitemap requires advanced planning for your document collection. You need to decide the name and location of each directory containing output. If you change where you put your HTML files, be sure to update your sitemap as well.
For the sitemap to work, you have to set the
current.docid parameter for each document you process. You set the
parameter value to the
targetdoc identifier for the current document. That informs the
stylesheet of the starting point for computing relative references,
since that information is not recorded in the document itself.
Here are some guidelines for understanding the sitemap feature. See Example 23.1, “Target database document” for examples.
The output directory hierarchy is represented by nested
dir elements in the sitemap. Each
name attribute must match the name of its output directory. Thus a sequence of
dir descendants can represent part of a pathname.
dir element can also contain a
document element. A typical setup will have terminal
dirs containing a single
document element, especially if that document is chunked. But a
dir element can contain a
document element and other
dir elements, if that is your directory structure.
targetdoc attribute value is the same document identifier used for olinking to that document. This identifier keys the stylesheet to the current document's location in the sitemap so it can compute relative paths from there to other documents.
The content of each
document element is the set of target data collected for that document. This is usually inserted as a system entity reference, although XInclude can be used as well (see the section “Using XInclude in the database document”).
Non-chunked documents may need a
baseuri attribute on their
document element to indicate the HTML filename. This is necessary if the
olink.base.uri parameter was not used to provide the same
collecting the document's target data. Don't use both the parameter
and the attribute, or both will appear in the generated hrefs.
sitemap element itself contains a single top-level
dir that serves as a container for the other
dir elements. The top-level
name attribute is irrelevant, since it is never used in
hrefs (it is always represented by
A directory can contain the output for more than one document. Expressed in the sitemap, this means a
dir element can contain more than one
document element. This feature is most useful for putting together several non-chunked documents. Chunked documents run the risk of duplicate filenames that would overwrite each other.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises