OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Re: XLink and OLink in Docbook 5

When I embarked on my efforts to rewrite olink in 2001, I wrote a background
paper on olinks and their relationship to XLink.  You can still read it at:


Most people were seeing XLink as a means to connect one XML file with
another. In the abstract, it sounds easy.  But people don't read XML
documents, they read HTML and PDF files rendered from XML documents.  My
paper references Norm's W3C Note that describes the difficulty of rendering
an XLink.


When you render your document to HTML, what should you do with an XLink that
points to an XML file?  If you do something like this:

<a href="myotherdoc.xml#mytarget">

then you are expecting the reader's browser to format the XML file.  With
what stylesheet?  Perhaps a stylesheet is referenced in a processing
instruction at the top of the XML file, and some browsers will render it.
But what if the XML file is modular and uses XIncludes?  If you have to
point to a specific XML module, then it is out of context.  But current
browsers won't process XIncludes (will they?).  What if the document you
meant to point to was supposed to be profiled?  There is no way to specify
profiling parameters in XLink syntax.

My own conclusion was that simple situations could work, but the general
case of rendering XLinks was very difficult.  Too hard for me, anyway.  I
decided that the only way to resolve links between DocBook documents was to
resolve them between rendered documents.  The current XSL implementation
uses an olink database containing information about rendered documents,
after the XIncludes are processed and the profiling is done.

But I didn't want the syntax in the olink to have to point to a particular
PDF file or HTML file like a ulink.  Such links are very fragile in source
documents.  So the olink is still abstracted, using a document identifier
(targetdoc) and fragment identfier (targetptr) to identify a unique target
in some pool of targets.  The pool is decided at build time, though.  A
given document identifier means only what you want it to mean when you
process the document.  The target pool might be filled with HTML targets in
one build, and PDF targets in another.  This level of indirection is
critical to the success of olinks. You can render olinks as needed at build
time, without having  to edit your source documents to update your olinks.
They even can survive translation.

For DocBook V5, the XLink syntax can use a URN as the href, as Jirka points
out.   A URN is an abstract name that requires a URN resolver to locate the
resource.  For DocBook olinks, it becomes the equivalent to the document
identifier.  With a #fragment_identifier taking the place of the targetptr
attribute, you have the complete equivalent to the current olink.

I think the stylesheets should assume an XLink starting with "urn:" needs to
be looked up somewhere, and without further instructions it should assume it
is an olink that gets resolved by the olink mechanism. If you then put
something like  <document targetdoc="urn:blah:blah"> in your olink database,
then it will be easy to implement.  This syntax still provides that level of
indirection, where a given urn means just what you want it to mean at build

Bob Stayton
Sagehill Enterprises
DocBook Consulting

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]