Re: [docbook] Transclusion

[Kate.Wringe@sybase.com]

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




..........................................................................................................................................................................................................................

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

To	docbook@lists.oasis-open.org
cc
Subject	[docbook] Transclusion

Hello world,

There's an open RFE about transclusion

  http://sourceforge.net/tracker/?func=detail&aid=2820947&group_id=21935&atid=384107

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

What other requirements are there?

                    
                   Be
seeing you,
                    
                     norm

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

attszn9p.dat