Comparision of attribute/element based transclusion proposal

[Jirka Kosek <jirka@kosek.cz>]

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: jirka@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
------------------------------------------------------------------

OpenPGP digital signature