Transclusion

Volume 13, Issue 53; 15 Dec 2010

Transclusion comes in many flavors, some more easily supported than others.

XML offers a number of transclusion mechanisms, some better supported than others. There are DTD mechanisms, there are general solutions like XInclude, and more language-specific solutions like DITA conref.

These mechanisms are not without their problems. Entities are problematic in some environments and XInclude relies on XPointer which suffers from a dearth of addressing schemes. This last point is precisely what put this issue back on the DocBook Technical Committee's radar. In addition, none of these mechanisms even attempt to address the issues that transclusion can introduce in the transcluded document, most obviously the problem of duplicate ID values.

In an effort to address the RFE, Jirka lead the TC through the process of determining the DocBook transclusion requirements (which are really, I think, the requirements of any documentation schema) and developed a proposal that addresses those requirements. Thank you, Jirka!

Those documents are now available. They've been available as attachments buried in the mail archives for a while, so it's really a question of conveniently availability. If you're interested in the problem, I encourage you to read

For my part, speaking personally and not as the TC chair, I have a couple of concerns that I hope public review will clarify.

I think the solution is fairly complicated (because the problem is fairly complicated). So my first concern is about implementation. Will authors understand it and be able to use it easily? Will vendors implement it?

My other concern is more vague. This feels like something more general than DocBook, it seems like something that other schemas might want to reuse, so I wonder if it belongs in DocBook specifically. I suppose if authors want it and vendors will implement it, we can let other folks copy it.

In any event, your comments are most welcome. On the DocBook list, if that's possible, or here. But on the list if you can, please.

Comments

Yes it's more general than DocBook; that's why we have XInclude.

If XPointer doesn't work, then can you invent a new addressing mechanism that fits better? XInclude is not limited to XPointer after all.

Duplicate IDs seem like something that could be fixed up in an XInclude 2 rather than inventing a new spec.

But if you do invent a new spec, please make it orthogonal to DocBook itself. I.e. like XInclude DocBook should not depend on it, and it should not depend on DocBook.

—Posted by Elliotte Rusty Harold on 22 Jul 2011 @ 04:05 UTC #