Re: Including verbatim text in a document...

["W. Eliot Kimber" <eliot@xxxxxxxxxxxxxx>]

At 05:27 AM 9/1/98 -0400, Norman Walsh wrote:

>So, in the next release of the DocBook DSSSL Stylesheets, I'm
>including support for the following clever trick/dirty hack
>(choose one ;-), unless someone talks me out of it.
>
>  <!DOCTYPE para PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
>  <!ENTITY program SYSTEM "program.c" CDATA linespecific>
>  ]>
>  <para>
>  Here's my listing:
>  <programlisting>
>  <inlinegraphic entityref="program"></inlinegraphic>
>  </programlisting>
>  </para>
>
>Basically, if the ENTITYREF on GRAPHIC/INLINEGRAPHIC has the
>LINESPECIFIC notation, I'm going to slurp it up (with James'
>read-entity extension in Jade) and spit it out.

The "value reference" facility of HyTime 2nd Edition (clause 7.6.2)
provides a formal definition of the use-by-reference semantic. Note that in
HyTime, use-by-reference of non-SGML data is meaningful because all data is
normalized into groves, so you are combining groves, not different source
data types.  The facility lets you define the value of any attribute, the
semantic content of an element, or the value of the entire element by
reference.

The key to the valueref facility is the "valueref" attribute, which
declares how the values of various properties are being addressed. In this
case, the property being addressed is the effective content of the
inlinegraphic element, the value of which is being addressed by the
'entityref' attribute.  The new declaration for inlinegraphic would be:

<!ATTLIST inlinegraphic
   -- Normal Docbook attributes omitted for clarity --
   entityref  -- Pointer to effective semantic content of the element --
     ENTITY
     #REQUIRED

   -- Attributes from HyTime architecture: --
   valueref  -- Define how effective value of content is addressed --
     CDATA
     #FIXED "#CONTENT entityref" -- entityref att addresses semantic
content --
   HyTime
     NAME
     #FIXED "HyBrid" -- Derive from HyTime arch so valueref att is 
                        recognized --
>

In terms of HyTime's formal grove-based processing model, using the
"read-entity" function is really calling a grove constructor for textual
data. The DSSSL code, which operates on groves, then has no difficulty
processing the resulting grove in whatever way is meaningful to you, the
author of the style sheet (echoing out the data, pretty printing the code,
etc.). 

Note that the value reference facility, which is only about
use-by-reference, is different from the current Xlink show="embed" in that
it completely separates use-by-reference from hyperlinking. For example, I
could make the inlinegraphic element also be a hyperlink in addition to
being a use-by-ref:

<!ATTLIST inlinegraphic
   -- Normal Docbook attributes omitted for clarity --
   graphic-description  -- Pointer to description of the graphic --
     IDREFS
     #REQUIRED
   entityref
     ENTITY
     #REQUIRED
   -- Attributes from HyTime architecture: --
   valueref  -- Define how effective value of content is addressed --
     CDATA
     #FIXED "#CONTENT entityref" -- entityref att addresses semantic
content --
   HyTime
     NAME
     #FIXED "clink" -- Derive from HyTime arch so valueref att is
recognized --
   HyNames
     CDATA
     #FIXED "linkend graphic-description"
>

Now I've made the inlinegraphic element *both* a hyperlink, which you use
the "graphic-description" attribute for (presumably to link to the textual
description of the graphic--an artificial example I realize), and a
use-by-reference, which you use the "entityref" attribute for. With Xlink,
you can't have both facilities applied to a single element. [I think this
is a weakness in Xlink, but I also recognize the significant simplifying
effect of not breaking out the two semantics separately.]

Cheers,

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


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist