Kimber - Reference to an NDATA entity

Subject: Re: Reference to an NDATA entity
Date: 01 Feb 1998 00:00:00 GMT
From: "W. Eliot Kimber" <eliot@isogen.com>
Organization: ISOGEN International Corp.
Newsgroups: comp.text.sgml

Johan Martens wrote:
>
> can somebody explain to me the consequence of a reference towards an
> NDATA entity from within a content?

The only 8879-defined consequence is that the parser informs the
processing system that it has encountered an NDATA entity reference and
gives it the relevant information. It is up to the processing system to
decide what to do with it.

NDATA entity references in content were primarily intended to be used
for representing special characters where you'd use an image for the
character. However, subsequent experience has provided both better ways
to handle characters generally and has shown that referencing data
entities from character data isn't really a good idea, for a variety of
reasons.

As a rule, NDATA, CDATA, and SUBDOC entities should be referenced using
ENTITY attributes of elements, where ENTITY attributes are attributes
whose value prescription is "ENTITY", meaning that they name an NDATA,
CDATA, SDATA, or SUBDOC entity declared in the document:

<!ATTLIST Graphic
    image-object ENTITY #REQUIRED
>

Where an instance might be:

<Graphic image-object="Picture-One">

It's still up to the processing system, not the SGML parser, to
determine what such references mean.  However, the value reference
facility of the HyTime standard gives you a way to indicate your intent
as a document type designer. For example, you can indicate that the
referenced entity should be treated *semantically* as the content of the
element making the reference:

<!ELEMENT Graphic EMPTY >
<!ATTLIST Graphic
    image-object ENTITY #REQUIRED
    valueref     CDATA  #FIXED "#CONTENT image-object"
    HyTime       NAME   #FIXED "hybrid"
>

The 'valueref' attribute is defined by the HyTime architecture. It's
value is a list of name pairs.  In this example, the first keyword,
"#CONTENT" means that the attribute named by the second name is a
pointer to the "effective" content of the element. The second name is
the name of the image-object attribute. Thus, the valueref attribute is
declaring that the semantic content of the Graphic element is whatever
the image-object attribute points at.  The image-object attribute is
declared as type "ENTITY", so whatever entity it names will become the
semantic content of the graphic element. [The HyTime attribute simply
associates that element with the HyTime architecture, which defines the
meaning of the valueref attribute--without this association, you
wouldn't know for sure that this valueref attribute was really the one
defined by HyTime.]

This makes it clear that the Graphic element is using a graphic by
reference, rather than creating a hyperlink to the graphic (which it
could also be doing).

Here's an example of an element that creates a hyperlink to a graphic:

<!ELEMENT ImageLink EMPTY >
<!ATTLIST ImageLink
   image-object ENTITY #REQUIRED
   HyTime       NAME   #FIXED "clink"
   HyNames      CDATA  #FIXED "linkend image-object"
>

Note that the image-object attribute declaration is exactly the same as
for the Graphic element.  However, the semantic of the ImageLink element
is very different from the Graphic element: it is a hyperlink, not a
use-by-reference.  We know it's a hyperlink because the HyTime attribute
value is "clink", which is one of the HyTime-defined hyperlinking forms,
and the value of the HyNames attribute is mapping the HyTime-defined
attribute name "linkend" to the local name "image-object", which means
that the image-object attribute is pointing to the other end of the
link.

The distinction between a use-by-reference and a link is important
because we usually have different behaviors associated with the two. The
result of a use-by-reference is usually the same as having put the data
referenced at the point of reference to start with. The result of a
hyperlink is usually to enable navigation between the ends of the link
(in this case, the reference to the image and the image itself).

You might be saying: "why do I need the HyTime stuff, the element types
make it clear what the difference is?"  That's true only because I chose
names that are likely to be meaningful to most of the readers of
comp.text.sgml (that is, speakers of English familiar with SGML).
Consider these two element type declarations:

<!ELEMENT X EMPTY >
<!ATTLIST X
   image-object ENTITY #REQUIRED
>
<!ELEMENT Y EMPTY >
<!ATTLIST Y
   image-object ENTITY #REQUIRED
>

Which one is the use-by-reference and which one is the hyperlink (given
that one is one and the other is the other)? Can't tell, because the
form of reference to the image isn't distinguishing.  However, if I add
the above HyTime stuff to the declarations, you can tell unambiguously:

<!ELEMENT X EMPTY >
<!ATTLIST X
   image-object ENTITY #REQUIRED
   HyTime       NAME   #FIXED "clink"
   HyNames      CDATA  #FIXED "linkend image-object"
>
<!ELEMENT Y EMPTY >
<!ATTLIST Y
   image-object ENTITY #REQUIRED
   valueref     CDATA  #FIXED "#CONTENT image-object"
   HyTime       NAME   #FIXED "hybrid"
>

Now you can tell that X is the link and Y is the use-by-reference,
because they use the HyTime-defined attributes to so declare themselves.
Even if you don't know what "valueref" and "clink" mean, you know that
they probably have something to do with HyTime because of the HyTime
attribute (which associates the elements with the HyTime architecture).
So all you have to do is go to the HyTime standard and see if it defines
anything called "valueref" or "clink".  It does, so there you go--you
can, from that, figure out what these things mean, at least with respect
to the semantics HyTime defines.

The value reference facility is defined in clause 6.7.1, which you can
find at
"http://www.ornl.gov/sgml/wg8/docs/n1920/html/clause-6.7.html#clause-6.7.1".
The clink element form is defined clause 8.2.2, which you can find at
"http://www.ornl.gov/sgml/wg8/docs/n1920/html/clause-8.2.html#clause-8.2.2".

Finally, note that the HyTime architecture doesn't say what the value
reference or hyperlink mean from a presentation or behavior
standpoint--it's still up to your processing application to provide
that, but you can at least provide it generically rather than in terms
of specific element types. You can say "make all hyperlinks act like
this" or "make all use-by-reference act like this", rather than having
to say "Make the X element behave this way and make the Y element behave
that way".  When you have a lot of different element types, this is a
significant savings in presentation and behavior specification effort.

--
<Address HyTime=bibloc>
W. Eliot Kimber, Senior Consulting SGML Engineer
Highland Consulting, a division of ISOGEN International Corp.
2200 N. Lamar St., Suite 230, Dallas, TX 95202.  214.953.0004
www.isogen.com
</Address>