[whatwg] Re: short comments (WF2), set I

[fantasai]

(Please don't send mailing list messages to my regular address.
  Either Reply All to get fantasai.lists, or just send it to the
  list. Thanks~)

Ian Hickson wrote:

> On Mon, 12 Jul 2004, fantasai wrote:
> 
>>>The key words "MUST", "MUST NOT",
>>
>>Do you want to add a note about capitalization (or lack thereof, rather)?
> 
> Not really. Should we?

IIRC, one person did complain.

>>>The children of a form element must be block-level elements, unless one of
>>>the ancestors of the form element is a td, th, li, dd, or block-level element
>>>other than div.
>>
>>And if they're not?
> 
> Fixed. But you might want to suggest a better way of phrasing it. (The 
> content model then would be (%block* | %inline*).)

I don't see any problem with the phrasing, except that the comma before
"unless" should be removed.

>>>A significand is an optional minus sign (U+002D, "-"), an integer, and
>>>optionally a decimal point (U+002E, ".") and an integer representing
>>>the fractional part.
>>
>>...optionally a decimal point (U+002E, ".") >followed by< an integer...
> 
> There's no "followed by" in the first part of the list. I don't really 
> understand why one would be better in the second part.

The "followed by" makes it clear that you are listing a sequence, not
a set. In other words, that 23-.4 is not valid. And you're right, it
should be in the first part of the sentence.

    The significand is an optional minus sign (U+002D, "-") followed by
    an integer and optionally a decimal point (U+002E, ".") and an integer
    representing the fractional part. The exponent is a lowercase literal
    letter "e" followed by an optional minus sign and an integer representing
    the index of a power of ten with which to multiply the significand to
    get the actual number.

>>resulting number -> desired number
>>(If you're multiplying two numbers, you'll always have a resulting number,
>>  even if that resulting number isn't the number you wanted.)
> 
> Used "actual number".

Pretty good. How about "number's value", though?

>>>Note that +0, 0e+0, +0e0 are invalid numbers
> 
> Changed "Note that" to "The strings".

Nice.

>>>When a control has a list attribute
>>
>>Your tenses are screwed up in this paragraph.
> 
> That entire sentence was way too complicated to understand. I've split it 
> into multiple paragraphs.

Still have verb construction parallelism problems:
    If the attribute is present but either specifies an ID that is
    not in the document, or specifies an element that is not an
    (X)HTML datalist or select, then it is ignored.
vs.                            ^^^^^^^^^^^^^^^^^^^
   The list of autocompletion values shall be given

They should both be "shall be" or both be "is".

You have this problem throughout the document. The inconsistency
makes all the "shall"s sounds silly, like you're trying to use an
older form of English but don't really know what you're doing.

>>>The UA may use the label attribute to annotate the value in its interface.
>>
>>The UA /should/ use the label attribute, and if there is no label 
>>attribute, it should use the text content of the <option>
> 
> It's the UA's UI. We're not requiring anything that specific.

It's not a requirement, it's a recommendation. Prepend "If the UA
chooses to annotate the value in its interface". If the UA wants
to use the label, it should preferably use a labeling scheme
consistent with what other annotating UAs use.

>>>It provides a list of data values, in the form of a list of option
>>>elements, and it may be used to provide an alternate representation
>>>of the form for user agents that do not support this specification.
>>
>>The second half of the sentence is not clear. It took me awhile to
>>figure out what you meant, and I already knew from the mailing list
>>how you mean to use <datalist>.
> 
> Any suggestions for improvements?

... and it may be used to provide fallback content for user agents that
do not support this specification.

>>>This data is not made available to the page DOM.
>>
>>Do we need a must requirement for this?
> 
> It's an example, so no. It's just stating a fact given what the spec
> already says.

I hadn't noticed that in the spec anywhere. I suppose it's implied
because there's nothing to say that the data /does/ appear in the DOM...

~fantasai

-- 
http://fantasai.inkedblade.net/contact