SGML: RefEntry SUBDOC entities
From server@amber.ora.com Tue Jul 16 02:37:58 1996
Sender: davenport@online.ora.com
Precedence: bulk
From: "W. Eliot Kimber" <kimber@passage.com>
To: Multiple recipients of list <davenport@online.ora.com>
Subject: Re: RefEntry SUBDOC entities
--------------------------------------------------------------------
At 07:14 PM 7/15/96 -0400, Robert Duncan [CONTRACTOR] wrote:
>I suspect that the reason that it works for your PARA example but not
>for mine is that PARA has mixed content while REFERENCE and REFENTRY
>both have element content at the point I'm trying to use the entity
>reference. And the trouble is that subdocument entities arrive as
>something like a character, not an element.
Yes, SUBDOC entities are essentially a special type of data entity and
therefore can only be referenced in PCDATA or RCDATA content or from ENTITY
attributes.
My personal recommendation is that you only use ENTITY attributes to refer
to SUBDOC entities. For a full explanation of why, see my paper, "Re-Usable
SGML: A Plea for SUBDOC", on the Passage Systems Web site,
http://www.passage.com/news/pubs/eliot/subdoc/subdoc.htm.
The short reason is that by restricting references to ENTITY attributes, you
can:
1. Define which element types can allow such references and in what contexts
subdocument references are allowed.
2. Ensure that processing applications get the data they expect when they
expect it.
3. Define policies such as "referenced subdocument must have the same
declaration set as "the referencing document and must have the same document
element as the referencing element" or "the referencing document must be
derived from the same architecture as the referencing document and must
conform to the same architectural form as the referencing element" or "I
just don't care, do what you want, I can handle it."
4. Use the "conloc" facility (part of the soon-to-be published SGML General
Facilities, packaged with (but not dependent on) the corrected HyTime
standard to further express the semantic of content reference rather than
simple cross reference or hyperlinking.
5. Create references to the subdocument by referring to the element that
refers to it.
For example, you could redeclare the RefEntry element type to include an
ENTITY attribute intended specifically to allow SUBDOC entity references:
<!ATTLIST RefEntry
%Common.Atts; -- Whatever Docbook normally has, doesn't matter --
SubdocRef ENTITY #CONREF -- When specified, RefEntry element has no
semantic content and subdocument is
taken to be its content. Should be
Refentry or equivalent. --
>
It can also be useful to declare an element type specifically intended to be
a "subdocument" element type, such as when you want to encapsulate something
like a chapter with additional metadata or something. This can also get
around the problem of some tools not supporting SUBDOC by letting you put
the real data a general text entity and then including it in the subdocument:
<!DOCTYPE RefEntrySubdocument PUBLIC "-//Hal and O'Reilly//DTD Docbook ...//EN"
[
<!ELEMENT RefEntrySubdocument O O (Refentry) >
<!ENTITY cat.1 SYSTEM "cat-1.sgm" -- NOTE: external text entity -- >
]>
<RefEntrySubdocument>
&cat.1;
</RefEntrySubdocument>
Finally, note that Exoterica's forthcoming Omnimark V3 will support
subdocument processing by allowing multiple documents to be parsed in the
same processing sessiont.
John McFadden has coined the term "microdocument" for what are essentially
(or literally, depending on how you declare them) subdocuments--a very good
term, I think. Exoterica provides some very nice demonstrations of how you
can use small documents with small but focused DTDs to build larger
documents dynamically. V3 also provides the functions you need to do
architecture-based processing, something that makes the use of subdocuments
more compelling because it lets you care less about the detailed element
structure of individual subdocuments. There should be quite a bit about this
issue at SGML '96.
Cheers,
Eliot
--
W. Eliot Kimber (kimber@passage.com)
Senior SGML Consultant and HyTime Specialist
Passage Systems, Inc., (512)339-1400
10596 N. Tantau Ave., Cupertino, CA 95014-3535 (408) 366-0300, (408)
366-0320 (fax)
2608 Pinewood Terrace, Austin, TX 78757 (512) 339-1400 (fone/fax)
http://www.passage.com (work) http://www.squirrel.com/squirrel/drmacro (home)
"If I never had existed, would you still remember me?..."
--Austin Lounge Lizards, "1984 Blues"