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


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


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