Re: [docbook-tc] Very rough proposal for DocBook transclusions

[Jirka Kosek <jirka@kosek.cz>]

Rowland, Larry wrote:

>   1) Simplest: Strip the ID from the referenced element.  This works
>      for the inline inclusion problem (that seems to be aimed at the
>      same use-case that entities were aimed at).  It may not work for
>      references to blocks of content, particularly if there are IDs 
>      inside the block.

In the latest proposal this is possible by specifying

<ref idfixup="strip" fileref="..."/>

>   2) Replace the ID of the referenced element with an ID provided on
>      the referencing element.  Again, this does not handle content
>      that has IDs included inside it, but it allows referencing the
>      element (like an admonition that needs to be repeated in a document
>      and also needs to have local references to it.  However, it can
>      be extended as described in the next option.  We indicated this
>      should be done by simple providing the ID on the referencing 
>      element.

xml:id from ref now automatically replaces xml:id on the transcluded content

<ref xml:id="foo-bar" fileref="..."/>

You can combine it with 1) and strip all other IDs as well:

<ref xml:id="foo-bar" idfixup="strip" fileref="..."/>

>   3) Replace the ID of the referenced element with an ID provided on
>      the referencing element AND use the new ID to prefix all IDs in
>      the transcluded block.

It occured to me that it might be better to allow arbitrary prefix,
which of course can be same as xml:id.

<ref xml:id="foo-bar" idfixup="prefix" prefix="foo-bar" fileref="..."/>

But we can add new value to idfixup, something like "prefix-with-id" to
have shortcut for this case.

>  This means you also have to modify
>      references within the transcluded block that reference IDs in
>      the block, but not references to IDs outside the block.  

This is more or less default behavior in my proposal. This can be
further controleld by linkscope attribute.

> The alternative to these three options was to pass through the ID on 
> the referenced element and do nothing to IDs inside it, which was not
> a problem if the block was only being included once, as opposed to
> being included repeatedly in a document.

You can do this by:

<ref xml:id="foo-bar" fileref="..."/>

> Both options 2 and 3 could be controlled by an attribute rather than by
> the presence of the ID, but the ID had to be provided anyway, so it
> didn't seem like too much of a stretch.  To deal with all four options
> it may be best to have an idpolicy attribute (probably with a default
> value of option 1, since inline use could become common as a replacement 
> for entities) to control this.  Not sure really, since policy 1 was in a 
> system that didn't have policy 2, so we ended up only having to deal with 
> either not modifying IDs or modifying them based on the ID attribute being 
> present.

Current proposal has defaults idfixup="auto" and linkscope="near" which
has sort of "magic" behavior that should work "properly" in most
situations. But I might be wrong and we can specify different behavior
as a default.

-- 
------------------------------------------------------------------
  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