OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

Jirka Kosek wrote:

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

Thanks Hussein for your valuable comments. More comments inline.

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

Personally I perceive XInclude as too verbose for inclusion of smaller
boilerplate texts -- but this is only problem if you edit document "by
hand" not using some advanced XML editor.

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

Self-contained except xml:base, am I right? You have to adjust xml:base
in some cases.

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

I see.

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

The idea was that first you will run transclusions (like XInclude), then
validate and then transform.

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

So @ref is similar to conref in DITA. There was some push back against
conref bacuse it has its own problems.

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

Yep, this probably will be sufficient in majority of scenarios.

Anyway thank you for your response and some fresh new ideas. It is very
important for DocBook TC -- we don't want to come with too complex
syntax noone would support. Currently it seems that tool vendors
consider the current proposal too complex, so we will have to come up
with something simpler and see whether it still address requests from users.

Thanks and have a nice day,


  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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]