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

Hi Norm,

I apologize for not responding to this request earlier but it arrived at a very busy time for us. Thank you for following up on this issue. I really hope that the TC can
come up with a solution for this problem.

Regarding your first requirement:
 1. Transclusion can introduce duplicate xml:id values. It should be
possible to specify a strategy for changing xml:id values in the transcluded content so that this is not the case.

I would further specify that the strategy for changing xml:id values should allow the user to specify the xml:id, so the transcluded content can be olinked to (i.e.,
 the strategy should not rely on modifying the ID values in the output ).

Secondary requirement:
There needs to be a mechanism to inform you when content is transcluded elsewhere. It is important to know when you are editing
a file that the file (or parts of it) is transcluded elsewhere and the locations of where it is transcluded (otherwise you can ignorantly change the content to make
it confusing or unusable where it is transcluded). It is really easy to know the reverse: to know  the portions of the file that are transcluded from elsewhere (you just need to look for the xinclude tag).

Example use case:

We document database software and in our reference material we document SQL statements which involves describing the various parameters/clauses that each statement takes.
The parameters and their descriptions can often be duplicated across multiple SQL statements. For example, the CREATE TABLE (http://dcx.sybase.com/index.html#1101en/dbreference_en11/create-table-statement.html) and  ALTER TABLE (http://dcx.sybase.com/index.html#1101en/dbreference_en11/alter-table-statement.html)
statements share most of their parameters.

Currently we use olinks to link the user from a particular parameter description in the ALTER TABLE statement to the corresponding parameter description in the CREATE TABLE statement.
For example:  INDEX and NO INDEX clauses   Use this clause to specify whether to build indexes on large BLOBs in this column. For more information about how to use this clause, see the corresponding section for the [NO] INDEX clause in the CREATE TABLE statement. We tried copying and pasting the parameter descriptions but found that it was too easy for descriptions to get missed and to find ourselves wasting time comparing the contents of the parameter descriptions. So, now the burden is placed on the user to flip back and forth between two (and often more) statement pages to get a
full description of a statement.

Because the SQL statements exist in the same book, we can't xinclude (using the xpointer element scheme) the parameters from one statement to another without introducing duplicate IDs.

Because we are dealing with hundreds of parameter descriptions,we do not want to create separate files that contain the individual parameter descriptions  as this would be cumbersome for us to organize and work with (if not impossible without a CMS). Also, we need to be able to link to the individual parameter descriptions; that is, we need the element (e.g., varilistentry, para, etc., ) that contains the transcluded description to have a unique ID.

What we need is the ability to transclude the content of the parameter descriptions into a new element tag, such as, how the xinclude xpointer scheme (http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219/) is designed to work. Unfortunately, the xpointer scheme is only a W3 draft, which means it "may be updated, replaced, or obsoleted by other documents at any time."

Thanks again,

Sybase 25 Year Anniversary logo Kate Wringe | Tech Writer 2| Sybase iAnywhere
445 Wes Graham Way, Waterloo, ON, N2L 6R2 Canada | Tel: (519) 883-6838 | kate.wringe@sybase.com | www.sybase.com

Norman Walsh <ndw@nwalsh.com>

12/11/2009 04:16 PM

[docbook] Transclusion

Hello world,

There's an open RFE about transclusion


The TC's initial position was to push back, suggesting that the right
technology for the task is XInclude.

Unforunately, XInclude isn't a complete solution because getting the
content transcluded doesn't solve the entire problem. And it doesn't
help that the the standardized XPointer schemes are fairly brittle.

The TC would like to collect a set of use cases and requirements for
transclusion. Here are the requirements that I can think of (with help
From the comments in the REF).

1. Transclusion can introduce duplicate xml:id values. It should be
possible to specify a strategy for changing xml:id values in the
transcluded content so that this is not the case.

2. Using the XInclude framework and element schemes, it's only
possible to transclude a single element. It should be possible to
specify ranges, at least ranges of sibling elements.

3. The XInclude framework and element schems are a little bit brittle.
Are there more robust schemes that we could encourage implementors to

What other requirements are there?

                                       Be seeing you,

Norman Walsh <ndw@nwalsh.com>      | Wink at small faults; for thou has
http://www.oasis-open.org/docbook/ | great ones.--Thomas Fuller (II)
Chair, DocBook Technical Committee |


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