RE: [docbook] Transclusion

["Rowland, Larry" <larry.rowland@hp.com>]

We implemented our own transclusion operators before XInclude was
stable enough to use.  We use a number of DocBook derived grammars
for specific types of documents (like help systems and manpages)
that have extensions for the specific environments they deliver
content into.  We found the addition of a grammar attribute to
be quite helpful to handle the specialized filtering and conversion
necessary to pull content from help systems and man pages into our
pretty much pure DocBook markup for books in PDF and HTML.  The
preprocessor that handles the transclusion invokes transform
elements based on the grammar attribute.

The transclusion operators also handle the simplest (and we found
the most common) ID collision problem by allowing the ID on the
inclusion element to replace the ID on the included content.  Most
of what we were including was small things like admonitions or
steps, which did not have internal IDs to deal with.  Inclusion
on the section level did not tend to be repeated in the same 
document, so this handled most of the problems.  We did have to
come up with an ID naming scheme so that not everyone used the
same ID for the introduction or preface.

Regards,
Larry Rowland



From: "David Cramer" <dcramer@motive.com> 
To: "Norman Walsh" <ndw@nwalsh.com>,<docbook@lists.oasis-open.org> 
Date: Fri, 11 Dec 2009 16:17:24 -0600 

--------------------------------------------------------------------------------

4. Validation. The author needs a way to know if the document is still
going to be valid post-transclusion. 

David

> -----Original Message-----
> From: Norman Walsh [mailto:ndw@nwalsh.com] 
> Sent: Friday, December 11, 2009 3:17 PM
> To: docbook@lists.oasis-open.org
> 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 |
> 


=======================================================================
[ Larry Rowland             | If you want to build a ship, don't drum ]  
[ ESS/ATG                   | up the men to gather the wood, divide   ]
[ Hewlett-Packard           | the work, and give orders. Instead,     ]
[ 3404 East Harmony Road    | teach them to yearn for the vast and    ]
[ Fort Collins, CO  80528   | endless sea. - Antoine de Saint Exupery ]
[ Phone: 970/898-2280       +-----------------------------------------]
[ E-Mail:larry.rowland@.hp.com                                        ]
=======================================================================