Re: [docbook-tc] Fwd: About your "Updated transclusion proposal"

[Jirka Kosek <jirka@kosek.cz>]

> ------------------------------------------------------------------------
> About your "Updated transclusion proposal"
> (https://lists.oasis-open.org/archives/docbook-tc/201409/msg00001.html)
> ------------------------------------------------------------------------

Hi Hussein,

based on feedback we produced new draft of Transclusion. Until TC will
approve it and will be published you can access it in the attachment to
the following email:

https://lists.oasis-open.org/archives/docbook/201412/msg00002.html

Your comments and feedback are more then welcomed.

More comments to some of your inquiries are below:

> * In my opinion, the transclusion processing you describe is not
> specific to DocBook 5. Your specification may be seen as an extension of
> the XInclude 1.1 specification which could be used for any document type
> making use of ID/IDREFs (e.g. DocBook 4, TEI). That's why you may want
> to choose a namespace for your attributes more generic than
> "http://docbook.org/ns/docbook";.

We changed namespace for transclusion attributes and the specification
now explicitly says that it can be used for other vocabularies as well.

> 1) Do not modify ID/IDREFs, that is, the equivalent of db:idfixup=none.
> 
> 2) Adjust ID/IDREFs, that is, the equivalent of db:idfixup=auto and
> db:linkscope=near.
> 
> * Let's say I'm wrong and that authors want full control over the IDs
> found in the transcluded content. In such case, your specification seems
> to be fine.

We kept db:idfixup=suffix (formerly prefix). Main reason is that for
some output formats (HTML based ones), IDs are used for deriving
filenames and anchor names. It's quite common to have control over those
as you need to keep URLs persistent over long period of time (eg. if you
put your HTML documentation on the website).

> A) What to do with db:XXX attributes in the transcluded content?
> 
> I suggest to discard them as they are no longer useful. Moreover,
> keeping them would make a DocBook 4 or TEI document invalid (yes, your
> specification is also useful in the case of DocBook 4 or TEI documents).

XInclude 1.1 draft has been changed, so we are now using XInclude 1.1
features for overriding local DocBook attributes and xml:id value. For
transclusion attributes we explicitly say that they should be discarded.

> B) Why use automatically generated prefixes rather than automatically
> generated suffixes?

Good point. We switched to suffixes.

> C) What's the default value of db:linkscope?
> 
> Your examples seem to suggest that it's db:linkscope=near when
> db:idfixup is not "none".

Indeed, this is fixed in the spec now.

> D) What's the use of db:linkscope=local?
> 
> This option is very likely to cause cross-references errors.

This can be useful if you want to isolate foreign documentation module
(which has some broken links inside).

					Jirka


-- 
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka@kosek.cz      http://xmlguru.cz
------------------------------------------------------------------
     Professional XML and Web consulting and training services
DocBook/DITA customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 rep.
------------------------------------------------------------------
    Bringing you XML Prague conference    http://xmlprague.cz
------------------------------------------------------------------

Attachment: signature.asc
Description: OpenPGP digital signature