docbook-apps

Hi,



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. 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).



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.



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



Thanks!

Fabrice

Typically those chapters are included as entities in a book file that
does have a doctype and also has any doc-specific entities declared in
the doctype's internal subset. You then validate the book file and in
doing so validate all the files it pulls in as entity references. See
DocBook, The Definitive Guide for more information:

http://docbook.org/tdg/en/html/ch02.html#ch02-physdiv

However, now there's another way to do the same thing in which each part
of the larger document does have its own doctype. See Bob Stayton's book
for a discussion of that:

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

David


________________________________

From: Fabrice (GMail) [mailto:fabrice.talbot@gmail.com]
Sent: Tuesday, March 31, 2009 1:24 PM
To: docbook-apps@lists.oasis-open.org
Subject: [docbook-apps] Undeclared entity in Docbook chapters



Hi,



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. 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).



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...



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



Thanks!

Fabrice

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