Details to watch out for

Details to watch out for
	Chapter 23. Olinking between documents

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 normal output.
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.

Using a sitemap

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 dir element's name attribute must match the name of its output directory. Thus a sequence of dir descendants can represent part of a pathname.
A 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.
Each document element's 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 filename when collecting the document's target data. Don't use both the parameter and the attribute, or both will appear in the generated hrefs.
The 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.


Chapter 23. Olinking between documents		Olinking in print output