Cross referencing provides huge gains for managing a large documentation set:

Cross references become even more useful when the processing machinery can automatically generate their cross reference text from information in the target of the cross reference (e.g., the title and chapter number in the target document).

These benefits of cross referencing come at a cost: that of managing the cross references. The standard ID/IDREF mechanism manages cross references quite effectively by validating them when the document is validated. Cross references implemented without ID/IDREF must be managed carefully if you don't want to degrade your documents. If a reader follows a link and lands in the wrong place (or no place), then they are less likely to trust the information they are reading. The cross referencing machinery must help maintain the accuracy of cross references, and it must be easy and automatic. This is particularly true when creating and maintaining large documentation sets. There are never enough eyes to check every cross reference against its target for each product release cycle or publication.

A full-featured cross referencing system should be able to do the following:

Can the cross referencing system described above be implemented in DocBook? There are four cross reference elements in DocBook, three of which cannot be used in such a system.

<sect1 id="Mousing">
  <title>Using a Mouse</title>
  <para>This is how you use a mouse</para>
</sect1>

XLink is designed to establish links between XML documents. XLink received the status of a full W3C Recommendation on 27 June 2001.^[1]

XLink uses the idea of global attributes in a separate xlink namespace to make elements in a DTD into XLink elements. Thus DocBook's olink could be made into an Xlink element by adding new attributes to the DocBook DTD. The full XLink spec provides for multiple links and bidirectional links between local and remote resources. It also lets you maintain link information outside the documents themselves in separate link bases. Doubtless many applications will arise to make use of these extended link features.

But XLink also supports simple xlinks, which is the type that document authors are currently used to. Simple xlinks point from the current element to another element, which could be in the same document or another document. A simple xlink can have other xlink attributes such as role, title, and actuate to modify its behavior. But it is always a single link from here to there.

It is the xlink href attribute that establishes the link. It looks similar to an HTML href attribute. The first part is a URI that points to a document. It could be a URL such as those used in HTML documents, or it could be a more general URN (Uniform Resource Name) with some mechanism for resolving the name to an actual resource. A second optional part, known as a fragment identifier, follows a # character and points to some location within that document. XLink permits fragment identifiers to use the powerful syntax of XPointers to locate information within the document. But it also supports the simplest form, which is just the value of an ID attribute within the target document. Thus our earlier olink example could be expressed as an xlink as follows:

<xref xlink:href="../OS-Userguide/book.xml#Mousing"/>

This assumes that a new xlink:href attribute has been added to the xref element in the DTD.

As you can see, this direct syntax is considerably simpler than the indirect references that olink had to resort to for making links between XML documents. This syntax establishes an unambiguous logical link between the current document and a point in the other document.

But how is this xlink to be interpreted when the current document is processed into HTML? Since this is an xref element, the stylesheet is expected to generate the hot link text, but what should it say? Also, exactly what does the user see when they click on the link? It is unlikely the author intended the reader to be dumped into the middle of an XML document to display raw XML markup like this:

<sect1 id="Mousing">
  <title>Using a Mouse</title>
  <para>This is how you use a mouse</para>
</sect1>

Both the generated text and the destination XML must be styled appropriately for the presentation of the current document. That's easy, just apply a stylesheet, right?

Well, it turns out that it isn't all that easy. A recent W3C Note^[2] outlines many of the complications that can arise, even with simple xlinks. Here is a sampling:

Several more complications could be added to the list:

The basic problem with xlink is how to resolve it to a styled result in your file. It appears you have to know their stylesheet and their profiling. You can't guess, you have to know with certainty what the results will be for your xlink to work.

If that is the case, then it becomes very difficult to link to the XML source document, which has several profiles in it and can be processed with several different stylesheets. Until that problem is solved, it is safer to cross reference to a rendered document with one profile and one style already selected. Cross references ultimately must land on a rendered version of the target if they are to be consumable.

But if we must link to a rendered document, why not just use <ulink>? Because ulinks are not flexible or robust enough. It is important to distinguish between the authoring process and the rendering process. You want your author to establish a logical link from one XML source document to another. You want a link that remains valid through several iterations of the product, and through several different renderings for print or online. A ulink that is valid in the current version may not be valid in the next. For ease of maintenance, the links should not require an editing pass through the document to update them for each new release. Rather, the processing machinery should resolve the abstract logical link to a rendered link for each release. An xlink or olink is the abstract logical link from XML to XML. An HTML href is a concrete working link.

At some point you render your document, that is, convert the XML to a final form for consumption. This conversion is done either ahead of time for packaging on the media, or on the fly in the server or browser. You want that logical link turned into a working link, using the actual rendered text, label, and URL of the rendered target. As was described above, it currently must resolve to a rendered version of the target document.

If cross references must finally resolve to a rendered document, then it is not necessary to process every target document from the current document just to resolve a link. If the appropriate information for linking was saved when the target document was rendered, then we can just use that information in the current document to form our links, and the target document would not have to be parsed. The datafile associated with olink in Norm Walsh's DocBook stylesheets provides such a mechanism.

The olink stylesheet (olink.dsl) generates a structured distillation of information about all the potential cross reference targets in a document. The target data is stored in a separate file from the document. Once the target data is separated from the document itself, it becomes more accessible for applications such as those described at the beginning of this document.

The target data file is an XML document that consists of a set of nested <div> elements. Each div element records the information for a single strucutural element in the document, such as book, chapter, section, etc. Other potential cross reference targets that are not part of the structural hierarchy are recorded in <obj> elements.

To meet these goals, it was necessary to add two new attributes to olink's attribute list. These new attributes appeared first in the DocBook XSL 4.2 DTD.

To form an olink, the author provides just two attribute values. For example:

<olink 
   targetdoc="OS-Userguide" 
   targetptr="UseMouse"/>

As with the existing olink, the author can optionally provide link text in the olink content. For an empty olink, the stylesheet is expected to generate the text for the link.

To identify the target document, a new targetdoc attribute is used. The existing targetdocent attribute could not be used here because it has attribute type ENTITY, and target documents are not handled as entities in this scheme. Instead, targetdoc is a simple identifier string that is resolved by the stylesheet.

To identify the target element, a new attribute targetptr is used. The existing olink attribute localinfo might have been used, but its name does not reflect its purpose. Together, the two new attributes make it clear that to form an olink you just have to identify the target document and the element within that document.

No other information is supplied in the olink markup, and no modespec or system entity declarations are used. When the XSL stylesheet encounters an olink with these attributes, it uses XSL templates to resolve the link.

Of course, the stylesheet cannot resolve such links on its own, so it must be supplied with sufficient information to do so. In the XSL implementation, the stylesheet is given a parameter (in a customization layer or at runtime) that points to a database file that provides that information. The advantage of supplying it at runtime is that it can be different for different builds of the document. A new release can refer to a new version of the target database. An HTML build can refer to an HTML rendering of the target documents.

The target database is a structured XML document with its own DTD. The data on potential cross references in a document is extracted using a special template in the XSL stylesheets. Then the data for the individual documents is merged into a single target database, and the resulting filename is passed to the DocBook stylesheet as a parameter.. The next section describes this data format.

A target database contains information for all the target documents the stylesheet may need during a given build. The overall structure looks like this:

<?xml version="1.0" encoding="utf-8"?> 
<!DOCTYPE targetset SYSTEM "/tools/docbook-xsl-1.52.1/common/targetdatabase.dtd" [
<!ENTITY ugtargets SYSTEM "/doc/userguide/target.db"> 
<!ENTITY agtargets SYSTEM "/doc/adminguide/target.db">
<!ENTITY reftargets SYSTEM "/doc/man/target.db">
]>
<targetset> 
  <targetsetinfo> 
    Description of this target database document,
    which is for the examples in olink doc.
  </targetsetinfo>

  <!-- Site map for generating relative paths between documents -->
  <sitemap> 
    <dir name="documentation"> 
      <dir name="guides"> 
        <dir name="mailuser"> 
          <document targetdoc="MailUserGuide"    baseuri="userguide.html"> 
            &ugtargets; (11)
          </document>
        </dir>
        <dir name="mailadmin">
          <document targetdoc="MailAdminGuide">
            &agtargets;
          </document>
        </dir>
      </dir>
      <dir name="reference">
        <dir name="mailref">
          <document targetdoc="MailReference">
            &reftargets;
          </document>
        </dir>
      </dir>
    </dir>
  </sitemap>
</targetset>
     

	Set the database encoding to utf-8 for the database, regardless of what encoding your documents are written in. The individual data files are written out in utf-8 so a database can have mixed languages and not have mixed encodings.
	Declare a system entity for each document target data file.
	Root element for the database is targetset.
	The targetsetinfo element is optional, and contains a description of the collection.
	The sitemap element contains the framework for the hierarchy of HTML output directories.
	Directory that contains all the HTML output directories.
	Directory that contains only other directories, not documents.
	Directory that contains one or more document output.
	The document element has the document identifier in its targetdoc attribute.
	For documents processed without chunking, the output filename must be provided in the baseuri attribute since that name is not generated by the document itself.
(11)	The system entity reference pulls in the target data for this document.

The data for each <document> is in a separate data file that is pulled in as a system entity reference. That data is structured in a manner similar to its target document. For every hierarchical element (book, chapter, section, appendix, etc.), there is a corresponding <div> element to record its target data. The nesting of div elements captures the parent-child relationships between elements. The value of each div element's id attribute would be captured, except that generated IDs are not included because they are not stable target names. In addition to the hierarchical elements, the collection includes all formal elements (tables, figures, etc.), and any block and inline elements that have ID attributes. These are stored as <obj> elements in the data set.

Here is an example of the target data for one document:

<?xml version="1.0" ?>
<div element="chapter" href="#publish" number="1" targetptr="publish">
  <ttl>Publishing DocBook Documents</ttl>
  <xreftext>Chapter 1</xreftext>
  <obj element="table" href="xsl-processors" number="1.1" targetptr="xsl-processors">
    <ttl>XSL Processors</ttl>
    <xreftext>Table 1.1</xreftext>
  </obj>
  <div element="sect1" href="#xsl-arch" number="" targetptr="xsl-arch">
    <ttl>DocBook XSL Architecture</ttl>
    <xreftext>the section called “DocBook XSL Architecture”</xreftext>
  </div>
</div>

In general, generated ID values are excluded from the data set because they are not reliable targets for cross referencing. Certain elements without ID may also be included, however. Those hierarchical elements without an ID attribute may provide some text or context for styling the link data in the cross reference. For example, a chapter might not have an ID attribute, but it still has a number and a title. When a cross reference is to a section that has an ID within that chapter, the link could be styled to say "see the section `Using a mouse' in Chapter 3: Peripherals".

The <div> and <obj> elements are generated using a special template included with DocBook XSL that extracts the target data from each document. The template is triggered with a stylesheet parameter named collect.xref.targets. See the DocBook XSL stylesheet documentation for more information on using the parameter.

The optional baseuri attribute is a prefix for hrefs generated for the target elements in this document. If an HTML document is output as a single HTML file, then the baseuri is that filename, and href attributes in the data file are of the form #elementid. The stylesheets combine the baseuri and href attribute values to form an olink. If the HTML document was chunked on output, then baseuri is usually blank. Then the href attributes in the data file are of the form filename.html#elementid.

The optional uri attribute can be used to precisely identify a rendered version of a document. It would allow you to keep several data sets for the same document rendered in different versions, profiles, or output formats. All would share the same targetdoc, since that is general name used by olinks find the document. But when you assemble your target database for a given production run, you can select one rendering of the document that you intend the olinks to resolve to. The naming scheme is user defined. Here is an example using a URN:

uri="urn:Caldera:OS-Userguide:3.2:en:html:caldera.ss3

This indicates the target data extracted from version 3.2 of Caldera's OS-Userguide, in the English version, in the HTML rendering, rendered by Caldera using its "ss3" stylesheet.

The processing of olinks with the DocBook XSL stylesheets can be summarized as follows:

Each of these steps is described in detail below.

The DocBook DTD supports large documents, all the way up to sets of books. If you want to form cross references among the books in a set using ID/IDREFs, then the set has to be in a single document. This is so unwieldy that most content managers break up the set into separate book system entity files, and only form the complete set at processing time.The individual books may be further broken down into chapter system entities.

System entities are not complete XML documents. If they contain a DOCTYPE declaration, then this will usually generate an error message when the system entity is pulled into the master document and processed.

The XInclude feature of XML permits each modular file to be a complete XML document. The master document uses <xinclude> elements, each of which uses an XPath expression to point to the root element of a modular file. This avoids the problem of the DOCTYPE declaration, which is left out of the inclusion.

Although each modular file may be a complete XML document, it still may not validate. If it has an xref or link element whose linkend attributes points to an ID in another file, then the modular document is not valid on its own. Both xref and link use the ID/IDREF mechanism, so the linkend must be in the current document.

If all the cross references to targets outside a modular component are converted to olink elements, then the file can be validated. That is because the targetdoc and targetptr attributes are not ID/IDREF, and so they won't be checked. The resolution of olinks takes place when the document is processed with a target database, not when the file is validated against the DTD.

Using olinks means a modular file can be processed on its own and produce reasonable output. Any links within itself would be resolved using ID/IDREF, and any links outside of itself would be written as olinks and resolved using the target database.

Of course, when a modular file is processed on its own, certain context information would be lost. The third chapter in a book would not know it was the third chapter when processed by itself, so its chapter number appear as "1". Likewise, all chapters would begin on page 1. But context information can be provided by the target database to correct these problems. The target database for the master document has all the information that's needed to establish the context for the current modular file. The stylesheet could be extended to supply the <div>'s number attribute. That number was generated the last time the target data file was generated for the whole document.

Although modular processing is convenient for development, it is not necessary when rendering the final document. To ensure complete sychronization among the modules, the master document can always be processed whole. This way you have reasonably accurate rendering in modular mode, and completely accurate rendering for final output. And it is the master document's target data file that would be used by other documents for linking.

Asynchronous processing means not having to process all your content at once to get cross references to work. You can use the target data from a previously processed document to form a link. The trick is to ensure that the target data won't change again after you process your document with the link to it.

If you are cross referencing among a collection of documents you are developing, then you have control over the target data. To generate a target database, you can freeze the documents and collect the target data. You can do this with a lock or a time stamp in a revision control system, or by simple agreement among developers. Each data collection becomes the reference point for the next cycle of development. At some point the collection is processed for a final time, the output is published, and the target database is archived for future reference.

An author can build their own output as they need to without having to build everything. Different departments or groups can work on their own documents, as long as they regularly synchronize the target data.

Going beyond parallel develop is developing documents in sequence. Later documents can safely make references to documents that have been published and their target data files frozen. You can even cross reference to documents whose source you have never seen, as long as you have access to the final target data file.

Olinks managed with this scheme permit you to cross reference to open source documents that are authored in DocBook XML. Often open source documents are the most authoritative on a subject, or at least on the software they document. Most are published in isolation, even if they are dependent on other software, since they have no means of connecting to other documents. Many could at least make use of active links to reference pages for the operating system they run on.

Open source software can also be assembled like building blocks into larger applications that integrate the components into a system. The documentation for the application needs to cross reference to the component docs. Without such links, the application doc needs to duplicate the information, which introduces more development and maintenance work for the authors.

If the DocBook source files are available, and you are rendering those docs, then you can extract the target data yourself to add to your target database. Since open source docs are generally versioned, you can easily tell which version of content you are linking to. Since you are creating the rendering, you know the rendering version as well.

The distributor of the doc will often ship rendered versions along with or instead of the XML source. If the distributor builds a target data file for each rendering to include in the distribution, then that can be added to your target database. Even if the XML source is not included in the distribution, links can be made to the rendered docs.

If the target data is produced as a side effect of rendering the document (controlled by a command line parameter), then the data can be generated regularly. When the final rendering is done for release, the data file can be simply included.

With the delays in getting general support for styling XML directly in web browsers, many content providers want to convert XML to HTML on the fly in the web server. But if your XML is a DocBook book, then the user will likely experience significant delays while the whole book is processed. There will be even greater delays while the entire book is delivered as HTML. You can chunk the output to reduce delivery time, but you still must process the whole document each time to resolve ID/IDREF cross references.

These delays can be reduced by breaking up the large book files into smaller modular files. and using olink with a document target database to resolve cross references within the document. Also, the target database can provide the context for chapter numbering and such for modular files. It is much faster to parse the target data file than it is to parse the entire book to establish the context.

So an XML repository that consists of small modular XML files linked together with olink and a target database could be rendered to HTML on demand. Whenever a document module in the repository is updated, it also has its target data updated in the database. When another document that targets the changed document is requested and processed, it uses the updated data to render the links.

When managing a collection of documentation, it is often the case that only certain documents are translated into other languages. If your documents are cross referencing among themselves, then some attention must be given to this issue. You don't want to form a cross reference to a translated document that does not exist.

This problem is solved by properly assembling your target database for your translated documents. The database used to process a given document starts with data for all the target documents you have translated. For any that are not translated, you substitute a version in a fallback language such as English. When the stylesheet processes olinks with such targetdoc values, they get a cross reference to the fallback document.