Transclusion in DocBook

Volume 14, Issue 17; 17 Apr 2011

The requirement to “transclude” documents, to incorporate them by reference rather than copying, is not uncommon in documentation systems.

Transclusion, transclusion
Oh, doc, pardon me for this crazy inclusion
I'm never, never, never going to 'clude again
Pump the entity in me gently
With apologies to Jimmy “Nervous Norvus” Drake

Documentation systems, especially systems like DocBook that encourage reuse, almost always have to deal with the issue of “transclusion”, including documents by reference rather than copying.

Historically, the easiest way to do this in XML was with external parsed entities. However, in a post-DTD world, there's a desire by many to move entirely away from DTD syntax. A more modern approach is to use XInclude.

Unfortunately, neither of these approaches address all the problems that arise. What's more, XInclude is not a particularly efficient mechanism for dealing with reuse on a smaller scale.

The DocBook Technical Committee has spent some time discussing these issues and Jirka Kosek has done a fabulous job of summarizing both the requirements and possible solutions. (Apologies for not having drawn broad, public attention to these documents sooner.)

I have mixed feelings about the transclusion problem. On the one hand, it's a very clear, real problem. On the other hand, it's not unique to DocBook and getting it right would require some quite significant support from tool vendors.

So I wonder if it shouldn't be addressed deeper in the stack, perhaps for XML as a whole. But also, if there's no support from tool makers, there's not much point specifying a solution at any level.

I think it's important to promote a solution that's both useful and practical. If you have comments, pro or con, please post them on the DocBook mailing list.


what about an XLink that doesn't suck? XLink was a very good idea very poorly executed. i remain convinced that something along the conceptual lines of XLink (general-purpose hyperlinking with flexible and machine-readable link and resource semantics) would be very useful.

—Posted by Erik Wilde on 18 Apr 2011 @ 04:32 UTC #

I completely agree with Erik Wilde’s comment!

XLink is one of the most genius failures in the history of XML. Apart from DocBook5—thank you Norm!—I don't see XLink in use anywhere. And that saddens me.

The reasons for this are no doubt complex and numerous. But I think a significant contributor, seemingly unnamed for whatever reason, is that XLink was way ahead of its time. The technological and sociological ecosystems just weren't ready when it was released.

But what about right now?

Right now, I strongly believe everything is much better poised right now to receive XLink. If XLink were revived and had a grammar overhaul, it could improve the entire XML ecosystem. A normative schema would go a long way too. (The spec offers a non-normative schema; but if one encounters an issue that may or may not be due to a “non-normative” or “unofficial” schema, IMO that’s just making XLink unnecessarily more difficult to adopt than it needs to be.)

With the widespread use of Saxon9, and both Michael Kay and Norm Walsh being W3C spec veterans, I’d be willing to be that if an effort were made to add a next-gen XLink support to Saxon, the “no support from tool makers” problem would go away.

For anyone interested, I recommend Elliotte Rusty Harold’s pages on XLink and XPointers. (I particularly love the section on Linkbases!☺)

—Posted by Tony on 12 May 2011 @ 04:03 UTC #