Re: [docbook-apps] Undeclared entity in Docbook chapters

[Thomas Schraitle <tom_schr@web.de>]

On Dienstag, 31. März 2009, Fabrice (GMail) wrote:
>
> I noticed that some Docbook projects have chapter XML files that
> reference entities not declared in the chapter. The chapter will not
> validate when loaded in a XML Editor and raise errors with most XML
> parsers.

That is true if you validate the file alone. However, usually the file 
alone can not stand for itself: it is embedded into a book usually. This 
book have to be valid, of course.

XML editors have lots of features, and some has the ability to create a 
project which includes all the respective files to it. With this project, 
the XML editor can also validate a file "alone".


> This is usually resolved at publish time: a book XML file 
> references those chapters with entity variables and includes entity
> declaration (inline or with a link).

Right. Unfortunately, the XML specification is pretty clear with this 
approach: if you reference your chapter this way, you can not use a 
DOCTYPE declaration. 


> Can someone explain me the benefits (or reasons) of this approach?
> Having non-validating XML files seems to defy the purpose of using XML
> standards in the first place.

Well, as explained above, it's a historical issue. This approach is pretty 
old (used in SGML days). It is still in use, but nowadays, XIncludes 
seems more the way to go. Especially with DocBook5. With XIncludes you 
can have a DOCTYPE declaration and therefor entity declarations too.

See http://www.sagehill.net/docbookxsl/ModularDoc.html for more details 
(as David also pointed out).

However, even with XIncludes, the remaining problem still persists: If you 
have two different files and you reference from one into the other, you 
will get an validation error.


> What are the alternatives for writers who want to expose and use
> entities in chapters?

Use XIncludes instead of referencing files with entities.


Tom

-- 
Thomas Schraitle