[Fwd: Re: [Fwd: Feedback on DocBook Transclusion proposal]]

[Jirka Kosek <jirka@kosek.cz>]

[With permission, I'm forwarding comments from Hussein Shafie.]

I've carefully read both the requirements
(http://docbook.org/docs/transclusion-requirements/) and your proposal
(http://docbook.org/docs/transclusion/) and I congratulate you about the
professionalism and depth of your work.

However my personal inclination leads me to always prefer simpler,
lighter, designs, even if it's at the expense of completeness.

It's very important to keep DocBook as simple as possible because, in my
opinion, it's a matter of life and death for structured documents. As a
technical writer, I would hate the idea of having the choice just
between an extremely complex DocBook 6 standard and an insanely complex
DITA 1.2.

--------------
About XInclude
--------------

First of all, why completely give up the idea of improving the XInclude
standard? I'm speaking about an hypothetical, rehashed, XInclude v2.0.

There are good things in XInclude:

* It's a simple, generic, mechanism.

* XInclude transclusion is orthogonal to document validation. It happens
before the document is validated. (In my opinion, XInclude elements
should never be added to the grammar of an XML vocabulary.)

* It comes with a very simple "element" addressing scheme (which could
be made slightly more powerful). It is open to other addressing schemes.

* xi:include elements are ``self-contained''. For example, you can
copy/paste them easily and reliably between different documents. No need
to declare anything special in the document where an xi:include has been
pasted.

-------------------
About your proposal
-------------------

* Your inline ref elements (without @definitionfile) bear names which
refer to the set of definitions attached to the document being edited.
This is quite hard to manage for an authoring tool such as XXE.

Example: you copy an inline <ref name="foo"> from document A and paste
it to document B. What if there is no <def name="foo"> in document B?
What if there is an existing but may be totally different <def
name="foo"> in document B?

There is no such problems with ``self-contained'' transclusion
directives such as XInclude or DITA conref.

* Your ref element is intended to be part of the DocBook grammar,
despite the fact that it conveys no element type information.

Example:

<para>Blah, blah, <ref name="disclaimer"/>.</para>

where:

<def name="disclaimer">
  <para>Be warned that...</para>
</def>

Here's what will happen:

[1] The above document validates OK.
[2] The transclusion processor, which is very rarely schema-aware, has
no way to report a transclusion error.
[3] The user will get a funny looking output when she/he will convert
its document to, say, PDF.

* In my experience, the idfixup/linkscope feature is overkill.

In your requirement document, you have basically described 2 kinds of
transclusion directives:

[UC-4] A transclusion directive which is used to compose modular
documents. In this case, the transcluded content will be found just once
in the modular document. Hence there is no need to perform any ID/IDREF
fixup.

[UC-5] A transclusion directive which is used to instantiate a copy of
one or more nodes. In such case, the transcluded content will typically
be found more that once in the document.

In my experience, suffice to be able to specify the ID of the copy. All
ID/IDREFs inside the copy may be automatically mangled. I don't know any
case where an author will want to address an element *inside* the copy.

What I call mangle ID/IDREFS is simply:
- Add a globally unique suffix to each ID defined in the copy.
- Update the IDREF/IDREFS which point to these IDs.
- Ignore the IDREF/IDREFS which point outside the copy.

----------------------------------------------------------
Outline of the transclusion mechanism, which as an author,
I would like to use
----------------------------------------------------------

Any element may bear one of these two attributes: @ref and @copy. The
value of these attributes is an URL, possibly ending with a fragment.

When an element has a @ref or a @copy attribute, it must be completely
empty.

@ref is a ``compose'' transclusion directive. Examples:

<chapter ref="chapter1.xml"/>

<section ref="book.xml#api_reference"/>

When @ref is used, there is no ID/IDREF fixup in the transcluded content.

@copy is an ``instantiate a copy'' transclusion directive. Examples:

<note xml:id="warning" copy="common.xml#legal_warning"/>

<phrase copy="common.xml#product_name"/>

When @copy is used, there is an automatic ID/IDREF fixup in the
transcluded content, the one described above:
- Add a globally unique suffix to each ID defined in the copy.
- Update the IDREF/IDREFS which point to these IDs.
- Ignore the IDREF/IDREFS which point outside the copy.

Cheers.







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