Modular cross referencing

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:

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:

Here are some scenarios to consider when using olinks with modules: