Re: [docbook] Future DocBook Ruminations - Modular Source Files & XInclude

[Bob Stayton <bobs@sco.com>]

On Wed, Aug 20, 2003 at 07:30:53PM +0100, Wills, Robert wrote:
> > No offense, but what this crap will be good for? Resulting grammar will 
> > be inconsistent and will go against all design rules for markup 
> > languages which I know. 
> 
> The grammar I suggested is certainly verbose but isn't inconsistent by any
> XML standards I'm aware of. Which design rules for markup languages does it
> break?
> 
> > Splitting document into several files works on 
> > physical level, resulting document on logical level should be reasonable 
> > structured XML. You can gain this by using external entities and 
> > XIncludes, no additional elements needed.
> 
> I'm not suggesting changing anything about how external entities or
> XIncludes work, or introducing any new mechanisms.
> 
> I am suggesting DocBook picks up an explicit dependency on the <xi:include>
> element and namespace - not something to be done lightly. For the DocBook
> specification the spotlight seems to focus on the processing and XSLT side
> of things where obviously XIncludes should never appear, but we should not
> forget that this same DTD is important in the editing environment too. From
> a document editor's perspective if the official way to do DocBook inclusion
> is <xi:include>, then why does any source file containing an <xi:include>
> fail to validate against the official DocBook DTD? I know and understand the
> current answer to this question, but don't 100% agree with it.
> 
> > If some tools have problems with external entities/XIncludes, then fix
> > these tools.
> 
> To quote Jeff Beal's recent posting about current editor support for
> modularization:
> 
>   "Epic wraps the DOCTYPE declarations with XML comments.
>   Emacs/PSGML uses local buffer variables to point to the
>   parent document. XMetal uses a processing instruction to
>   point to the DTD.  WordPerfect has a catalog that maps
>   the root element to the DTD."
> 
> Is this what you mean by "fix"? It's a subjective point, by I think even my
> admittedly inelegant solution less of a hack than any of the above.
> 
> > But don't touch XML sources, they should be there for many 
> > years, they are important.
> 
> Yes they are important, but sources have to be edited as well as processed,
> and in the real world editing rapidly implies errors. The earlier you find
> the errors, the faster your documents go out the door. The best way to find
> errors is to validate against a grammar.
> 
> I'm just looking for a standards-compliant and practical way to allow
> validation of document fragments without relying on hacks in particular
> editing environments and without compromising the rigor of the DocBook
> grammar. It seems odd that this requirement should prove such a difficult
> one to solve given all the powerful XML technologies and standards at our
> disposal.

I believe that XInclude was created to solve this problem.
Unfortunately, it is still a Candidate Recommendation at
W3C, so it has not been fully implemented by the various
processors.

It is possible to use XInclude with standard tools
and editors.  We use it in a master book file to pull
in chapter and appendix files, each of which is a valid
document.  None of the modular files use Xincludes, so they
can be worked on with any XML tools.  Only the master book
file needs the special handling for XIncludes:

- Extending the DTD to add an xi:include element. That can
be done with an internal subset in the DOCTYPE declaration
in the master book file.  It can be done by declaring
a couple of 'local' parameter entities that are designed
to be used to extend the DTD.

- Processing the book file with an XInclude-aware
processor, such as xsltproc.  

- Validation of the book file still needs to be done.
Despite what Daniel Veillard said about there being
no standard for validation after resolving XIncludes,
his xmllint tool with the --xinclude and --postvalid
options does a nice job of validating after the includes
are resolved.

Keep in mind that cross references may be an issue with
modular files.  You can't use xref and link between modules.
You have to use olink.  That requires more setup, but
it does work.  For more details, see:

http://www.sagehill.net/docbookxsl/ModularDoc.html

-- 

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