Kimber - HyTime FCS's

Subject: Re: HyTime FCS's
Date: 06 May 1998 00:00:00 GMT
From: "W. Eliot Kimber" <eliot@isogen.com>
Organization: ISOGEN International Corp.
Newsgroups: comp.text.sgml

Lloyd Rutledge wrote:
>
> Alison Lennon wrote:
>
> > In HyTime is there an ability to define the extents of axes of FCS's
> > based on an external entity. For example, if you have an NTSC video
> > entity can you in the document (not the DTD) alter the extents of your
> > fcs to match that of the specified video entity?
>
> HyTime alone doesn't have this ability.  Marker values that are
> defined only in "pure" HyTime must, either directly or indirectly,
> resolve eventually to marker numeric values specified explicitly in
> the document.

Lloyd's explanation of the Berlage architecture approach is correct.
HyTime provides the general facility of "marker functions" which are the
mechanism by which you connect the general HyTime representation of your
data to the realities of the data management and/or presentation system.
Because the possible set of such systems is unbounded, the HyTime
architecture cannot do more than provide a general integration mechanism
and some (hopefully) clear rules about how to use it in specific cases.

As Lloyd explains, a marker function must return axis markers. How a
given function does this is up to it. However, a marker function is
governed by a declared notation, which serves as the name of the
definition of how the marker is supposed to work (and which can be used
to connect a marker in a document to software that implements the
marker). The use of notations in this way provides the hook a general
HyTime engine uses to connect the marker function elements it finds to
the code that knows how to process those elements and give back axis
markers to the HyTime engine. You would expect any generalized HyTime
engine to provide an integration API for associating functions (say in
DLLs) with particular marker function notations.

For example, say you want a marker function that returns an axis marker
pair reflecting the real size of a graphic, which you will then use to
set the maximum dimensions of the axes of the finite coordinate space.
It might look something like this (first the declarations and then a
document that uses them):

<!-- External DTD subset: myfcs.dtd -->
<!-- This declaration set defines the elements needed to define
     finite coordinate spaces for use with event schedules. The FCS
     elements are used by reference from event schedule elements.
  -->
<!-- [1] -->
<!-- Declare use of the HyTime architecture: -->
<?IS10744 arch
  name="hytime"
  arc-public-id="ISO/IEC 10744:1997//NOTATION Hypermedia/Time-based
Structuring Language (HyTime)//EN"
  dtd-public-id="ISO/IEC 10744:1997//DTD AFDR Meta-DTD
Hypermedia/Time-based Structuring Language (HyTime)//EN"
  form-att="HyTime"
  renamer-att="HyNames"
  doc-elem-form="HyDoc"
  bridge-form="HyBrid"
  options="sched markfun valueref gadafe"
>
  <!NOTATION GraphicExtent
     PUBLIC "+//IDN isogen.com//NOTATION Graphic Extent Marker
Function//EN"
     -- Marker functions of this notation determine the extent of
graphics
        in terms of the measurement units of the governing coordinate
space
        along the axis for which the marker is used. Intended to be used
        to set the maximum extent of axes.
     --
  >
  <!ATTLIST #NOTATION GraphicExtent
     graphic    -- The graphic to get the extent of --
       CDATA    -- Value must be an entity name --
       #IMPLIED -- If not specified, the graphic that is the object of
                   the event for to which this marker function applies
                   (because it is used as part of the definition of the
                   event's extent). --
  >
  <!ELEMENT FCSDefDoc
    -- HyTime document that contains FCS definition and associated
resources --
    O O
    (fcs,
     AxisExtentDef+)
  >
  <!ATTLIST FCSDefDoc
     HyTime
       NAME
       #FIXED "HyDoc"
  >

<!-- [2] -->

  <!ELEMENT mfGraphicExtent -- Graphic Extent marker function --
    - O
    EMPTY
  >
  <!ATTLIST mfGraphicExtent
    graphic     -- Graphic we want the extent of --
      ENTITY
      #REQUIRED
    notation
      (GraphicExtent)
      #FIXED "GraphicExtent"
    HyTime
      NAME
      #FIXED "markfun"
  >

<!-- [3] -->

  <!ELEMENT fcs -- Finite coordinate space definition --
    - O
    EMPTY
    -- Elements in content used to indirectly define the
       extents of the axes.  See below. --
  >
  <!ATTLIST fcs
    id
       ID
       #REQUIRED -- So event schedules can point to it --
    axes
       CDATA
       #FIXED "horiz virspace
               vert  virspace"
       -- Two axes, measured in generic units --

 -- [4] --

    horiz        -- Defines extent of horizontal axis --
       IDREF
       #REQUIRED -- Points to its defintion --
    vert         -- Defines extent of vertical axis --
       IDREF
       #REQUIRED -- Points to its definition --

-- [5] --

    valueref     -- Defines definition-by-reference of attribue values
--
       CDATA
       #FIXED "horiz horiz
               vert vert"
    HyTime
       NAME
       #FIXED "fcs"
  >

<!-- [6] -->

  <!ELEMENT AxisExtentDef
    -- Axis extent definition: defines effective value of axis
definition
       attributes for FCS.
     --
    - -
    (#PCDATA | mfGraphicExtent)*
  >
  <!ATTLIST AxisExtentDef
    id
       ID
       #REQUIRED -- Always used by reference --
    HyTime
       NAME
       #FIXED "HyBrid"
  >
<!-- End of declaration set -->

Here's what the parts of the foregoing are:

1. I declare a notation to represent the marker function I need, in this
   case determining the extent of a graphic. I use a notation attribute
to
   define an argument for the function, in this case, a reference to the
   graphic (as an entity) that the marker function will examine.

   A generalized HyTime processor will normally provide a way to
integrate
   notation processors by notation external ID. In a purpose-built
system,
   you'd just make the connection in the code directly. In either case,
there
   must be a way to get from a mention of the notation in a document
   to the code that implements the function.

2. I decare a markfun-form element to use to invoke the marker function.
   Note that the element names the GraphicExtent notation as its
governing
   notation. It also specifies a graphic attribute, which corresponds to
   the graphic notation attribute.  When the mfGraphicExtent element is
   processed, it will be passed (as a grove node, of course) to the
   software function that implements the GraphicExtent notation. That
software
   will then grab the information it needs from the element and do
whatever
   it does.  In a generalized system, this is all done in terms of
groves.
   In a purpose-built system, it's done however it's done.

3. I declare a finite coordinate space element (fcs), which defines the
general
   configuration of an fcs. The fcs will then be used by reference from
   event schedule elements (fcs elements can also contain event
schedules
   directly).

   The axis attribute of the fcs element declares the names of the axes
   in the fcs and the measurement unit used for each axis. In this case,
   there are two axes, which I've named "horiz" (horizontal) and "vert"
   (vertical) as we are creating an FCS for presenting graphics. Here
I've
   used virtual units (generic quanta), rather than some real
measurement
   units, for simplicity. For this example, assume that the presentation
   software will handle translating the virtual units into to real units
   on the screen. This is the way most software works (think of TWIPS in
   Windows programming).

4. For each axis named in the axes attribute, you must declare an
attribute
   of the same name. These axis definition attributes define the extents
   of each axis. In a simple fcs definition, the value of the attribute
would
   simply be the definition. However, in this case we want to use a
marker
   function to define the extent based on the size of the graphic, so we
   have to define the attribute values indirectly.  Notice that both the
   horiz and vert attributes are declared as IDREF. This is so that they
   can point to the elements that define their "effective values" (that
is,
   the values that the fcs processor will use in place of their
syntactic
   values).

5. The fact that an attribute is setting its value indirectly is
declared
   using the valueref (value reference) attribute. The valueref
attribute
   associates attributes with the attributes that address their
effective
   values. In this case, the attributes address their own effective
values.
   You read the valueref attribute as follows: "the effective value of
the
   'horiz' attribute is addressed by the 'horiz' attribute."

   The valueref facility is a general facility of the HyTime
architecture.

6. I declare an element to hold the effective value of the horiz and
vert
   attributes. The value of an axis definition attribute has the lexical
   type "(NUMBER, granule?, ("#MDU", ratio, granule?)?)", so I can't
just
   point to an mfGraphicExtent element as I need to be able to specify
   the other parts of the axis spec. The definition of a specialized
element
   also makes it clearer what's going on (I hope).  Note that the
   AxisExtentDef is not something defined by the HyTime
architecture--I've
   made it up for my own purposes. I've derived it from the HyBrid form
   just to make sure it is architectural for the HyTime architecture.

   A typical instance of the AxisExtentDef might be:

   <AxisExtentDef id="horiz-def">
   <mfGraphicExtent graphic="picture1">
   </AxisExtentDef>

At this point we've defined the rules for our system: how to use the
real extent of graphics in the definition of FCSs. Now it only remains
to define an FCS instance so we can create event schedules that use it.
The foregoing declaration set can be used for many FCS instances.

<!-- document piconefcs.sgm -->
<!DOCTYPE FCSDefDoc SYSTEM "myfcs.dtd" [
  <!NOTATION GIF SYSTEM >
  <!ENTITY river-otter SYSTEM "rivotter.gif" NDATA GIF >
]>
<FCSDefDoc>
<fcs
  id="picture-one-fcs"
  horiz="axis-spec"
  vert="axis-spec">
<AxisExtentDef
  id="axis-spec">
<mfGraphicExtent
  graphic="river-otter">
</AxisExtentDef>
</FCSDefDoc>

Notice that both the horiz and vert attributes point to the same axis
extent definition element. This is because the marker function can
determine which axis it is being used for and return the corresponding
value for the graphic's extent.
This works because the use-by-reference is not a reference to the
syntactic content of the AxisExtentDef but to the semantic result of
processing it in a particular use context.  Technically, the effective
values of the horiz and vert attributes are determined at the time the
HyTime semantic grove is constructed, not at the time the document is
originally parsed.

An event schedule that uses this FCS might look like this (first the
declaration set and then a document that uses it):

<!-- External DTD declaration set: overlay.dtd -->
<!-- This declaration set defines the structures necessary to create
     event schedules that manage objects overlayed over a base graphic,
     such as putting labels over an image.  Intended to use instances
     of the FCS defined by documents that use "myfcs.dtd" declaration
set.
  -->
<?IS10744 arch
  name="hytime"
  arc-public-id="ISO/IEC 10744:1997//NOTATION Hypermedia/Time-based
Structuring Language (HyTime)//EN"
  dtd-public-id="ISO/IEC 10744:1997//DTD AFDR Meta-DTD
Hypermedia/Time-based Structuring Language (HyTime)//EN"
  form-att="HyTime"
  renamer-att="HyNames"
  doc-elem-form="HyDoc"
  bridge-form="hybrid"
  options="sched nmsploc reftype"
>
  <!ELEMENT GraphicOverlayDoc
    O O
    (GraphicOverlay+)
  >
  <!ATTLIST GraphicOverlayDoc
    HyTime
      NAME
      #FIXED "HyDoc"
  >
  <!ELEMENT GraphicOverlay
    -- Event schedule for doing things on top of graphics --
   O O
   (Header,
    BaseGraphic,
    OverlayEvent*)
  >
  <!ATTLIST GraphicOverlay
    fcs         -- Pointer to governing FCS --
      IDREF
      #REQUIRED
    HyTime
      Name
      #FIXED "evsched"
  >
  <!ELEMENT Header -- Metadata for the schedule --
    O O
    (Title,
     nmsploc*)
  >
  <!ELEMENT Title  -- Title of the schedule --
    O O
    (#PCDATA)*
  >
  <!ELEMENT nmsploc -- Name-space location address, for indirect ID refs
--
    - -
    (#PCDATA)*
  >
  <!ATTLIST nmsploc
    id
      ID
      #REQUIRED
    namespc  -- Name space --
      (elements |
       entities)
      elements -- Default: elements by ID --
    locsrc     -- The document we are addressing into --
      ENTITY   -- Document or subdocument entity --
      #IMPLIED -- Curre document if not specified --
  >

  <!ELEMENT BaseGraphic -- Event for base graphic --
    - O
    (BaseExtent) -- Content is extent specification --
  >
  <!ATTLIST BaseGraphic
    object     -- Graphic that is content of event --
      ENTITY
      #REQUIRED
    exspec
      CDATA
      #FIXED "1 1" -- Fixed tree location to address first subelement --
    reftype    -- Define addressing form used by attributes of the
element --
      CDATA
      #FIXED "exspec TREELOC" -- Exspec attribute is a treeloc --
    HyTime
      NAME
      #FIXED "event"
  >
  <!ELEMENT BaseExtent -- Fixed extent specification for the base
graphic --
    - O
    EMPTY
  >
  <!ATTLIST BaseExtent
     spec    -- Extent specification value --
       CDATA
       #FIXED "1 -1 1 -1" -- Base graphic always fills the FCS --
     HyTime
       NAME
       #FIXED "extent"
     HyNames  -- Remap the architectural content to the value of the
spec att --
       CDATA
       #FIXED "#ARCCONT spec"
  >
  <!ELEMENT OverlayEvent -- Event that overlays on the base graphic --
    - -
    (extlist,
     EventObject?)
  >
  <!ATTLIST OverlayEvent
    object     -- thing that is the content of the event --
      ENTITY
      #IMPLIED -- By default, the content of the EventObject subelement
--
    exspec
      CDATA
      #FIXED "1 1" -- Fixed tree location to address first subelement --
    loctype    -- Define addressing form used by attributes of the
element --
      CDATA
      #FIXED "exspec TREELOC" -- Exspec attribute is a treeloc --
    HyTime
      NAME
      #FIXED "event"
  >
  <!ELEMENT extlist -- extent specification list. --
    - -
    (#PCDATA)* -- Value is one or more dimension specs --
  >
  <!ATTLIST extlist
    HyTime
      NAME
      #FIXED "extlist"
  >
  <!ELEMENT EventObject -- Contains text to use as event object --
    - -
    (#PCDATA)*
  >
<!-- End of declaration set -->

This declaration set defines an event schedule element. The element
types should be pretty self explanatory. An event schedule consists of
one or more *events*. An event has an *extent*, which is the amount of
space within the governing FCS that it occupies, and one or more
*objects*, which are the data that the event is scheduling. In this
example I've created two different specializations of the event
architectural form: BaseGraphic, for defining the base graphic of the
schedule, and OverlayEvent, which is used to define the events that will
go on top of the base graphic.  Note that both event-form elements use
their content to define their extents. Here I've used the loctype
(reference location type) attribute to make the required exspec
attribute of the event elements into a fixed treeloc that will always
address the first subelement of the event elements. I can do this
because the DTD forces the extent element into a consistent place.
[Events define their extents by reference so that you can re-use the
same extent spec for many events. This is the normal case for
representing music, for example, where the extents reflect a relatively
small number of nominal durations for musical notes.]

For the BaseGraphic I've used architectural name remapping to fix the
value of the extent specification, which should always be "1 -1 1 -1",
meaning that the base graphic fills the FCS (which it will as the FCS
extent is defined in terms of the graphic's real size).  The HyNames
attribute tells the architectural processor where to find the values it
expects. In the case of the extent element form, it expects to find the
extent specification in the content. Here I've remapped the
architectural content (#ARCCONT) to the spec attribute. The
architectural processor will take the value of the spec attribute in the
client and use that as the content of the extent element it creates in
the architectural instance. Thus, given this markup in the client (base)
document:

<BaseExtent><!-- notice that all attribute values are fixed in the DTD
-->

The architectural instance will have:

<extent>1 -1 1 -1</extent>

There are many possible sophistications that I have not shown in this
example in order to keep it simple, such as using marker functions to
define the extents of the overlay objects, or using a third axis to
define the "z order" of the overlays.

Here is an instance of the event schedule that uses the fcs instance
shown above:

<!DOCTYPE GraphicOverlayDoc SYSTEM "overlay.dtd" [
  <!NOTATION SGML
    PUBLIC "ISO 8897:1986//NOTATION Standard Generalized Markup
Language//EN"
  >
  <!ENTITY the-fcs SYSTEM "piconefcs.sgm" CDATA SGML >
  <!NOTATION GIF SYSTEM >
  <!ENTITY river-otter SYSTEM "rivotter.gif" NDATA GIF >
]>
<GraphicOverlayDoc>
<GraphicOverlay
  fcs="pic-one-fcs">
<Header>
<Title>The Parts of an Otter</Title>
<nmsploc
  id="pic-one-fcs"
  locsrc="the-fcs">picture-one-fcs</nmsploc>
</Header>
<BaseGraphic
  object="river-otter">
<BaseExtent>
</BaseGraphic>
<OverlayEvent>
<extlist>
10 100
20 200
</extlist>
<EventObject>
The head
</EventObject>
</OverlayEvent>
</GraphicOverlay>
</GraphicOverlayDoc>

Here is the HyTime architectural instance for the FCS definition, as
produced by SGMLNORM (sgmlnorm -Ahytime piconefcs.sgm):

<HYDOC>
<FCS AXES="horiz virspace
           vert  virspace"
     ID="PICTURE-ONE-FCS"
     VALUEREF="horiz horiz
               vert vert">
</FCS>
<HYBRID ID="AXIS-SPEC">
<MARKFUN NOTATION="GRAPHICEXTENT">
</MARKFUN>
</HYBRID>
</HYDOC>

Here is the HyTime architectural instance for the event schedule
(sgmlnorml -Ahytime otterparts.sgm):

<HYDOC>
<EVSCHED FCS="PIC-ONE-FCS">
<NMSPLOC NAMESPC="ELEMENTS"
         LOCSRC="the-fcs"
         ID="PIC-ONE-FCS">picture-one-fcs</NMSPLOC>
<EVENT OBJECT="river-otter" EXSPEC="1 1" REFTYPE="exspec TREELOC">
<EXTENT>1 -1 1 -1</EXTENT>
</EVENT>
<EVENT EXSPEC="1 1">
<EXTLIST>10 100
20 200</EXTLIST>
</EVENT>
</EVSCHED>
</HYDOC>

You can find the formal definition of all the HyTime architecture
facilities at "http://www.ornl.gov/sgml/WG4/docs/n1920".  You can find
more information on HyTime, including pointers to work by Lloyd and
others, at the HyTime User's Group Web site, "http://www.hytime.org".  I
am in the process of finishing the first usable version of a
generalized, grove-based, HyTime engine, called "PHyLIS" (Personal
HyTime Linking Information System). PHyLIS will not do anything with
event schedules out of the box, but as the source code (VB5) will be
provided, it would not be hard to extend it yourself if you cared to. It
would merely be a matter of writing code to interpret HyTime
architectural documents like the ones above to populate the FCS-specific
properties of the HyTime semantic grove and then write new components to
take advantage of those properties. [It's not quite ready for general
availability, but if you'd like an early look at the code, let me
know.]  Implementing this example in particular would not be hard to do
at all.

--
<Address HyTime=bibloc homepage="http://www.drmacro.com">
W. Eliot Kimber, eliot@isogen.com
Senior SGML Consulting Engineer, Highland Consulting
2200 North Lamar Street, Suite 230, Dallas, Texas 75202
+1-214-953-0004 +1-214-953-3152 (fax)
http://www.isogen.com (work)</Address>