Olinks permit you to form cross references among your modules without generating validation errors when you edit or process your modules individually. Olinks are described more completely in Chapter 24, Olinking between documents. This section describes the specifics of using olinks with modular DocBook files.
Without olinks, authors are forced to put all of the content that they want to cross reference among into one huge document, such as a
set. To avoid validation errors, such authors would always have to edit or process the entire set each time.
With olinks, you have control over the size of the documents you produce from your collection of modules. For example, you may decide that you generally produce books, so you will be cross referencing among your books. Or you might be producing individual articles, and you need to be able to reference other articles.
Keep in mind that while olinks are formed between file modules, they are resolved between produced documents. That's because the resolution of an olink depends on the context in which a module is used. For example, if your modules consist of chapters and you use a chapter module in more than one book, then the chapters might have different chapter numbers in the different books. A cross reference that displays the chapter number needs to get the right number for each book, and that number is not contained in the chapter module itself. Also, resolution in HTML output requires the output filenames and directories for the HTML files to be known.
To use olinks, you need to plan how your content is assembled into documents, and how those documents relate to each other. During processing , each document has a target data set generated for it that records all of the potential cross reference targets in that document. Those data sets are then collected into a target database, which is used to resolve olinks among the documents included in the database.
If you are only producing one set of documents from your collection of modules, then you need only one target database. But you can have more than one target database. That's needed in any of these situations:
You want to produce two versions of a document with different modules included.
You want to produce two versions of HTML output for a document, and they use different chunking levels, filenames, or output directories.
You want to produce different collections of output and control the scope of cross referencing in each collection.
To form an olink, you supply identifiers for the element you are targeting and the document that contains it. The element identifier is its ID attribute value, and it is recorded in the
targetptr attribute of the olink. This is similar to putting an ID value in a
linkend attribute of an
xref element. The document identifier is recorded in the
targetdoc attribute of the olink. The document identifier is not in the document itself, but is assigned when forming the target database of documents.
How you manage your document identifiers depends somewhat on how you are combining your modules. Keep these points in mind:
You can have more than one target database.
In a given target database, each document identifier must be unique.
Changing a document identifier may not be easy once it has been in use. The document identifiers are written into the
targetdoc attribute of olinks in the documents. If you have many of them, changing them all is a nontrivial exercise.
Here are some scenarios to consider when using olinks with modules:
If you do not reuse your modules, then each document is a unique collection of modules and can have a fixed document identifier. All documents can be in the same target database. And each olink can reliably use one of those document identifiers in its
If you reuse modules in distinctly different documents, then each document can still have a fixed document identifier, and all documents can still be in the same target database. It is ok for an element and its ID to appear more than once in a target database, as long as each is under a different document identifier. Now you have to be more careful in how you write your olinks. They have to point to one finished document or the other, even though they are pointing to the same source module.
If you reuse modules in different versions of the same document, then you will probably need to create more than one target database. This permits you to use the same document identifier for the different versions, yet they do not conflict in the database. Your olinks can be written with that single document identifier. Which version they resolve to is determined at processing time by which target database is used to resolve olinks.
If you have a completely free form collection of modules and everything is resolved at processing time, then you can use text entities in your olink
targetdoc attributes. For example:
<olink targetptr="UsingMouse" targetdoc="&mousebook;" />
In this example, you know you are pointing to the
UsingMouse ID value on an element in a module. But when you write the olink, you do not know what document that module appears in, because that is not established until processing time. All you know is there had better be some document that contains the mouse information, and you refer to that document identifier in the abstract with a text entity. When you process this olink, the
mousebook text entity must be assigned a value that resolves to the right document identifier in the target database being used during that processing run. This is very flexible, but also more complex, and more likely to lead to unresolved olinks unless you pay careful attention to details.
If you are using DocBook 5, then you can use almost any inline element as an olink by using the universal linking attributes available in DocBook 5. See the section “Universal linking in DocBook 5” for more information.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises