Re: [xml] Best way to add XInclude to existing DTD?

[Daniel Veillard <veillard redhat com>]

On Thu, Sep 20, 2001 at 02:31:07PM +0200, Peter Ring wrote:
  I'm a bit late replying, I'm busy with other stuff and this raises
a few interestng but complex questions !

> I'm investigating XInclude as a way to compile a number of separately
> maintained DocBook XML documents into one document for publication. The
> beauty of using XInclude is that each document is a valid instance by
> itself, which makes it a lot easier to edit (and besides, it encourages a
> writing style which is beneficial for this particular purpose).

  Well people usually use external parsed entities for this, that's the
canonical way to do this. In general your question would also be suitable
for the docbook-apps mailing list at OASIS.

> I wonder what might be the most kosher way to add the necessary <include
> href="..."> element to DocBook?
> 
> E.g., to pick up fragments as <section> elements:
> 
>   <?xml version="1.0"?>
>   <!DOCTYPE section PUBLIC 
>     "-//OASIS//DTD DocBook XML V4.1.2//EN"
>     "/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd" [
>     <!ENTITY % local.section.attrib
>       "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'"
>     >
>     <!ENTITY % local.refentry.class
>       "|xi:include"
>     >
>     <!-- ENTITY % local.refentry.class
>       "|include"
>     -->
>     <!ELEMENT xi:include
>       EMPTY
>     >
>     <!ATTLIST xi:include
>       href CDATA #REQUIRED
>       parse (xml|text) "xml"
>       encoding CDATA #IMPLIED
>     >
>   ]>

  I'm always a bit reluctant about extending the DTD from the internal
subset. It is correct but makes the document different, this should work
in this case but is IMHO looking for troubles on the long term.
<pedantic>
using a local file path for the SystemID is not fantastic, I would
suggest you investigate XML Catalogs (see my previous posts on this
subject) and keep the canonical URI for docbookx.dtd
</pedantic>

>   <section> 
>     <title>A section</title> 
>     <para>Some introductory remarks</para>
>     <xi:include href="included.xml#xpointer(/section)"/>
>   </section>

  XInclude is not yet a Recommendation. One of the most controversial
points of the current draft is the reuse of XPointer. I like to see this
used but in all fairness I have to note that this is subject to reexamination
by the XML Core Working Group. I think we will keep this but ...

> I've added the XInclude namespace declaration as a #FIXED attribute to
> <section>, and added <xi:include> to the content model of %refentry.class;,
> which was as close as I could easily get to <section>. 

  Yes this in theory should work. But as you noted this may be pushing the
limits of libxml namespaces+DTD compatibility a bit too far.

> This works well with editors and with libxml/libxslt (2.4.5/1.0.4) except
> that it does not validate with xmllint (using libxml version 20405). For
> validation, xmllint wants "include" rather than "xi:include":

  This really sounds like a bug, I'm really sorry I didn't had time
to look at it yet. Will do, if you register it on bugzill.gnome.org
you will be sure I won't forget :-)

> $ xmllint --catalogs --loaddtd --valid --debug template.xml
> 
> template.xml:27: validity error: Element section content doesn't follow the
> Dtd
> Expecting (sectioninfo? , ... a large content model ... | (refentry |
> xi:include)+ | section+) , (toc | lot | index | glossary | bibliography)*),
> got (title para include )
> </section>
>          ^
> DOCUMENT
> version=1.0
> URL=template.xml
> standalone=true
>   DTD(section), PUBLIC -//OASIS//DTD DocBook XML V4.1.2//EN, SYSTEM
> /usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd
>     ENTITYDECL(local.section.attrib), parameter
>      content=xmlns:xi CDATA #FIXED 'http://www.w3.org...
>     ENTITYDECL(local.refentry.class), parameter
>      content=|xi:include
>     COMMENT
>       content= ENTITY % local.refentry.class     "|inc...
>     ELEMDECL(include), EMPTY
>     ATTRDECL(href) for xi:include CDATA REQUIRED
>     ATTRDECL(parse) for xi:include ENUMERATION (xml|text)"xml"
>     ATTRDECL(encoding) for xi:include CDATA IMPLIED
>   ELEMENT section
>     namespace xi href=http://www.w3.org/2001/XInclude
>     TEXT
>       content=    
>     ELEMENT title
>       TEXT
>         content=A section
>     TEXT
>       content=    
>     ELEMENT para
>       TEXT
>         content=Some introductory remarks
>     TEXT
>       content=   
>     ELEMENT xi:include
>       ATTRIBUTE href
>         TEXT
>           content=included.xml#xpointer(/section)
>     TEXT
>       content= 
> 
> For the validation, xmllint reports that it got an "include" element, while
> the debug output displays a "xi:include" element.
> 
> What gives?

  A bug very probably.
I very much like the spirit of your attempt, it is an interesting suggestion.
Another way in the libxml framework to make sure the included entities
are valid is to use the
  xmllint --dtdvalid /usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd \
      included.xml
"a posteriori" validation. It's more tied in some sense to libxml but 
do not rely on XInclude and XPointer.

  yours,

Daniel

-- 
Daniel Veillard      | Red Hat Network http://redhat.com/products/network/
veillard redhat com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/