This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Defining ENTITYs in nested entity files


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]