OBJECT specifying a run-time parameter example flawed?

In the Inclusions section of HTML 4.0
     http://www.w3.org/TR/WD-html40/struct/includes.html
there is an example of a run-time parameter for a declared
OBJECT:

-----8<-----excerpt-----8<-----
The following example illustrates how to specify run-time values
that are other objects. In this example, we send text (a poem,
in fact) to a hypothetical mechanism for viewing poems. The
rendering mechanism recognizes a run-time parameter named
"font" (say, for rendering the poem text in a certain font).
The value for this parameter is itself an object that inserts
(but does not render) the font object. The relationship between
the font object and the poem viewer object is achieved by 
(1) assigning the id "tribune" to the font object declaration
and (2) referring to it from the PARAM element of the poem 
viewer object (with valuetype and value). 

<OBJECT declare
     id="tribune"
     type="application/x-webfont"
     data="tribune.gif">
</OBJECT>
...view the poem in KublaKhan.txt here...
<OBJECT classid="http://foo.bar.com/poem_viewer" 
           data="KublaKhan.txt">
<PARAM name="font" valuetype="object" value="#tribune">
<P>You're missing a really cool poem viewer ...
</OBJECT> 

-----8<-----end_excerpt-----8<-----

The part that confuses me is the placement of
"...view the poem in KublaKhan.txt here..."
because it is not nested within an OBJECT element
(instead it just sits between two OBJECT elements).

Hmm.  I just realized that this text is italicized, sorry, emphasized, to
indicate that it's a meta comment about the
code.  But is this comment recommending that its position
is the location of the alternate text for browsers that don't
understand the OBJECT element?  Ah, no, I just understood -- the
phrsae is commenting on the fact that the next OBJECT
element is about to display a poem.

I find this practice of including meta-comments within example
code confusing.  I'd prefer to see the example code here
simply split up into two code fragments, with something in
between them in normal style.

Such as: the first OBJECT example, then "Later on in the document, you
could use the following OBJECT element, which causes the KublaKhan.txt poem
to appear in poem_viewer.  The PARAM element
used here passes the previously declared font information from the
earlier OBJECT element."  Then put the second OBJECT example.

The document conventions (convent.html) say that informative
notes will be emphasized, but that isn't very specific -- I
didn't realize before that this convention applied to comments
in code fragments.  Also, please consider marking notes that are
in the middle of example code with a visible separator (such as
"[") and/or use the Note style that is defined in your style
sheet.

Well, I have two more comments about this example.

1. For caching or "pre-loading" purposes, should a browser
   load a declared OBJECT at the moment of declaration,
   or only when it is referenced?  If the latter, what method
   of "preloading" OBJECTs does HTML 4.0 advocate?

2. Please make the alternate text in this example more
   helpful so that Web authors do not emulate its brevity
   and lack of alternate presentation.

I'm sure we're all sick of seeing alternate text/NOFRAMES
material that is nothing more than a flip "update your
browser!" --  so instead of "You're missing a really cool
poem viewer ...", how about "The cool poem viewer is not
available with your browser, but here is the poem it would
have displayed:
<BR>
In Xanadu did Kubla Khan ..."

Hope these comments are helpful.
-- 
E. Stephen Mack <estephen@emf.net>          http://www.emf.net/~estephen/

Received on Wednesday, 9 July 1997 23:31:19 UTC