transclusion: attribute vs. element

["Bob Stayton" <bobs@sagehill.net>]

I'm following up on an action item to initiate a discussion of using
element ref vs. attribute ref for transclusions.  To bring you up to date,
I've included below my signature Jirka's description of the two approaches, together
with the minutes on that item from the last meeting.

I'm advocating using a ref element for these reasons:

a.  It more easily supports "content-only" inclusions, especially
as a mechanism for replacing entities.

b. Because of (a), it also more easily supports including a sequence of sibling
elements.

c. Its content model is always empty, as opposed to a regular
element that comes in two flavors: empty with @ref, or
containing regular content.

d.  I think it is conceptually easier to use: it is always replaced,
similar to an xi:include element.

e.  It is easier to find in an XML file.

Comments?

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


Jirka's email:

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 [JIrka's] 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.



excerpt from:
DocBook Technical Committee Meeting Minutes: 20 July 2011
=============================================================

7.  Transclusion in DocBook.

Jirka summarized his message [2] comparing an element approach
versus an attribute approach to transclusions as described
in his proposal[3].

Regarding the attribute mechanism, Jirka pointed out that
@copy does id fixup, but @ref does not.

Bob raised the distinction between predefined reusable content
declared inside a definitions element versus an inclusion
of an arbitrary external element.

Larry pointed out a need in either mechanism for transcluding
the content only of the referenced element.  That would be how
any reference to a def element would work, since def is not
to appear in the document flow.

Larry expressed a strong preference for a mechanism that
would replace entities, which the definitions element
provides.  But a def could be referenced either by a
ref element or by a @ref attribute, *if* there is an
implied rule that any reference to a def element is
always content only.

Another option is to add a @contentonly attribute,
similar to @copy, except it only transcludes the
content of the referenced element into the current element.

Bob pointed out that the ref element might be more flexible
when referencing a def that had a sequence of siblings.
A ref element is always replaced.

Norm asked some straw poll questions:

a.  Does anyone want to not pursue transclusions?  No one responded.
b.  Does anyone strongly favor ref element?  Bob responded.
c.  Does anyone favor attribute approach?  Nancy responded.

ACTION: Bob and Nancy to initiate a discussion on the mailing
list to further develop the issues between the two approaches.