Procedure 1. Using olink

1. Identify the documents

   Decide which documents are to be included in the domain for cross referencing, and assign a document id to each. A document id is a name string that is unique for each document in your collection. Your naming scheme can be as simple or elaborate as your needs require.

   For example, you might be writing mail agent documentation that includes a user's guide, an administrator's guide, and a reference document. These could be assigned simple document ids such as ug, ag, and ref, respectively. But if you expect to also cross reference to other user guides, you might need to be more specific, such as MailUserGuide, MailAdminGuide, and MailReference.

   You can add new documents to a collection at any time. You can also have more than one collection, each of which defines a domain of documents among which you can cross reference. A given document can be in more than one collection.

2. Add olinks to your documents

   Insert an <olink> element where you want to form a cross reference to another document. You supply two attributes in each olink: targetptr is the id value of the element you are pointing to, and targetdoc is the document id that contains the element.

   For example, the Mail Administrator's Guide might have a chapter on user accounts like this:

   <chapter id="user_accounts">
   <title>Administering User Accounts</title>
   <para>blah blah</para>
   ...

   You can form a cross reference to that chapter in the Admin Guide by adding an olink in the User's Guide like this:

   You may need to update your
   <olink targetdoc="MailAdminGuide" targetptr="user_accounts">user accounts</olink>
   when you get a new machine.

   When the User's Guide is processed into HTML, the text user accounts will become a hot spot that links to the Admin Guide.

   If instead you create an empty olink element with the same attributes, then the hot text will be generated by the stylesheet from the title in the other document. In this example, the hot text would be Administering User Accounts. This has the advantage of being automatically updated when the title in the Admin Guide is updated.

3. Generate target data files

   For each document in your collection, you generate a data file that contains all the potential cross reference targets. You do that by processing the document using your regular DocBook XSL stylesheet but with an additional parameter set. Here are examples showing the syntax for three different XSL processors for the same document.

   libxml2:
   xsltproc --param collect.xref.targets "'only'" docbook.xsl userguide.xml
   
   Saxon:
   java com.icl.saxon.StyleSheet userguide.xml docbook.xsl collect.xref.targets="only"
   
   Xalan:
   java org.apache.xalan.xslt.Process -IN userguide.xml -XSL docbook.xsl -PARAM collect.xref.targets "only"
   

   This command should generate in the current directory a target data file, named target.db by default. You can change the filename by setting the parameter targets.filename. The generated file is an XML file that contains only the information needed to form cross references to each element in the document.

   The DocBook XSL stylesheets contain the code needed to generate the target data file. The parameter collect.xref.targets controls how that code is applied, and has three possible values.

   no

   Don't generate the target data file (this is the default). Use this setting when you want to process just your document for output without first regenerating the target data file. This is the default since any documents without olinks don't need to do this extra processing step.

   yes

   Generate the target data file, and then process the document for output. Use this setting when you change your document and want to regenerate both the target data file and the output.

   only

   Generate the target data file, but don't process the document for output. Use this setting when you want to update the target data file for use by other documents, or when you set things up for the first time.

   In the command examples above, docbook.xsl should be the pathname to the DocBook stylesheet file you normally use to process your document for output. For example, that might be:

   /usr/lib/docbook/docbook-xsl-1.48/html/docbook.xsl

   If you use the DocBook chunking feature, then it would be the path to chunk.xsl instead. If you use a DocBook XSL customization file, then it should be pathname to that file. It will work if your customization file imports either docbook.xsl or chunk.xsl, and it will pick up whatever customizations you have for cross reference text. If you use different stylesheet variations for different documents, be sure to use the right one for each document. For example, you might use chunking on some long documents, but not on short documents. Use Makefiles or batch files to keep it all consistent.

4. Decide on your HTML output hierarchy

   To form cross references between documents in HTML, their relative locations must be known. Generally, the HTML files for multiple documents are output to different directories, particularly if chunking is used. So before going any further, you must decide on the names and arrangement of the HTML output directories for all the documents in your collection.

   Here are the output directories for our example docs:

   documentation
       |
       |-- guides
       |      |-- mailuser      contains MailUserGuide files
       |      |-- mailadmin     contains MailAdminGuide files
       | 
       |-- reference
              |-- mailref       contains MailReference files

   It is only the relative location that counts; the top level name is not used. The stylesheet will compute the relative path for cross reference URLs using the relative locations.

5. Create the target database document

   Each collection of documents has a master target database document that is used to resolve all olinks in that collection. The target database document is an XML file that is created once, by hand. It provides a framework that pulls in the target data for each of the documents in the collection. Since all the document data is pulled in dynamically, the database document itself is static, except for changes to the collection.

   Here is an example target database document, which is named targetdb.xml by default. In structures the documents in the collection into a sitemap element that provides the relative locations of the outputs for HTML. Then it pulls in the individual target data using system entity references to the files generated in step 3 above.

   <?xml version="1.0"?>
   <!DOCTYPE targetset SYSTEM "/tools/docbook-xsl-1.48/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; 
             </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>
        
   

   	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. Then cross references can be resolved using the form userguide.html#targetptr.
   	The system entity reference pulls in the target data for this document.

   When this document is processed, each target.db file is pulled into proper location in the hierarchy using its system entity reference, thus forming the complete cross reference database. That makes all the information available to the XSL stylesheets to lookup olink references and resolve them using the information in the database.

   The use of system entities permits the individual target.db data files for each document to be updated as needed, and the database automatically gets the update the next time it is processed.

   System entities also permit the use of XML or SGML catalogs to resolve the location of the various data files.

6. Process each document for output

   Now all that remains is to process each document to generate its output. That's done using the normal XSL DocBook stylesheet with an additional parameter, the database filename. The DocBook XSL stylesheets (version 1.XX and higher) know how to resolve olinks using the target database.

   Here are command examples for three XSL processors:

   libxml2:
   xsltproc --param target.database.document "'/projects/mail/targetdb.xml'" \
            --output /http/guides/mailuser/userguide.html
            docbook.xsl userguide.xml
   
   Saxon:
   java com.icl.saxon.StyleSheet -o /http/guides/mailuser/userguide.html \
            userguide.xml docbook.xsl \
            target.database.document "/projects/mail/targetdb.xml" 
            
   Xalan:
   java org.apache.xalan.xslt.Process \
            -PARAM target.database.document "/projects/mail/targetdb.xml" \
            -OUT /http/guides/mailuser/userguide.html
            -IN userguide.xml -XSL docbook.xsl 
            

   The only difference from the normal document processing is the addition of the parameter target.database.document, which provides the location of the target database file. As your document is processed, when the stylesheet encounters an olink that has targetdoc and targetptr attributes, it looks up the values in the target database and resolves the reference. If it cannot open the database or find a particular olink reference, then it reports an error.