RE: [docbook-tc] discuss transclusion on Wednesday

["Grosso, Paul" <pgrosso@ptc.com>]

> -----Original Message-----
> From: Bob Stayton [mailto:bobs@sagehill.net]
> Sent: Tuesday, 2010 December 14 11:02
> To: DocBook Technical Committee
> Subject: [docbook-tc] discuss transclusion on Wednesday
> 
> Hi,
> I wanted to point out that the DocBook TC agenda includes discussion
of
> transclusion,
> and that Jirka has updated his proposal as of 9 December.  Here are
the
> URLs:
> 
> Requirements document:
> 
> http://docbook.org/docs/transclusion-requirements/
> 
> Specification document:
> 
> http://docbook.org/docs/transclusion/

We need to explain somewhere that the definitions element
is removed as a result of the transclusion (if that, in fact,
is what we want--that's what the examples make it look like).

-----

I still don't see where we explain what happens when a 
transcluded region contains an info element with definitions,
especially in the case where we have profiling attributes
involved.

And having a transcluded region that contains an info element 
with definitions will mean (I think) that the result of the
transclusion has some new definitions, but not the original
definitions (if we remove definitions as a result of the
transclusion as mentioned above).

-----

In Example 6, I don't see why os="linux" is chosen.
Perhaps we just need to say:

 Result of transclusion when os="linux"

or something like that to make this clearer.

-----

Example 7 does not show the results of the transclusion.
(And when it does, it will have to say what value of os was used.)

-----

In example 9, it wasn't clear to me whether ref's @definitionfile
was used as the only source of definitions or if those in the
document's info element would also be available (and presumably
overridden by a definition of the same name in the definitionfile).

-----

We need to say what happens with a ref element has both a name
attribute and a fileref attribute.

-----

I still think our suggested id fixup is too complicated.  Not
that it can't be implemented, but people are still saying XML
needs to be made simpler, and here we are defining something 
like linkscope=near which is going to be fairly confusing for
the average user to debug when things don't go as they expect.

Suppose we just have one attribute, idfixup-prefix, and when
it is not specified (or null), no id fixup is done.  Its
value can be either #auto or an NCName.  When it is #auto,
we do the equivalent of idfixup=auto, linkscope=local.  When
it is an NCName, we do the equivalent of idfixup=prefix,
linkscope=local with the given prefix.

I'd even be willing to give up on #auto.  When the prefix is
auto-generated, we can avoid id clash, but one can't reference
into a transcluded region from outside.  However, if you know
the prefix (because you specified in on the ref element), then
you will know what idref value to use to reference any id within
any transcluded region.  So I don't see much added value--and
some downside--to having #auto.

paul