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

[Ian Hickson]

On Mon, 12 Jul 2004, fantasai wrote:
>> Authors have long requested changes to HTML4
> 
> suggestion: changes -> enhancements (puts it in a more positive,
>                                       extend-not-replace light)

Fixed.

 
>> Requirements from such comments in mailing lists and other discussions were
>> examined, and from these sources a set of requirements and design goals were
>> derived:
> 
> Requirements were derived from requirements?
> How about just "Such comments"?

Fixed.


>> The key words "MUST", "MUST NOT",
> 
> Do you want to add a note about capitalization (or lack thereof, rather)?

Not really. Should we?


>> ...it is possible that authors would prefer to declare the page's forms
>> in advance, in the head element of XHTML documents (this does not apply
>> to HTML documents).
> 
> Replace with
>    Similarly, form elements in XHTML may now be nested (this does not apply
>    to HTML).
> 
> It's a more self-contained example, and the text actually occurs in the spec.

Fixed.


>> 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*).)


>> 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.


>> with which to multiply the base to get the resulting number
> 
> base -> significand, to be consistent with the previous sentence.

Oop. Fixed.

 
> 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".


> Probably should swap "A significand" -> "The significand" and "An 
> exponent" -> "The exponent". The reason is you need to refer to "the 
> number", so you need to have all the number bits be definitively 
> described (so that we're always talking about this one specific number).

*shrug*. Fixed.


>> while being easier to parse than some other floating point syntaxes
> 
> easier to parse or easer to read?

Parse.


>> Note that +0, 0e+0, +0e0 are invalid numbers (the minus sign cannot be 
>> replaced by a plus sign for positive numbers, it must simply be 
>> omitted). UAs must not submit numbers in invalid formats (whatever the 
>> user might enter).
> 
> Don't combine the note and the conformance requirement in the same 
> paragraph. I suggest moving the first sentence to the end of the 
> "Numbers must be submitted as" paragraph and the shifting the resulting 
> "UAs must not" paragraph to before the "This format is designed" 
> justification paragraph.

Changed "Note that" to "The strings".


>> See below for notes on IDN
> 
> Hyperlink "notes on IDN" instead of "below".

I urge you to concentrate on details that actually matter.


>> must have no value selected, unless a default value
> 
> I suggest removing that comma.

Doesn't really seem to aid in readability, but ok.


>> then the defaultValue DOM attribute has the specified value
> 
> missing end tag

Fixed.


> Extensions to theinput element
>> Empty fields (those with no value) do not need to match their type... 
>> Ranges The ERROR_TYPE_MISMATCH code is used for fields whose values do 
>> not match their types...
> 
> I think we should have a section that briefly introduces type-checking
> and includes all the random statements like this. They're currently
> scattered throughout the section, so the whole idea gets lost. (The section
> further down is too focused on the submission and DOM Events algorithms to
> help.)

Ok, added an intro section. However, the first sentence you quoted above 
isn't in it, as that's a really minor detail (and, to authors, should be 
pretty obvious since it has been that way forever), and the second one is 
actually covered by a more detailed summary in the DOM section, to which 
the sentence already links.


>> a sequence of digits 0-9, treated as a base ten integer
> 
> I think you should define integer somewhere and just refer to it with a 
> hyperlinked "integer".

Yeah, I've been thinking of doing that. Will bear that in mind.


>> For date and time types it must match the relevant format mentioned for
>> that type, having all the fields present and with the right number of
>> digits, with the right separating punctuation.
> 
> Can we let the time portions omit the seconds?

Yes.


> The datalist element and the list attribute
>>  text, email, , uri,
> 
> double comma?

Fixed.


>> 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.


> And you're requiring an algorithm again.

Actually if you carefully read that section, you'll notice that the 
algorithm isn't required. It is carefully phrased in the form of "the list 
shall be the one that would be formed by", thus making it a strict 
conformance requirement that the list be indistinguishable from the one 
described, but not specifying how it is implemented.


>> 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.

>> If the element is marked as disabled, if the autocompletion value is 
>> the empty string,
> 
> Why?

Why what?


>> or if the autocompletion value is not a valid value for the
>> control's type (for example, 20 is not a valid value for a datetime
>> control) then it must be ignored.
> 
> This should not be part of the same sentence. The way you have it
> written, it means that if I have an invalid but disabled value, it
> gets treated as the empty string and not ignored.

I don't understand how you read it that way, at all.


>> The author-specified list of predefined values may be augmented by
>> the UA's own autocompletion logic, for example the UA may remember
>> previous values that the user has entered.
> 
> autocompletion logic. For example,
> 
> "For example" is not a conjunction. You cannot use it to combine two
> full clauses.

Fixed.


>> This element should not be displayed.
> 
> This should probably be qualified by an "if the UA supports
> <datalist>" or somesuch. I do expect WF2 will be implemented
> piecemeal, insofar as the pieces are complete. <datalist> is one
> such feature.

Fixed.

 
>> To complement the new list attribute, a datalist element is introduced.
> 
> How about introducing the element _before_ you use it in your algorithm?

Fixed.


>> This element has two roles.
> 
> . -> :

Seriously, please concentrate on things that matter. When the text is
already correct, suggesting punctuation changes that only arguably
improve readability simply wastes your time and mine.


>> 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?


>> Authors must only put empty option elements
> 
> There's no reason I should not be able to do this:
> <datalist>
>    <select>
>      <option>text</option>
>    </select>
> </datalist>

Fixed.


>> For controls inside datalist  elements must never be successful.
> 
> remove "For"

Done (that was actually a type for Form, though).


>> 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.


>> inside the value attribute instead of inline
> 
> missing end tag

Fixed.


>> However, if the values are required to be shown
> 
> need to be shown

Fixed.


>> The UA could hove
> 
> have

Fixed.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'