[Timesheets LC comment] Index Function

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

Received on Saturday, 1 March 2008 22:52:46 UTC