Hi folks, please find below my belatedly finished action item. Please feel free to add more advantages/advantages to each option.
Jirka Comparison of approaches to transclusion markup ================================================ Element based transclusions as described at http://docbook.org/docs/transclusion/2011-04-20/ -------------------------------------------------------------------------------------------- This approach uses dedicated <ref/> element for transcluding content. Implementation in schema: <ref/> has to be allowed almost everywhere. In past similar customization was done for XInclude, but <ref/> has to be added into more places. Advantages: - single element will be used for transclusions, which makes processing little bit easier - schema change is quite small - schema change is equally doable in RELAX NG, W3C XML Schema and DTD Disadvantages: - some content models will became too loose, because <ref/> will be allowed everywhere - validation will be more complicated as for each <ref/> it should be checked whether transcluded content is valid at the transclusion point Attribute based transclusions as described at http://docbook.org/docs/transclusion/2011-04-20/#d6e445 ----------------------------------------------------------------------------------------------------- This approach uses additional attributes @ref/@copy on existing DocBook elements. Implementation in schema: The simplistic implementation is just addition of few additional global attributes. However better would be to create schema where each element can exclusively contain either existing content model or only new transclusion attributes (using RELAX NG co-occurrence feature). Advantages: - schema using co-occurrences will provide quite good validation and code completition out-of-the box - in most cases for basic validation it would be enough to check equivalence of top-level transcluded element with element used for transclusion Disadvantages: - co-occurrences are not supported by W3C XML Schema (1.0) and DTD; additional checks has to be done in Schematron for proper validation - co-occurrence based schema has to redefine pattern for each DocBook element My observation -------------- I think that it is slightly better to use attribute based approach. Most problems with schemas can be solved automatically. We can create list of element for which transclusion should be allowed. This list will contain almost all DocBook elements, except probably some "leaf" elements like <primary/> for which probably doesn't make sense to use transclusions. From this list we can automatically create: 1. Transclusion-aware schema like: include "docbook.rnc" # for each transclusion enabled element define alternative with # transclusion attributes, e.g.: db.para |= element db:para { attribute copy { ... }, attribute ref { ... }} ... 2. Schematron rules enforcing exclusivity of transclusion attributes (this schema will be used with DTD/W3C XML Schema), e.g.: <rule context="*"> <report test="(@ref or @copy) and (* or attribute::*[not(self::copy or self::ref)] "> You can use either tranclusion attributes or specify content directly </report> </rule> However attribute based proposal still lacks some features, and it is question if its simplicity outweighs those missing features. -- ------------------------------------------------------------------ Jirka Kosek e-mail: ji...@kosek.cz http://xmlguru.cz ------------------------------------------------------------------ Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing ------------------------------------------------------------------ OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member ------------------------------------------------------------------
signature.asc
Description: OpenPGP digital signature