This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Defining ENTITYs in nested entity files
- From: Bob Stayton <bobs at caldera dot com>
- To: Ed Halley <ed at halley dot cc>, docbook at lists dot oasis-open dot org
- Date: Tue, 06 Aug 2002 09:20:09 -0700
- Subject: Re: DOCBOOK: Defining ENTITYs in nested entity files
- References: <1028647186.3132.41.camel@speare9>
On Tue, Aug 06, 2002 at 11:19:46AM -0400, Ed Halley wrote:
>
> I am a total "first day" newcomer to DocBook, trying to set up a basic
> outline for a possible book. I have a basic set of .sgml files worked
> out, but was perplexed about the rationale behind the <!ENTITY> /
> &entity; scheme which demands all entities be named in the top-layer
> document, rather than localized where it matters.
>
> 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>)
>
> 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. 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.
>
> This is merely an annoyance, and if pressed, I could just massage the
> .sgml files with a higher level script. I was just wondering about the
> rationale to requiring all external entities at all scopes to be
> referenced in the top level file? (And to point out something I missed,
> if indeed I did.)
You are running into the same frustration that I did when I
first tried to modularize DocBook content. The basic
problem is that the SGML and XML specifications state that
external parsed entities cannot have a <!DOCTYPE>
declaration. Without a DOCTYPE, you cannot declare other
entities. Also, without a DOCTYPE you can't have 'valid'
modular files.
<editorial>
I've always considered this a fundamental design flaw,
but since I didn't participate in developing the specs,
who am I to criticize?
</editorial>
Some people work around these problems with scripts, and
with text editors that insert a DOCTYPE on the fly.
I've taken another approach and have developed a system of
modular DocBook using XIncludes instead of external
entities. XInclude permits you to create modules that have
a DOCTYPE. Each module can be validated, and it can have
its own XIncludes. If you are doing SGML DocBook, then
XInclude won't help you, because it is only implemented
for XML. But if you are just getting
started, you might consider using XML instead.
I'm writing up a description of my modular XML doc scheme
and will post it shortly for others who want to try it.
Bob Stayton 400 Encinal Street
Publications Architect Santa Cruz, CA 95060
Technical Publications voice: (831) 427-7796
Caldera International, Inc. fax: (831) 429-1887
email: bobs@caldera.com