[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] Future DocBook Ruminations - Modular Source Files & XInclude
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]