Re: DOCBOOK-APPS: XInclude doesn't validate with xmllint

[Bob Stayton <bobs@caldera.com>]

On Sun, Dec 01, 2002 at 11:38:07AM +0100, Yann Dirson wrote:
> It happens that the following idea just reached my concious mind, so I try
> to followup to the correct thread.
> 
> IIRC the context was about validating documents before or after xinclude
> processing.
> 
> My opinion is still that we need to be able to validate before, and that
> does not prevent to validate after as well.
> 
> There is even a use-case for this.  If the individual XML files do not
> validate (ie. conform to a DTD which has the xinclude elements), then we
> cannot make use of the existing SGML editing tools (psgml comes to my mind
> as one of the most widely used, since its existence even brought some vi
> adepts to launch emacs sometimes).
> 
> 
> On Fri, Oct 04, 2002 at 06:41:08AM -0400, Daniel Veillard wrote:
> > > >   But allowing an extra attribute everywhere is quite simpler
> > > > than allowing an extra element everywhere :-)
> > >
> > > "everywhere" is probably too strong, i bet noone wants to use this for
> > > inline elements.
> >
> >   Well, it's hard to predict a priori in what way people are gonna use
> > a relatively new tool, I would not constraint the use case while there
> > have been only little use so far.
> 
> Yes, and IMHO not adding the xinclude elements to the DTD will effectively
> constraint the use case of DocBook.

It isn't that we (the DocBook Technical Committee) don't
want to add an xinclude element, or that we think it is 
not needed.  It would be easy to add an xinclude
element to the DTD.  But that isn't enough, because
the xinclude element must appear
in content models for it to be useful.

The problem is that it is hard to write the content models
for all cases of possible xinclude usage.  An xinclude can
replace just about any content, including required
elements.  That means just about every part of each
element's content model needs to change "somestuff"
to "(somestuff | xinclude )".  Try doing that with an element
like section, which currently has:

<!ELEMENT section (sectioninfo?,
		(%sect.title.content;),
		(%nav.class;)*,
		(((%divcomponent.mix;)+,
                   ((%refentry.class;)*|(%section.class;)*|simplesect*))
		 | (%refentry.class;)+|(%section.class;)+|simplesect+),
		(%nav.class;)*) >

You think this content model is hard to understand now,
wait until you add xinclude.  I get a headache just
thinking about the possible combinations. 8^)

Maybe certain common cases could be added.
Take the relative simple case of the book element.
It's content model could be amended to look like this:

<!ELEMENT book %ho; ((%div.title.content;)?, bookinfo?,
 		(dedication | toc | lot
 		| glossary | bibliography | preface
		| %chapter.class; | reference | part
		| %article.class;
            --> | xinclude
 		| %appendix.class;
		| %index.class;
		| colophon)*)
		%ubiq.inclusion;>

This addition would make
it possible to put chapters, bibliographies, appendices,
and such components into separate xincluded files,
and the book document would still validate.
But no matter what cases are added, someone will want
to use xinclude in other cases.

In any case, I maintain that it is misleading to validate a
document that has unresolved xincludes.  For example, a
title element is required for every chapter.  You can
replace the title element with an xinclude.  But the
xinclude is opaque to the validator if it is not resolved.
How can the validator know that the chapter has its
required title? What if the xinclude that should contain
the title does not actually contain a title?  Should the
validator say the chapter is valid? I don't think so.
Validation needs to be rigorous, and it can't be guessing
about missing elements.

Consider also that xincludes are very much like system
entity references.  A system entity reference can replace
just about any content in a document. And everyone seems to
accept the fact that the document cannot be validated until
the system entities are resolved.  Validating XML editors
must be able to resolve system entities to be truly
validating. Why not extend that mechanism to resolve
xincludes?  It seems that the hard part has already been
done, now they just need to handle some different syntax
for specifying the included text. 

So lobby your tool author to get them to support xinclude
the way they support system entities.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com