RE: [docbook] Re: markup for mediaobject parameters

["Grosso, Paul" <pgrosso@ptc.com>]

> -----Original Message-----
> From: Norman Walsh [mailto:ndw@nwalsh.com]
> Sent: Friday, 2011 August 26 10:12
> To: docbook@lists.oasis-open.org
> Subject: [docbook] Re: markup for mediaobject parameters
> 
> "Grosso, Paul" <pgrosso@ptc.com> writes:
> > In DocBook, video and audio objects get marked up something like:
> >
> > <audioobject>
> >   <objectinfo>
> >     <title>optional description</title>
> >   </objectinfo>
> >   <audiodata fileref="xxx.wav">
> > </audioobject>
> >
> > At least in HTML, video and audio objects get marked up
approximately
> > something like the following (though actually each browser has its
> > own quirky requirements that are all different):
> >
> > <object various-attribute-assignments>
> >   <div>optional description</div>
> >   <param name="param1" value="value1">
> >   . . .
> >   <param name="paramN" value="valueN">
> > </object>
> >
> > There are other optional things and so forth, but my question is how
> > best to markup in DocBook the things that will map to the various
> > HTML <param> elements.  There can be any number of quite arbitrary
> > things.
> [...]
> > Is there a more official way? Has anyone seen another solution in
> > common practice? Am I missing something more obvious?
> 
> No, I haven't, and no, respectively.
> 
> I've wrestled with this occasionally, but the number and variety of
> parameters seem so varied and ill documented that I've never tried to
> build a rational model.
> 
> I don't really like the keywordset hack. Off the top of my head,
> either of the following seems better:
> 
> 1. Just add html:object to your schema and let people put in the
> literal objects. It's not clear to me that there's any portability
> anyway. And if you made it a choice in mediaobject, you could provide
> a fallback.
> 
> 2. Use PIs:
> 
> <audioobject>
>   <objectinfo>
>     <title>optional description</title>
>    </objectinfo>
>    <audiodata fileref="xxx.wav">
>     <?object-param key1 value1?>
>     <?object-param key2 value2?>
>    </audiodata>
> </audioobject>
> 
> That said, if you find a better solution, please do pass it along!

I don't like your suggestions, and I can't think of anything 
better than the keywordset "hack".  Let me try to explain.

The problem with just embedding html:object is that you have 
to structure your <object> code differently for every browser.  
I've been experimenting with IE7, Firefox 4, and Chrome 10. 
Just for example, here's some notes I have:

<notes>
IE requires classid on the object (unless it recognizes the type).

Chrome and Firefox cannot have classid on the object (at least
not for Windows Media Player).

All browsers obey the height and width better when they are
set on the object, and Firefox doesn't do anything unless
they are set on the object.

Firefox needs @data set to the path on object at least in 
some cases.

IE needs to have the path in a <param> whose name is "src".

Firefox can't have type set on object when doing embed.

autostart values of 0 and true seem to work for all three,
but 1 and false don't reliably.

IE7 doesn't execute the content of object, so fallback text
or nested objects don't work.
</notes>

So, what a friendly editor like Arbortext has to do is collect
the info from the markup and then generate HTML that will work
on as many browsers as possible.  The necessary HTML consists 
of multiple nested object elements, nested in just the right order,
with different ones of those object elements having different 
attributes set and different children param elements.  For example,
Firefox needs @data set to the referenced URL on object, but IE 
needs a child param element whose name is "src" and whose value 
is the URL.

So just allowing html:object would in theory allow a user to
insert the necessary code, but it would be close to 0 probability
they would get code in there that would work with all browsers.

Using PIs to insert params could in theory be handled in much
the same way as the keywordset idea in that the styling code
could pick up the values and then use them to emit the necessary
HTML code.  But parsing PIs the get the same info one can get
more easily when it's marked up in keywords does not seem like
a good tradeoff to me.  Using something like keywordset, one
could even write some validation code (in Schematron or your
own favorite command language) to do some validation, whereas 
that couldn't be done nearly as easily with PIs. 

I've got customers that want to mark up in DocBook and want
Arbortext's HTML publishing capabilities to have multimedia support.
If I go and tell them to insert PIs, they are going to come back
and say that doesn't sound like non-proprietary support.

So the only choices I see are to tell them that there is no
support for doing this in DocBook or to suggest they use
something like the keywordset solution.

paul