Re: DOCBOOK-APPS: Including Fragments of other DocBook Documents

[Bob Stayton <bobs@caldera.com>]

On Wed, Jun 19, 2002 at 04:35:12PM +0100, Sagar.Shah@ubsw.com wrote:
> >-----Original Message-----
> >From: Paul Grosso [mailto:pgrosso@arbortext.com]
> >Sent: 19 June 2002 15:01
> >To: Shah, Sagar; docbook-apps@lists.oasis-open.org
> >Subject: Re: DOCBOOK-APPS: Including Fragments of other DocBook
> >Documents
> >
> >
> >At 11:41 2002 06 19 +0100, Sagar.Shah@ubsw.com wrote:
> >>I would like to be able to include fragments of other docbook 
> >documents in the document i'm writing. (to save maintaining 
> >information in two places etc. etc.).
> >
> >
> >>So far i've managed to use Xinlcude and do things along the lines of:
> >>
> >>-----
> >><?xml version="1.0"?>
> >><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML 
> >V4.1.2//EN" "docbookx.dtd" [
> >><!ELEMENT xi:include (xi:fallback)>
> >>                  <!ATTLIST xi:include
> >>                      xmlns:xi  CDATA #FIXED 
> >"http://www.w3.org/2001/XInclude";         
> >>                      href       CDATA                        
> >           #REQUIRED
> >>                      parse      (xml|text)                   
> >           "xml"
> >>                      encoding   CDATA                        
> >           #IMPLIED
> >>                  >
> >><!ELEMENT xi:fallback ANY>
> >>                  <!ATTLIST xi:fallback
> >>                      xmlns:xi   CDATA #FIXED   
> >"http://www.w3.org/2001/XInclude";
> >>                  >
> >>]>
> >>
> >><article>
> >>  <articleinfo>
> >>    <title>Test</title>
> >>    <author>
> >>      <firstname>Sagar</firstname>
> >>      <surname>Shah</surname>
> >>    </author>
> >>
> >>  </articleinfo>
> >>
> >>  <section id="MyFirstSection">
> >>    <title>foo</title>
> >>    <para>la la</para>  
> >>    <xi:include 
> >href="docbook-tech-support-1.dbk#xpointer(id('OtherIssues'))"/> 
> >>  </section>
> >></article>
> >>-----------
> >>
> >>This all works fine :-)
> >
> >This is interesting to me.  Can you please tell us what tool(s) you
> >are using that have implemented XInclude?   (The W3C XML Core WG is
> >still looking for XInclude implementation experience, and it was not
> >clear to me that there was any great amount of XInclude support out
> >there yet, so any information would be of value.)
> 
> I don't know how mature it is, but the Xinlcude support in
> libxslt and libxml2 works great for me :-)


I'm also using xincludes with xsltproc with good success.
To do so, you just add --xinclude to your xsltproc command line.
I understand that Cocoon implements xincludes as well, but
I've not tried it.  I've looked but not found support in Saxon
for xinclude.

I've kept my xinclude usage simple: a master book document
that contains just a sequence of <xi:include> elements to
pull in the chapter files.  Many people set up their
books using external entities this way.  The advantage of
xincludes is that each chapter file can be a complete XML
document with DOCTYPE declaration.  That means chapter files
can be loaded into an XML editor and validated individually
without doing DOCTYPE tricks.

With a simple book file like this, I never have to load my
book document into my XML editor, where it would complain
about the DTD not declaring <xi:include> elements.  I did
try creating a DTD customization, but decided I didn't need
it with this simple setup.  I just make sure my individual
chapter files are valid.

xsltproc supports xincluding part of a document using the #id
syntax to locate an element by id.  I tried some other
XPointer syntax, but couldn't get it to work.  I also tried
using nested xincludes, but the internal ones were not
'included'.

To validate my book, I use xmllint, which is included
with xsltproc:

xmllint --xinclude --postvalid --noout book.xml

I've run into situations where I wanted to process my
content with tools that don't support xinclude.  For those
situations, I preprocess my book file to resolve the
xincludes first. I use xsltproc --xinclude and a trivial
XSL stylesheet that outputs all elements and attributes.
Then I run the results through the other processor.


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com