Dear SYMM WG-
This is a Last Call review comment from the SVG WG on the SMIL
Timesheets 1.0 specification, W3C Working Draft 10 January 2008,
http://www.w3.org/TR/2008/WD-timesheets-20080110/ . Please let us know
if you have any questions by replying to www-svg@w3.org.
3.4 Index Functionality
-----------------------
"Thus, the index() function becomes a shortcut to each of the
elementscomposing the ordered list and provide index numbers for the
DOMActivateevent references in the Timesheets."
The 'index()' function is not well defined. A good definition would
clearly list the allowed syntax, and say what it returns instead of
trying to define it by example. It should say if the first item in the
list has index 0 or 1 for example.
Again, the order of the selected elements list should be clearly defined
(either in this spec or by reference to another spec). It can be
expected that users want to add elements dynamically using DOM, and that
a timesheet continues to work as expected in such cases.
---
There is no example of using the 'index()' function with both
parameters, and the use cases for the second parameter are slightly unclear.
---
4.2 The item element
--------------------
"It can reference a media element or a set of elements by the element's
tag, id or class; the syntax and processing is the same to the
CSSselector [CSS2] syntax."
The comments on section 3.2 applies here too. BTW, why is the item
element defined twice? Consider making section 3.2 informative.
Also it sounds like <item> can only work on "media elements". That would
limit the use-cases in SVG. Please make that a MAY or informative statement.
---
"The select attribute links the timesheet to the document. Its value is
a comma-separated list of CSS selectors [CSS2]."
This makes it sound like a way to create a link between the documents
(like a <link> element). It might be better worded, "The select
attribute associates (or applies, or ties, or binds) the Timesheets
element to one or more node in the target document."
Please consult the CSS WG if you haven't already done so, to make sure
that comma is the best list-separator character for selectors.
---
"The attribute follows the same syntax as the CSS selectors, so that the
elements can be referenced by their name, id, or class, or a more
complex combination of the selectors."
The attribute, or each list value? Please clarify and add an example
showing the use of a list of selectors.
---
"If the attribute targets multiple elements in the host document, item
controls all of them based on the host document order."
How is the control based on the host document order?
---
"When the selector matches more than one element, an ordered list
ofelements is constructed."
...and the ordered list is ordered by what exactly? Is it "live" or not?
---
"The beginInc attribute increments the begin time of each of the
elements,but the first one, by the defined value. Note that the begin
time of thefirst element is never modified. The beginInc attribute has
to be apositive integer."
What important use-cases are addressed by the 'beginInc' attribute?
Please add an informative section describing that.
"each of the elements" is "each of the selected elements"? Clarify please.
Please define what happens if the beginInc attribute is not a positive
integer (e.g. a float value or a negative value)?
---
"Note that the begin time of the first element is never modified."
That's repeating the "but the first one" again, it's confusing.
---
"The item element defines one function: index()."
Is this to say that section 3.4 should be made informative? Please keep
all normative text in one place.
---
"Thus, it can be used to automatically generate index numbers for both
internal and external events within the begin, dur, or end attributes of
the item, animate, set, animateMotion, and animateColor elements."
Host languages may wish to add further attributes where it can be used,
please allow that. And the list of elements which it applies to should
of course also allow for host languages to add elements
(svg:animateTransform).
---
"The index() function has the format:index(<selector>, <indexStart>)"
Is extra whitespace allowed (start, middle, end)? What happens if the
comma is missing?
Please consult the CSS WG if you haven't already done so, to make sure
that comma is the best separator character for selectors.
---
"The <selector> parameter has to be a valid CSS selector, while the
<indexStart> parameter has to be a positive integer value."
Clarify what happens if the above conditions are false (each
individually or both at the same time).
---
"If there are no elements in the host document matching the CSS
selector, the index() function is not called."
Please clarify that it is a MUST requirement.
---
"If there are elements in the host document matching the CSS selector,
an ordered list of the elements is constructed. In this case, when an
element from the list is activated, the index() function returns the
index of such element within the list plus the <indexStart> value."
Please define the index start offset (0 or 1 usually). Here it might be
nice to point out something about negative <indexStart> and indexing.
The order of the selected list comment (mentioned in other comments)
applies here too.
---
"The item element can contain:
- time containers: seq, par, and excl
- prefetch elements
- animation elements: animate, set, animateMotion, and animateColor
- and other item elements"
Allow host languages to add elements here, e.g <svg:animateTransform> or
host language time containers.
---
"However, the direct child of the item element can only have one child
or none."
Why? It may have several, but timesheets MUST not process them. Clarify.
---
"All other children than the first one are ignored."
What if the first child is a textnode? Clarify that it's the first
element child.
---
"If the item element has several descendants they have to be included
within a child time container."
Why? Please clarify. Also, if this is a normative statement, please use
the keyword MUST.
---
"Furthermore, the parent item element limits the scope of the CSS
selectors of the descendant item, prefetch, animate, set, animateMotion,
and animateColor elements to match only descendant elements of the host
language elements selected by the parent item element, as described in
the SelectionMechanism section."
It's not clear to me why this has to be limited to only one step of
nesting. Since the need for limiting the scope of CSS selectors is
cited, why is it that one is prevented from further limiting the scope
by nesting item elements deeper?
Regards-
-Doug Schepers, on behalf of the SVG WG