[whatwg] short comments (WF2), set I

[fantasai]

> Authors have long requested changes to HTML4

suggestion: changes -> enhancements (puts it in a more positive,
                                      extend-not-replace light)

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

> The key words "MUST", "MUST NOT",

Do you want to add a note about capitalization (or lack thereof, rather)?

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

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

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

> with which to multiply the base to get the resulting number

base -> significand, to be consistent with the previous sentence.

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

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

> while being easier to parse than some other floating point syntaxes

easier to parse or easer to read?

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

> See below for notes on IDN

Hyperlink "notes on IDN" instead of "below".

> must have no value selected, unless a default value

I suggest removing that comma.

> then the defaultValue DOM attribute has the specified value

missing end tag

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

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

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

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

double comma?

> When a control has a list attribute

Your tenses are screwed up in this paragraph.
Get Eira to check it, you probably won't listen to me.
(And she's probably better at it than I am.)

And you're requiring an algorithm again.

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

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

Why?

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

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

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

> To complement the new list attribute, a datalist element is introduced.

How about introducing the element _before_ you use it in your algorithm?

> This element has two roles.

. -> :

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

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

But that sentence expressly forbids it. What you /mean/ to say, afaict, is
that authors may put
EITHER
   - empty option elements
OR
   - other content that would normally be valid in the <datalist>'s parent
in the <datalist>.

> For controls inside datalist  elements must never be successful.

remove "For"

> This data is not made available to the page DOM.

Do we need a must requirement for this?

> inside the value attribute instead of inline

missing end tag

> However, if the values are required to be shown

need to be shown

"Requirement" is too strong for this case, imo.

> The UA could hove

have


  ~fantasai