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 | [email protected] | www.sybase.com Norman Walsh <[email protected]> 12/11/2009 04:16 PM To [email protected] 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 <[email protected]> | Wink at small faults; for thou has http://www.oasis-open.org/docbook/ | great ones.--Thomas Fuller (II) Chair, DocBook Technical Committee |
<<image/jpeg>>
attszn9p.dat
Description: Binary data
--------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
