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

[Jirka Kosek <jirka@kosek.cz>]

Norman Walsh wrote:
> Jirka Kosek <jirka@kosek.cz> writes:
>> I'm not sure if I will be able to send more complete proposal before telcon.
> 
> Thanks, Jirka. A few proofreading nits:
> 
> s/very bad, bud/very bad, but/
> s/xpointer(id('product-name')/text())/xpath(id('product-name')/text())/

Thanks.

> With respect to the DocBook Transclusion Proposal, I think I'd prefer
> <ref name="product-name"/> to <ref>product-name</ref> just because it
> will tend to minimize whitespace issues in the markup.

My motivation of using element content instead of attribute was that in
visual XML editors it might be easier to type in reference name -- in
order to edit attributes you have to usually open some special dialog
box while element content can be typed directly. Also name of reference
is defined as xsd:NCName so any whitespace will be ignored anyway.

But I have no strong preference on this.

> Do you have any ideas about what to do about the duplicate ID problem?

Yes, I just haven't enough time to write them down. With a risk of
oversimplification there are quick and rough ideas:

Transclusion of XML document without any special ID processing:

<ref fileref="shared-module.xml"/>

Module is transcluded and IDs are automatically adjusted in a way that
all links inside this module do not cross to other parts of document:

<ref fileref="shared-module.xml" linkscope="always-local"/>

Of course, in reality some links will be pointing outside the module.
Previous transclusion will report errors in such situation. This case
could be handled with another mode where all links that can be resolved
locally are kept local to this module and only unresolved links can
point outside of module:

<ref fileref="shared-module.xml" linkscope="local"/>

Also in this mode link target is chosen in a way that element with
matching ID is found in a subtree rooted at nearest possible ancestor.
(I think that this mode should be probably default one.)

These two transclusion modes are useful when including some relatively
selfcontaining content. When document is created with many modules,
heavily interlinked with a risk that some module is used several times
in a different location then third mode is here:

<ref fileref="shared-module.xml" linkscope="global"/>

If there are some ID clashes then global setting can be used to rename
all IDs (to some unique combination of module-occurence identifier
combined with original ID) or keep ID of first occurence and rename only
later appearing duplicate IDs.

Default setting for this idfixup property should be probably to keep
original ID on the first occurence. There should be possibility to
switch this off completely or rename all IDs.

(In the document I have sent yesterday there is
attribute idfixup { "none" | "all" | "rest" }?
but this should be rather some global parameter then property of each
transcluded file.)

I'm sorry that I haven't finished more baked proposal on the time. My
plan was to create some sample files that will shows these different
transclusion modes. I can do this before next months telcon, but I would
like to hear some comments during todays telcon as well.

				Jirka

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