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

[Bob Stayton <bobs at caldera dot com>]

On Thu, Oct 03, 2002 at 11:36:59AM +0200, Peter Ring wrote:
> Here's how we do it.
> 
> First I'd like to lobby for keeping your local copies of DTDs and
> stylesheets as a mirror or cache of the canonical URLs. This makes mapping
> URL system identiers to local system identifiers trivial, and also makes
> maintenance a no-brainer. BTW, the catalog.dtd that you get from
> http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd is
> version 1.7, while the one in the spec is version 1.9. So much for entity
> resolution over the net ;)
> 
> xml/
>   catalog.xml # master catalog that delegates 
>               # public, uri, and system identifiers 
>               # to catalogs below
>   docbook.sourceforge.net/
>     release/
>       xsl/
>         catalog.xml
>         1.48/
>         1.55.0/
>   www.magnus.dk/
>     docbook/
>       xml/
>         catalog.xml
>         1.0/
>         1.1/
>         1.3/
>       xsl/ # put generally useful xsl 
>            # customization here
>   www.oasis-open.org/
>     committees/
>       entity/
>         release/
>           1.0/
>     docbook/
>       xml/
>         catalog.xml
>         configerror.txt
>         ebnf/
>           1.0/
>           1.1CR1/
>         htmlforms/
>           1.1/
>         mathml/
>           1.0/
>         simple/
>           1.0CR3/
>           4.1.2.5/
>         svg/
>           1.0CR1/
>         4.1.2/
>         4.2/
>       xmlcharent/
>         catalog.xml
>         0.3/
>   www.w3.org/
>     TR/
>       html4/        
>       xhtml1/
>         catalog.xml
>         DTD/
>       MathML2/
>         catalog.xml
>         dtd/
> 
> Our DocBook customization adds <xi:include> as a valid element in a number
> of places. This was quite messy until DocBook XML 4.2. The general idea is
> to add the <xi:include> element to to %local.whatever.class; so that
> <xi:include> becomes valid in <whatever> context.
> 
> I've left out some additional customization that includes EBNF support; it's
> still rather messy if you don't want to use the released wrapper DTDs.
> Anyway, here we go:
> 
> <!-- 
>   Customised DocBook XML DTD
> 
>   Invocation:
>   "-//MAGNUS//DTD DocBook XML V4.2-Based Variant V1.2//EN"
> 
>   $Id: magnus-docbookx.dtd,v 1.6 2002/06/24 09:43:33 pri Exp $
>   -->
> 
> <!-- XInclude element
>   http://www.w3.org/TR/2002/CR-xinclude-20020221/
>   -->
> <!ELEMENT xi:include
>   (xi:fallback)
>   >
> <!ATTLIST xi:include
>   href CDATA #REQUIRED
>   parse (xml|text) "xml"
>   encoding CDATA #IMPLIED
>   xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude";
>   >
> <!ELEMENT xi:fallback 
>   ANY
>   >
> <!ATTLIST xi:fallback
>   xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude";
>   >
> 
> <!-- include as chapter 
>   -->
> <!ENTITY % local.chapter.class
>   "|xi:include"
>   >
> 
> <!-- include as section
>   -->
> <!ENTITY % local.section.class
>   "|xi:include"
>   >
> 
> <!-- include as para content
>   -->
> <!ENTITY % local.para.char.mix
>   "|xi:include"
> >
> 
> 
> <!ENTITY % DocBookDTD PUBLIC 
>   "-//OASIS//DTD DocBook XML V4.2//EN"
>   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";
>   >
> %DocBookDTD;

Thanks for this great detail.

One little item...
I've noticed in your example and the XInclude Candidate
Recommendation that the content model for xi:include is:
 
  <!ELEMENT xi:include (xi:fallback) >

Shouldn't there be a question mark to make xi:fallback optional?

  <!ELEMENT xi:include (xi:fallback?) >

The spec [1] seems to permit this.  Here is the relevant part:

  4.4 Fallback Behavior
  XInclude processors must perform fallback behavior in the
  event of a resource error, as follows:
  
  If the [children] of the xi:include element information item
  in the source infoset contain exactly one xi:fallback
  element, the top-level included items consists of the
  information items corresponding to the result of performing
  XInclude processing on the [children] of the xi:fallback
  element. It is a fatal error if there is zero or more than
  one xi:fallback element.

When I first read this, the final sentence suggested that
xi:fallback is required.  But that sentence is qualified
by the first paragraph, which says fallback is invoked
only when a resource error occurs (when the xinclude URI can't be
resolved).

I realize you may want to enforce having a fallback element
using the DTD, and that's fine.  But when you do that, you get no
indication from the processor that your intended xinclude
failed. You have to scan the output.

Not having a fallback element produces a fatal
error if the xinclude cannot be resolved.  That may be
desirable behavior, depending on the application:

1.  In a web application, it is more important that the
process complete, and fallback is better than failure.

2.  In a publishing application where you are preparing final
camera-ready copy, it is more important that the
xincludes succeed, and any fallback is not acceptable.
Then failure is better than fallback.  Fix the problem
and run it again until it is right.

So in a publishing environment, I'd rather not have the
fallback elements so that it is impossible to produce output
with missing content.  A nice combination might be to
declare a stock fallback element with an entity, and insert
that entity in each xinclude so that
draft processing can proceed. Then for final processing
declare the entity as empty so fallback is removed.

So that's why I think in some situations
the xi:fallback element needs to be declared optional
in the DTD.


[1] XML Inclusions (XInclude) Version 1.0
    W3C Candidate Recommendation 17 September 2002
    http://www.w3.org/TR/xinclude/#fallback


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