Modular cross referencing

Modular cross referencing
	Chapter 22. Modular DocBook files

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 23, 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:

A target database establishes the scope of olink cross referencing. That means it defines what documents can be reached by olinks.
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 don't 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 targetdoc attribute.
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 don't 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 don't know what document that module appears in, because that isn't 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.


Validating with XIncludes		Modular sections