Re: DOCBOOK: Defining ENTITYs in nested entity files

["Matt G." <matt_g_@hotmail.com>]

>From: ed@halley.cc
>To: docbook@lists.oasis-open.org
>Subject: DOCBOOK: Defining ENTITYs in nested entity files
>Date: Tue, 06 Aug 2002 11:19:46 -0400
>
>However, to "include" the nested files, I have to identify all
>of them in the book.sgml as <!ENTITY> elements before the <book>
>tag starts.

First of all, this is an SGML/XML issue.  At least w/ regard to the XML 
version of DocBook, the authors of the DTD can't do anything about the 
behavior of entities.  They could add XInclude-like functionality, but 
that's another discussion (check the archives).

All entities must be defined in either the internal or external subset of 
the DTD, as you observe, but this DOESN'T mean they must be local to the 
top-level file.  XML/SGML allows parameter entities to be external, so you 
can put these definitions in another file (or files).

You might even consider creating a hierarchy of parameter entities, which 
roughly mirrors the file-structure of your document.  If you're a 
programmer, think of it somewhat like .h files which correspond to .c files. 
  Just keep in mind that all relative system identifiers are relative to the 
location of the file in which the entity is defined - not to the top-level 
file where they're included.


>I couldn't find a way to name a file to be included/imported on
>the spot.  It seems more natural to me to define the chapter
>elements in each part file, and the part files in the book file.

Ah, the perennial tradeoff between locality and flexibility...  The entity 
mechanism, in XML (I don't know if SGML has the same limitations), forces 
you to define entities up-front (and provide internal names, for external 
entities), but you can override them.  Without this level of indirection, 
you couldn't override the value or externally override/resolve the location 
of an external entity.  Whether that's useful, for your purposes, is another 
matter - I'm merely citing some advantages of this additional 
complexity/non-locality.


>For example, I considered:
>
>  book.sgml (including <book> &preface; &partfoo; &partbar; </book>)
>
>    preface.sgml (a leaf <preface> </preface>)
>
>    partfoo.sgml (including <part> &chapfoofoo; &chapfoobar; </part>)
>
>      chapfoofoo.sgml (a leaf <chapter> </chapter>)
>
>      chapfoobar.sgml (a leaf <chapter> </chapter>)
>
>    partbar.sgml (including <part> &chapbarfoo; &chapbarbar; </part>)
>
>      chapbarfoo.sgml (a leaf <chapter> </chapter>)
>
>      chapbarbar.sgml (a leaf <chapter> </chapter>)


On your file naming convention & structure, I just thought I'd make the 
observation that you're over-constraining your ability to adjust nesting 
depth.  For example, if you decide you want to make chapbarfoo and 
chapbarbar child sections of another chapter, you have to modify both of 
those files, and their names are now misleading.  If you put the 'chapter' 
tags in your 'part' files, you can just start chapbarfoo.sgml with a 'title' 
(and maybe change its name not to start with "chap"), and it can be either a 
chapter or a section.

Of course, this assumes you're using the recursive 'section' element, 
instead of numbered ones.  I never understood why someone would want 
depth-numbered sections - I don't believe people even take advantage of the 
ability to adjust the content model, at a given depth.


Matt Gruenke


_________________________________________________________________
Chat with friends online, try MSN Messenger: http://messenger.msn.com