[whatwg] Suggested changes to Web Forms 2.0, 2004-07-01 working draft

Matthew Thomas mpt at myrealbox.com
Mon Jul 5 00:22:15 PDT 2004


The following are suggested changes to  
<http://whatwg.org/specs/web-forms/current-work/> as it was at  
approximately, erm, 2004-07-04T11:00:00.00Z. Some are corrections of  
errors. Others are suggestions for making the specification easier to  
understand. Still others are questions, highlighting points I (as a  
moderately educated (X)HTML author) couldn't understand enough to  
suggest a specific clarification.

A few, finally, propose changes to the Web Forms syntax or rules. For  
easy reference, these are:
24. datetime - syntax
28. local-datetime - name of element
31. range - syntax
36. date/time fields - default values
45. accept attribute - handling invalid values
47. disabled attribute - for form element
58. autofocus attribute - ignoring when appropriate

> ...
> Abstract
> ...
> Web Forms 2.0 applies to both HTML and XHTML user agents, and provides  
> new strongly-typed input fields, new attributes for defining  
> constraints, a repeating model for declarative repeating of form  
> sections, new DOM interfaces, new DOM events for validation and  
> dependency tracking, and XML submission and initialization of forms.

1.  Suggestion: This sentence is unnecessarily long for
     reading on the Web. Split it up.
     *   "agents, and" --> "agents. It"

> ...
> This specification also standardises and codifies existing  practice  
> in areas that have not been previously documented.

2.  Suggestion: Shorten this sentence, and (assuming
     suggestion 1) make it parallel with the previous one.
     *   "This specification also" --> "It also"

> ...
> 1. Introduction
> ...
> Authors have long requested changes to HTML4 to support some of their   
> more common needs. For example, take this extract from a  recent post  
> written by an anonymous poster on the popular topic-driven  Slashdot  
> forum:
>
> There are three things that need adjustments to get decent forms in  
> HTML.
>
> First, have the option of not redrawing the page upon submission.  
> [...]  Second, have a "grid" widget that allows spreadsheet-like data  
> entry  grids.
>
> Third, have validation options such as <input type="text" name="foo"  
> format="number" decimals=2> or perhaps <input type="number"   
> name="foo" decimals=2>
>
> This post is typical of the kind of comments made by Web authors.   
> Requirements from such comments in mailing lists and other discussions  
>  have been examined, and from these sources a set of requirements and   
> design goals were derived:

3.  Suggestion: Remove the example post, since (a) people
     could be misled into thinking that everything it asks
     for is in Web Forms 2.0, when it's not, (b) people could
     be misled into thinking the spec was created by typical
     Slashdot-level intellects, when it's not, and (c) it
     unnecessarily lengthens the spec.
     *   "needs. ... Requirements" --> "needs. Requirements"

4.  Error: Mismatched tense. Either:
     *   "discussions have been" --> "discussions were"
     *   "design goals were" --> "design goals have been"

> ...
> *   Ease of authoring for authors with limited knowledge
>     about XML, data models, etc, but familiar with
>     commonly used languages such as HTML and ECMAScript.

5.  Error: Mismatched tense. Either:
     *   "with limited" --> "who have limited" and
         "but familiar" --> "but who are familiar"
     *   "familiar with" --> "good knowledge of"

> *   Basic data typing, providing new controls for commonly
>     used types so that authors do not need to repeatedly
>     design complicated widgets such as calendars.

6.  Suggestion: Use more standard terminology.
     *   "widgets" --> "controls" throughout the spec
     *   "widget" --> "control" throughout the spec

> *   Simpler validation on the client side (while
>     recognizing that server  side validation will still be
>     required), with declarative solutions for the common
>     case, but strong DOM support so that less common cases
>     can easily be handled using scripting.

7.  Question: Was "the common case" really meant here?
     *   "the common case " --> "common cases"

> *   Dynamically adding more fields (repeating structures)
>     on the client side without scripting.

8.  Suggestion: Change from a verb phrase to a noun phrase,
     like (almost) all the other points.
     "Dynamically adding" --> "Dynamic addition of"

> ...
> *   This specification should be implementable in full on
>     devices with limited resources.

9.  Suggestion: Shorten this sentence by changing it to a
     noun phrase, like all the other points.
     "This specification should be implementable in full" -->
     "Full implementability"

> 1.1 Relationship to HTML
> ...
> It is  expected to be implemented in ordinary HTML user agents  
> alongside existing forms technology, and indeed, some of the features  
> described in this draft have been implemented by user agents as  
> ad-hoc, non-standard extensions  for many years due to strong market  
> need.

10. Suggestion: Split the sentence for readability.
     *   "technology, and indeed" --> "features. Indeed"

> ...
> 1.3. Relationship to  XForms
> ...
> XForms 1.0 is well suited for describing business logic and data  
> constraints. Unfortunately, due to its dependencies on technologies  
> not widely supported by Web browsers, it has not been widely  
> implemented by those browsers itself.

11. Error: Mismatched number: "browsers", "itself".
     *   "itself" --> "either"

> This specification aims to simplify the task of  transforming XForms  
> 1.0 systems into documents that can be rendered on every day Web  
> browsers.

12. Error: "This specification" unavoidably refers to the
     specification mentioned two sentences previously, which
     is XForms 1.0, which is not what you mean.
     *   "This specification" --> "Web Forms 2.0"

13. Error: Wrong part of speech.
     *   "every day" --> "everyday"

> ...
> The structured XML instance data stored on the server-side (e.g. in a   
> database) is converted by the XForms processor into name/value pairs  
> that are then used by the UA to prefill the form.

14. Error: Wrong part of speech. Either:
     *   "on the server-side" --> "on the server" (preferred)
     *   "stored on the server-side" --> "stored server-side"

> ...
> 1.5 Missing features
> ...
> *   Elements or properties to create a "tabbed" or
>     "wizard" interface. This need will be addressed in a
>     separate specification.

15. Error: Tabbed interfaces and "wizard" interfaces are
     not, and have never been, the same or even related.
     *   'a "tabbed" or "wizard" interface. This need' -->
         'tabbed interfaces or "wizard" interfaces. These
         needs'

> ...
> *   A grid or spreadsheet editing control. This need may
>     addressed in a future version of this specification.

16. Error: Missing word.
     *   "may addressed" --> "may be addressed"

> *   A declarative way of specifying that one list should
>     filter the view of a second list. Again, however,
>     this need may addressed in a future version of this
>     specification.

17. Error: Missing word.
     *   "may addressed" --> "may be addressed"

18. Suggestion: Repetition of "this" is clumsy. (And it will
     still be clumsy no matter what Web Forms is or isn't
     renamed to later.)
     *   "this specification" --> "Web Forms"

> ...
> 1.6. Conformance  requirements
> ...
> Implementations that do not support scripting (or which have their   
> scripting features disabled) are exempt from supporting the events and  
> DOM interfaces mentioned in this specification.

19. Suggestion: Use RFC 2119 terminology.
     *   "are exempt from supporting" --> "may decline to
         support"

> Other aspects of this specification that are defined in terms of an  
> events model must still act as if events were supported.

20. Error: Aspects of an inanimate specification cannot act.
     *   "Other aspects" --> "For other aspects"
     *   "model must still" --> "model, such user agents must
         still"

> ...
> While user agents should support all possible values, there may be  
> implementation-specific limits.

21. Suggestion: Make the allowance more explicit.
     *   "there may be implementation-specific limits." -->
         "they may impose limits if necessary."

> ...
> 2. Extensions to form  control elements
> ...
> text
>     A free-form text input, nominally free of line breaks.
> password
>     A free-form text input for sensitive information,
>     nominally free of line breaks.

22. Suggestion: Use more standard terminology.
     *   "input" --> "field"

> ...
> The form element is therefore allowed in the head element of XHTML  
> documents, although only when the form element is empty.

23. Error: "Although" can only introduce a complete clause,
     but "only when the form element is empty" isn't one.
     *   "although" --> "but"
     (Note that this sentence is repeated, somewhat
     unnecessarily, in the example in section 1.7.)

> ...
> 2.1. Extensions to the  input element
> ...
> datetime

24. Suggestion:  
http://listserver.dreamhost.com/pipermail/whatwg-whatwg.org/2004-July/ 
000875.html

>     A date and time (year, month, day, hour, minute,
>     second, fractions of  a second) encoded according to
>     [ISO8601] with the time zone set to UTC

25. Suggestion: The [ISO8601] citation key is used as text
     here, but other citation keys are not, even to the
     extent of writing "the HTML4, XHTML1.1, DOM2 HTML, DOM3
     Core, and DOM3 Events specifications ([HTML4], [XHTML1],
     [DOM2HTML], [DOM3CORE], [DOM3EVENTS])". Pick a policy
     and stick with it.

> ...
>    one or more digits for the fraction of a second, a
>    literal "Z".

26. Suggestion: Use "and" to reassure readers that the
     sequence has been written down completely.
     *   "second, a" --> "second, and a"
     *   similar for local-datetime
     *   similar for date
     *   similar for month
     *   similar for week
     *   similar for time.

> All the numbers must be in base ten and zero-padded if necessary.  
> e.g.: 1995-12-31T23:59:59.99Z

27. Error: Capitalization. Either:
     *   "necessary. e.g." --> "necessary. E.g." throughout
         the spec
     *   "necessary. e.g." --> "necessary, e.g." throughout
         the spec

> ...
> local-datetime

28. Suggestion: Rename this value so it is easier to find in
     alphabetically sorted references and tutorials.
     *   "local-datetime" --> "datetime-local"

> ...
> date
> ...
> User agents are expected to show an appropriate widget,  such as a  
> calendar.

29. Suggestion: Don't give UA implementors bad ideas. :-)
     The most efficient method of entering a date with the
     keyboard is with a datepicker (a multi-part text field
     with increment+decrement buttons), not with a calendar.
     This would also be easier to implement, more consistent
     with the other date/time controls, and more compact
     (reducing scrolling to get to other controls), than a
     calendar would be. Even for a pointing device, the most
     efficient interface (at least for choosing any date not
     in the current month) would involve menus opened from
     each segment of the datepicker (one-dimensional menus
     for year and month, and a two-dimensional menu for day),
     rather than using a calendar.
     *   "calendar" --> "datepicker"

> ...
> number
> ...
>     This format is designed to be compatible with
>     scanf(3)'s  %f format, ECMAScript's parseFloat, and
>     similar parsers while being easier to parse than
>     required by some other floating point syntaxes.

30. Error: Syntaxes cannot require ease.
     *   "than required by some other" --> "than some other"

> range
>     Same as number, but indicates that the exact value is
>     not important,

31. Suggestion: Either make this a separate <scale> element,
     or make its suggested presentation an *addition* to a
     text field rather than a replacement for it.

     I see three general use cases for this control.

     A.  An author provides just a slider, and doesn't mind
         if it degrades to a text field. (Most uses.)

     B.  An author provides a text field and a slider next to
         each other, for ease of input both with a keyboard
         and with a pointing device. (For example,
         colorpickers, size selectors, and image manipulation
         tools.)

     C.  A game developer provides a slider, and does not
         want it to degrade to a text field because that
         would ruin the fun. (For example, she uses scripting
         to create a slider and then to oscillate its
         value, with a button for the player to click when
         the slider is as close to the value he wants as his
         hand-eye coordination will allow.)

     The current syntax only satisfies case A. Case B doesn't
     work because in a non-WF2-supporting browser it will
     degrade to two text fields next to each other, which
     will be incomprehensible. And case C doesn't work
     because cheats can easily make it degrade, by using a UA
     (such as a current release of Opera) that doesn't
     support WF2 but does allow easy UA spoofing.

     If, instead, it was a <scale> container element:
     A.  would work by including an <input type="text">
         inside the <scale> element.
     B.  would work by preceding the <scale> element with an
         <input type="number"> element.
     C.  would work by just using the <scale> element by
         itself (though dedicated cheats could still install
         a browser extension that converted <scale>s to their
         equivalent <input type="number"> fields on demand).

     What's more, a <scale> container element would provide
     better forward compatibility with future versions of Web
     Forms that allow specification of sub-scales, non-
     -numeric extreme values, and the like. A rough
     hypothetical future example:
     |
     | Log me out if I'm idle for:
     | <scale id="expire" valuewithunits="30m" value="30"
     | min="10" max="180">
     |    <subscale min="10" max="50" step="10" suffix="m"
     |    value="minutes" />
     |    <subscale min="1" max="3" suffix="hrs"
     |    suffixsingular="hr" value="hours" />
     |    <extreme label="Never" value="n" />
     |    <!-- degrade for WF1: -->
     |    <input id="expire-wf1" value="30" /> minutes
     | </scale>
     |
     which might appear in a Web-Forms-4-compliant UA as:
     |
     | Log me out if I'm idle for:
     |  ========V===========================
     |  '   '   '   '   '   '    '    '    '
     | 10m 20m 30m 40m 50m 1hr 2hrs 3hrs Never

     These advantages should be measured against the risk
     that authors of type A above will accidentally forget to
     include the backward-compatible markup, and against the
     risk that WF>2 extensions to such <scale> syntax could
     not possibly degrade gracefully in a WF2 client.

     Alternatively, the spec could be changed to state that
     the special range interface (e.g. the slider) should
     always be provided *in addition to* the normal number
     interface (e.g. the field). This would suit cases A and
     B above, abandoning C. (I know the famous Safari RSS
     slider doesn't have or want a text field; but that's
     *part of a browser's own interface*, so I don't see any
     need for it to be a Web Forms control to begin with.)

> letting UAs optimise their UI for usability.

32. Suggestion: Clarify the purpose of the value. Depending
     on the outcome of suggestion 31, either:
     *   "optimize their UI for usability" --> "provide a
         simpler interface than they do for number"
     *   "optimize their UI for usability" --> "add a simpler
         alternative to their interface for number"

> For instance, visual UAs may use a track bar control.

33. Suggestion: Use more standard terminology.
     *   "track bar" --> "slider"

> ...
> email
>     An e-mail address, based on the definitions in
>     [RFC2822] (specifically the addr-spec token, defined
>     in RFC2822 section 3.4.1, excluding the CFWS subtoken
>     everywhere and the FWS subtoken everywhere except in
>     the quoted-string subtoken).

34. Suggestion: Since the bracketed section modifies the
     definition, it probably shouldn't be bracketed.

35. Suggestion: Repeat "excluding" to make it clearer
     whether the CFWS subtoken is allowed in the quoted-
     -string subtoken.

     *   "An e-mail address, following the format of the
         addr-spec token in RFC 2822 [RFC2822] section 3.4.1,
         but excluding the CFWS subtoken everywhere, and
         excluding the FWS subtoken everywhere except in the
         quoted-string subtoken."

> ...
> By default, all of these new types, just like the types from HTML4,  
> must have no value selected, unless a default value is provided using  
> the value attribute.

36. Suggestion: *Please* remove this requirement, at least
     for the date-/time-related controls. I have never seen,
     in any graphical toolkit, a timepicker or datepicker
     control (or even a calendar control) that did not have a
     default value. I would be surprised if it was even
     possible without changing the toolkits' APIs. Even if it
     was possible, their inconsistency with other uses of
     such controls on the user's computer would make them
     look broken. And they would be unreasonably difficult to
     use without the keyboard, as there would be no starting
     values to increment or decrement.

> ...
> 2.1.1. Ranges
> ...
> A field with a max less than its min can never be satisfied and thus  
> would block a form from being submitted.

37. Suggestion: Use RFC 2119 terminology. Either:
     *  "thus would block" --> "must block"
     *  "thus would block" --> "may block"

> This is does not make the document non-conformant.

38. Error: Stray word.
     *   "This is does" --> "This does"

> ...
> 2.1.2. Precision
>
> Another attribute, step, is introduced to control the precision  
> allowed for the date-related, time-related, and  numeric types.

39. Suggestion: Shorten this by making it a specification,
     rather than a description of a specification.
     *   "Another attribute, step, is introduced to control"
         --> "The step attribute controls"

> ...
>> The following control would only allow sundays (starting from 1900)  
>> to be picked:

40. Errors: Capitalization, wrong number, brackets etc.
     *   "sundays (starting from 1900) to be picked" -->
         "selection of a Sunday in any year from 1900"

> ...
> 2.4. Extensions to the  textarea element
>
> The rows and cols attributes of the textarea element are no longer  
> required attributes. When unspecified, CSS-compliant browsers should  
> lay the element out as specified by CSS, and non-CSS UAs may use  
> UA-specific defaults, such as, for visual UAs, using the width of the  
> display device and a height suitable for the device.

41. Error: Since the viewport is almost always smaller than
     the device, this appears to suggest that visual UAs
     default to making a textarea larger than the viewport!
     *   "width of the display device and" --> "width of the
         parent element, and"
     *   "height suitable for the device" --> "height less
         than those of the parent element and the viewport"

> ...
> CSS UAs should render textarea elements as  specified by the  
> 'white-space' property, although UAs may have rules in their UA  
> stylesheet that key the default 'white-space'  property values based  
> on the wrap element for textarea elements.

42. Question: What is meant by "key the ... values"? How
     does a style sheet "key a value"?

> ...
> 2.5. Extensions to file upload  controls
> ...
> They default to 0 and 1 respectively (and so limit the default number  
> of files to 1 optional file, as per most existing implementatios in  
> early 2004).

43. Error: Typo.
     *   "implementatios" --> "implementations"

> (This is done by the file upload controls first checking their  
> attribute, and if they don't have one, checking their  form's. The two  
> attributes don't "stack".)

44. Suggestion: Remove brackets, clarify, and avoid
     anthropomorphizing form controls.
     *   "If a file upload control has a valid accept
         attribute, its value is used and the relevant form
         element's accept attribute is ignored for that
         control."

45. Suggestion: Follow this by specifying robust error-
     -handling for when people stuff up specifying an accept
     attribute.
     *   'If an upload control or a form element has an
         invalid accept attribute, the value is assumed to be
         "*/*". Such an attribute for a file upload control
         still overrides any accept attribute for the
         relevant form element.'
     (Why? Because the faulty value is much more likely to be
     the author's attempt at a non-specialization exception
     to the form's rule, than an attempt at a specialization.

> ...
> 2.7. Extensions to the  submit buttons
> ...
> If a submit button is activated, then the submission uses the values  
> as  given by the button that caused the activation, with missing  
> attributes  having their values taken from the equivalent attributes  
> on the relevant  form element, if any.

46. Suggestion: Split the sentence for readability.
     *   "activation, with missing attributes having their
         values taken" --> "activation. Missing attributes
         take their values"

> ...
> 2.8. Extensions to existing  attributes
> ...
> disabled
> ...
>     When applied to a fieldset element it overrides the
>     disabled attributes of any descendent form controls
>     (regardless of whether they are associated with the
>     same form). In other words, a form control is disabled
>     if it has its disabled attribute set, or if any of its
>     ancestor fieldset elements have their disabled
>     attribute set.

47. Question: If the disabled attribute can be applied to
     <fieldset> elements, why can't it be applied to <form>
     elements too?

> ...
> Servers should still expect to receive, and must be able to cope with,  
> content larger than allowed by the maxlength attribute, in order to  
> deal with malicious or non-conforming clients.

48. Suggestion: "maxlength" should be in <code></code> here.

> This attribute must not affect the initial value (the DOM   
> defaultValue attribute). It must only affect what the user  may enter  
> and whether a validity error is flagged during validation.

49. Question: How should a UA behave if the initial value is
     longer than the maxlength?

> ...
> 2.9. The pattern attribute
>
> For the text, password, email, and uri types of the input  element,  
> and the textarea element, a new attribute, pattern, is introduced to  
> specify patterns that the strings must match.

50. Suggestion: Clarify the purpose of the attribute by
     making it a specification, rather than a description of
     a specification.
     *   "a new attribute, pattern, is introduced to specify
         patterns that the strings must match." --> "the
         pattern attribute imposes further restrictions on
         the data that can be accepted in those controls."

51. Suggestion: Add best behavior for UAs in minimizing
     errors.
     *   "In addition to preventing submission of a form
         containing a field that does not match its pattern,
         a UA should:
         -   ignore entry of a character that is not allowed
             anywhere in the field's value
         -   instantly convert Latin characters to upper case
             or lower case if only one case is permitted
             throughout the field's value."
     (If necessary, use "may" instead of "should".)

> ...
>> For example, the following snippet:
>>     <label> Part number:
>>      <input pattern="[0-9][A-Z]{3}" name="part"
>>             title="The expected format is: a digit
>>             followed by three uppercase letters."/>
>>     </label>
>>
>> ...could cause the UA to display an alert such as:
>>
>>     The text you have entered does not match the required
>>     pattern.
>>
>>     The expected format is: a digit followed by three
>>     uppercase letters.

52. Suggestion: Give authors (and UA implementors) an
     example that provides a much more pleasant experience.
     (My footnotes below are not part of the suggested
     replacement text.)
     *   'If focus is moved away from a control in which the
         user has entered an invalid value[1], or if form
         submission is attempted while the field is invalid,
         a visual UA may highlight the field in some way.[2]
         And if, for example, a text field has the code

             <label>Part number:
               <input pattern="[0-9][A-Z]{3}" name="part"
                      title="A part number must be one digit
                      followed by three uppercase letters."/>
             </label>

         and form submission is attempted[2] when this field
         is the first invalid field in the form[3], a visual
         UA may focus the field, and display a help balloon
         pointing at it[4] containing the text:

             <strong>A part number must be one digit followed
             by three uppercase letters.</strong>[5]

             You cannot complete this form until the field is
             correct.[6]'

     [1] Why not "that contains an invalid value"? Because if
         the default value (such as "") is invalid, we don't
         want the form to turn into a sea of pink borders
         just from being tabbed through.
     [2] Why not display the error as soon as focus leaves
         the field? Because I may be temporarily focusing
         somewhere else to copy (or refer to) text to put in
         the field.
     [3] Why just for the first invalid field? To prevent a
         festival of simultaneous or consecutive balloons
         from multiple invalid fields.
     [4] Why a balloon instead of an alert? Firstly, people
         don't read alerts. Secondly, it makes the identity
         of the field more obvious. And thirdly, it removes
         the need to dismiss anything -- you can edit the
         field with the balloon still present, and the
         balloon fades away as soon as you do something else.
     [5] Why put the author's message first? Because it's
         almost certainly more useful than the generic
         message.
     [6] Why not mention "pattern" in the generic message?
         Firstly because Grandma thinks a "pattern" is about
         knitting, not regexps. And secondly because the
         author might have stuffed up and omitted their
         message, and referring to a "pattern" without saying
         what it was would be needlessly aggravating.

> ...
> 2.10. The required attribute
> ...
> For check boxes, the required  attribute shall only be satisfied when  
> the checkbox is checked.
>
> For radio buttons, the required attribute shall only be satisfied when  
> exactly one of the radio buttons in that radio group is checked.

53. Suggestion: Use the present tense.
     *   "shall only be satisfied" --> "is satisfied only"

> ...
> 2.11. The form attribute
> ...
>> In this example, each row contains one form, even though without this  
>> attribute it would not be possible to have more than one form per  
>> table if any of them span cells.

54. Suggestion: Split the sentence for readability.
     *   "one form, even though without this attribute" -->
         "a form. Without the _form_ attribute"

55. Error: Mismatched tense. Either:
     *   "it would not be" --> "it is not"
     *   "them span" --> "the forms spanned"

> ...
> 2.12. The autocomplete attribute
> ...
> A UA may allow the user to disable support for this attribute. Support  
> for the attribute must be enabled by default, and the ability to  
> disable support should not be trivially accessible, as there are  
> significant security implications for the user if support for this  
> attribute is  disabled.

56. Suggestion: Clarify the connections between the
     sentences.
     *   "attribute. Support" --> "attribute. But support"
     *   "this attribute is" --> "the attribute is"

>> Banks frequently do not want UAs to pre-fill login information:

57. Error: Match the spelling used elsewhere in the spec.
     *   "pre-fill" --> "prefill"

> 2.13.  The autofocus attribute
> ...
> UAs may ignore this attribute if the user has indicated (for example,  
> by starting to type in a form control) that he does not wish focus to  
> be changed.

58. Suggestion: Insist on this, as it is a security
     vulnerability. (Several times I have accidentally typed
     a password into a username field because the browser had
     returned focus to it just after I had focused the
     password field.)
     *   "may" --> "must"

> ...
> Authors should only mark one (non-disabled) control per document with  
> the autofocus attribute.

59. Suggestion: Start this sentence with "However," and move
     it to the end of the paragraph describing what happens
     if multiple controls have the attribute set.

>> In the following snippet, the text field would be focussed when the  
>> document was loaded.

60. Error: Spelling. "Focused" and "focusing" are used in
     some parts of this spec, and "focussed" and "focussing"
     in others. Pick one style and stick to it.

> ...
> 2.15.  The help  attribute
>
> Any form control can have a help attribute specified.

61. Suggestion: Use RFC 2119 terminology.
     *   "can" --> "may"

> ...
> This specification does not specify how help information should be  
> used, but for example, the UA could show a small pop-up window if the  
> user focuses such a control and pressed the F1 key, or could show the  
> help information in a side-bar while the relevant control is focused.

62. Suggestion: Make the suggestion more platform-agnostic.
     On my old computer, F1 launched Internet Explorer. On my
     new computer, F1 decreases the display brightness ...
     *   "F1 key" --> "device's standard Help key"

> ...
> 2.16. Handling unexpected  elements and values
> ...
> Upon encountering such an invalid construct, UAs must proceed as  
> follows:

63. Suggestion: Maybe I'm just getting old-fashioned, but I
     remember not so long ago "construct" wasn't a noun.
     *   "an invalid construct" --> "invalid nesting"

> For parsing errors in HTML
> ...
> For non-empty form elements in head elements in XHTML
> ...
> For non-empty input elements
> ...
> For output elements containing  elements in the DOM
> ...
> For textarea elements containing tags in HTML
> ...
> For textarea elements containing elements in the DOM
> ...
> For select elements containing nodes other than  option and optgroup  
> elements, and for  optgroup elements containing nodes other than   
> option elements
> ...
> For option elements containing nodes other than text  nodes
> ...
> For option and optgroup elements that are  not inside select elements
> ...
> For attributes that contain invalid values
> ...
> For value attributes that are invalid according to the  type attribute
> ...
> For value attributes that are invalid according to the  min, max,   
> step, etc, attributes
> ...
> For labels pointing (via for) to elements that  are not form controls
> ...
> For labels with no for) attributes and  containing more than one form  
> control

64. Suggestion: Remove all instances of the word "for" in
     these headings.

> For non-empty input elements
>     By default, the form control must replace the contents
>     of the element in the rendering with the form control
>     widget.

65. Suggestion: Shorten and clarify.
     *   "By default, the form control must be rendered and
         the contents of the element must not be."

> For output elements containing  elements in the DOM
> ...
>     While the element contains elements, they are rendered
>     according to the CSS rules.
> ...
> For textarea elements containing elements in the DOM
> ...
>     The rendering is based on the value DOM attribute, not
>     the contents of the element, unless CSS is used to
>     override this somehow.
> ...
> For option elements containing nodes other than text  nodes
> ...
>     Two possibilities are sensible: rendering the content
>     normally, just as it would have been outside the form
>     control; and rendering the initial value only, with
>     the rest of the content not displayed (unless forced
>     to appear through some CSS).

66. Error: This specification does not appear to include by
     reference any CSS specification as a whole (though it
     does mention CSS3 Generated Content and UI properties).
     Either that should be done, or these statements should
     be generalized in case the document is styled using a
     language other than CSS.

> ...
> For option elements containing nodes other than text  nodes
> ...
>     As far as rendering goes, it is left largely up to the
>     UA.

67. Suggestion: Shorten.
     *   "How such markup should be rendered is undefined."

>> Note: It should be noted that while nesting a form inside a select  
>> control may look cool, it is extremely poor UI and must not be  
>> encouraged.

68. Suggestion: Remove redundant redundancy.
     *   "It should be noted that while" --> "While"

> For option and optgroup elements that are  not inside select elements
>     The elements should be treated much like span elements
>     as far as rendering goes.

69. Suggestion: Remove redundancy.
     *   "as far as rendering goes" --> ""

> For attributes that contain invalid values
>     The attribute must be ignored.

70. Suggestion: If suggestion 45 above is accepted, note the
     exception here.

> For labels with no for) attributes and containing more than one form  
> control

71. Error: Stray bracket.

> ...
> 3.1. Introduction for  authors
> ...
> To explain this, we will step through an example. Here is a sample  
> form with three rows:

72. Question: Why does the example contain no <form></form>
     tags?

> ...
>> <p><button type="add" template="order">Add Row</button></p>

73. Suggestion: Encourage more standard text for such
     buttons.
     *   "Add Row" --> "+" throughout the spec (or at least
         everywhere except section 3.1.1, where more specific
         text may be educative)

> ...
>> <button type="remove">Remove This Row</button>

74. Suggestion: Encourage more standard text for such
     buttons.
     *   "Remove Row" --> "–" throughout the spec (or
         at least everywhere except section 3.1.1, where more
         specific text may be educative)

> ...
> 3.1.2 Suggestions for authors
> ...
> In order to be considered a part of the repetition model, however, the  
> row  must have a repeat attribute with a numeric value. That value   
> can be any integer. (For example, you could use "-1" as the value of  
> all prefilled rows.)

75. Error: Bad markup.
     *   "repeat<code>" --> "repeat</code>"
     *   "</code></code>" --> ""

> ...
> 3.2. Definitions
> ...
> In order to implement such a form declaratively, several new global  
> attributes are introduced: repeat, repeat-start, repeat-min,  
> repeat-max, and repeat-template. When placed on elements in the  
> http://www.w3.org/1999/xhtml namespace, they must be namespace-free  
> attributes, and when placed on other elements, they must be attributes  
> in the http://www.w3.org/1999/xhtml namespace.

76. Error: Bad markup.
     *   "<?code>" --> "</code>"
     *   "namespace.</code>" --> "namespace."

> 3.2.2. Repetition blocks
> ...
> There can take part in the deletion and movement aspects of the  
> repetition model, but not addition..

77. Error: Wrong word.
     *   "There" --> "They"

78. Error: Typo.
     *   ".." --> "."

> ...
> 3.6. The repetition  model
> ...
> However, see the section on seeding a form with initial values for  
> details on how repetition blocks can be pre-filled.

79. Suggestion: Make "the section on seeding a form" a
     hyperlink.

> ...
> 3.6.1. Addition
> ...
> 9.  If the template has a name (see the previous step),
>     then, for every attribute on the new element, and for
>     every attribute in every descendant of the new
>     element: if the attribute starts with a zero-width
>     non-breaking space character (U+FEFF) then that
>     character is removed from the attribute; otherwise,
>     any occurrences of a string consisting of an open
>     square bracket (U+005B, "["), the template's name, and
>     a closing square bracket (U+005D, "]"), is replaced by
>     the new repetition block's index.

80. Error: Mismatched number. Either:
     *   "occurrences" --> "occurrence"
     *   "is replaced" --> "are replaced"

> ...
>     For example, if the template is called order, and the
>     new repetition block's index has the value 2, and one
>     of the attributes of one of the descendents of the new
>     repetition block is marked up as
>     name="order.[order].comment.[comment[order]]", then
>     the attribute's value is changed to
>     order.2.comment.[comment2].

81. Error: Match the spelling used elsewhere in the spec.
     *   "descendents" --> "descendants"

> ...
> 3.7.1. Repeated rows
> ...
> If the "Delete Row" button above is pressed, the row would be removed.

82. Error: Mismatched tense.
     *   "would be" --> "is"

> ...
> 4. The forms event model
> ...
> Some of the above are mainly described in [DOM3EVENTS] and [HTML4].

83. Error: Mismatched number. Either:
     *   "Some of the above" --> "These events"
     *   "the above are mainly" --> "these events are"

> ...
> 4.4 Form validation
> ...
> The default action is UA-specific, but is expected to consist of   
> focusing the element (possibly firing focus events if appropriate),  
> alerting the user (ideally using a non-modal mechanism) that the  
> entered value is unacceptable in the user's native language along with  
> explanatory text saying why the value is currently invalid.

84. Error: Incomplete list.
     ", alerting" --> ", and alerting"

> ...
>> form.error.value = 'That is not an integer.';
>>     else if (event.target.validity &  
>> event.target.form.ERROR_STEP_MISMATCH)
>>       form.error.value = 'That is not an integer.';
>>     else if (event.target.validity &  
>> event.target.form.ERROR_RANGE_UNDERFLOW)
>>       form.error.value = 'That integer is less than 0.';
>>     else if (event.target.validity &  
>> event.target.form.ERROR_RANGE_OVERFLOW)
>>       form.error.value = 'That integer is more than 255.';
>>     else if (event.target.validity & event.target.form.ERROR_REQUIRED)
>>       form.error.value = 'You did not enter a value.';

85. Suggestion: Encourage more positive error messages.
     *   "  form.error.value = 'You must enter a number.';
         else if (event.target.validity &
         event.target.form.ERROR_STEP_MISMATCH)
           form.error.value = 'Fractional numbers are not
           allowed.';
         else if (event.target.validity &
         event.target.form.ERROR_RANGE_UNDERFLOW)
           form.error.value = 'The number must be 0 or
           greater.';
         else if (event.target.validity &
         event.target.form.ERROR_RANGE_OVERFLOW)
           form.error.value = 'The number must be 255 or
           less.';
         else if (event.target.validity &
         event.target.form.ERROR_REQUIRED)
           form.error.value = 'You must enter a number.';

> ...
> 5. Form submission
> ...
> 1.  Step one: Dispatch the submit event.
> ...
> 2.  Step two: Check the validity of the form
> ...
> 3.  Step three: Identify all form controls
> ...
> 4.  Step four: Build a form data set
> ...
> 5.  Step five: Encode the form data set
> ...
> 6.  Step six: Submit the encoded form data set
> ...
> 7.  Step seven: Dispatch the received event.
> ...
> 8.  Step eight: Handle the returned  data

86. Suggestion: Remove the redundant "Step xxx"s. We already
     know they're steps, and we already know what number each
     of them is.

> ...
> 2.  Step two: Check the validity of the form
>
>     If the form submission was initiated as a result of a
>     submit event's default action, then the form is
>     checked for validity. If, after the form has had any
>     relevant invalid events fired, any controls remain
>     invalid, then the submission shall be aborted.
>
>     Otherwise, if the form submission was initiated via
>     the submit() method, then instead of firing invalid
>     events, a SYNTAX_ERR exception shall be raised (and
>     submission is aborted) if any of the controls are
>     invalid. [DOM3CORE]

87. Error: Mismatched tense.
     *   "shall be aborted" --> "is aborted"
     *   "shall be raised" --> "is raised"

>     Script authors who wish to validate the form then
>     perform submission can use script such as:

88. Suggestion: Clarify.
     *   "then perform" --> "before performing"

89. Error: Missing word.
     *   "use script" --> "use a script"

> ...
> 3.  Step three: Identify all form controls
>
>     All the controls that apply to the form, whether
>     successful or not, should be taken, in document order.

90. Question: Taken where?
     *   "taken, in" --> "identified in"

> ...
> 5.  Step five: Encode the form data set
>
>     The form data set is then encoded according to the
>     content type specified by the method and enctype
>     attribute of the element that caused the form to be
>     submitted.

91. Error: Mismatched number.
     *   "attribute" --> "attributes"

> ...
> 6.  Step six: Submit the encoded form data set
>
> Finally, the encoded data is sent to the processing agent designated  
> by the action attribute of the element that initiated the submission  
> using the protocol method specified by the  method attribute of that  
> same element.

92. Error: Step 6 is not the final step.
     "Finally, the" --> "The"

93. Suggestion: Clarify with a comma.
     "submission using" --> "submission, using"

> 7.  Step seven: Dispatch the received event.
> ...
> If it is canceled, then the submission processing stops at this point.  
> If it is not cancelled, then its default action is to perform the rest  
> of the submission procedure (step eight).

94. Error: Spelling. Choose either "cancelled" and
     "cancelling", or "canceled" and "canceling", and stick
     to it.

> ...
> 5.2. Handling characters outside the submission character set
> ...
> If the form data set contains characters that are outside the  
> submission character set, the user agent should inform the user that  
> his submission  will be changed;

95. Question: Should the UA do that even if the only such
     characters came from <input type="hidden"> controls? If
     so, for what purpose?

> ...
> 5.3.  application/x-www-form-urlencoded
> ...
>     Character encodings that are not mostly supersets of
>     US-ASCII must not be used (this includes UTF-16 and
>     EBCDIC) even if specified in accept-charset attribute.

96. Error: Missing article.
     *   "in accept-charset" --> "in the accept-charset"

>     How a UA establishes the page's character encoding is
>     determined by the language specification. It could be
>     explicitly specified by the page, overriden by the
>     user, or auto-detected by the UA. For example, HTML4
>     section 5.2.2 [HTML4].

97. Errors: Fragment and spelling.
     *   "How a UA establishes the page's character encoding
         is determined by the language specification (for
         example, HTML4 section 5.2.2 [HTML4]). It could be
         explicitly specified by the page, overridden by the
         user, or auto-detected by the UA."
     *   The same for section 5.5 step 1.

> ...
> 4.  Control names and values are escaped. Space characters
>     are replaced by `+', and then non-alphanumeric
>     characters are encoded in the submission character
>     encoding and each resulting byte is replaced by `%HH',
>     a percent sign and two uppercase hexadecimal digits
>     representing the value  of the byte.
>
> 5.  The control names/values are listed in the order they
>     appear in the  form data set. The name is separated
>     from the value by `=' and name/value pairs are
>     separated from each other by `&'.

98. Suggestion: Use consistent quotes throughout the spec.
     *   "`" --> '"'
     *   "'" --> '"'
     *   the same for section 5.5 step 4
     *   the same for section 6.1 example

> ...
> 5.6.  Submitting  the encoded form data set
> ...
> If the form contains more something other than just one file upload  
> control with exactly one file selected, or if the attribute is  
> specified but has an unrecognised value, the enctype attribute is  
> treated as if it was application/x-www-form-urlencoded.

99. Error: Stray word.
     "more something other" --> "something other"

> ...
> 5.6.4. For file: actions
> ...
> The semantics described in this subsection are recommended, but UAs  
> may implement alternative semantics as consistent behaviour for  
> submission to file: URIs is not required for interoperability on the  
> World Wide Web.

100.Suggestion: Clarify.
     *   "semantics as" --> "semantics if desired, as"

> ...
> 6.2 Seeding a form with initial values
> ...
> However, output control can be populated.

101.Error: Missing article.
     *   "However, output" --> "However, an output"

> ...
> 7.1. Additions specific to  the HTMLFormElement interface
> ...
> The elements array must contain all the input, output, select,  
> textarea and button controls without a form attribute that have the  
> form as an ancestor, except if one of the ancestors between the  
> control and the form is a repetition template or another form, and,  
> all the input, output, select, textarea and button controls that have  
> a  form attribute that points to the form, except if the control  has  
> an ancestor that is a repetition template that is not also an ancestor  
>  of the form.

102.Error: "And" followed by comma but comma not followed by
     parenthetical subclause.
     *   "form, and, all" --> "form; and all"

> ...
> The form.validate() method shall make a list of all the elements in  
> the form's elements list whose interfaces have a validate() method  
> defined and a successful attribute defined, and whose successful  
> attribute has the true  value, then shall invoke the validate() method  
> on all the elements in that list. It shall return the logical-and of  
> all the return values (i.e. it  returns false if any of the form  
> controls are successful but invalid). See the section on form  
> validation for details regarding the resulting events.

103.Suggestion: Match the tense of the rest of the spec. As
     appropriate:
     *   "shall" --> "must"
     *   "shall make" --> "makes"
     *   "shall return" --> "returns"

> ...
> For all other element it must return false.

104.Error: Mismatched number.
     "element" --> "elements"

> ...
> 7.6. New DOM attributes for new  content attributes
> ...
> The form attribute on most of the control interfaces is  read-only,  
> but reflects the curret state of the form content attribute.

105.Error: Typo.
     "curret" --> "current"

> ...
> 7.10. Loading remote documents
> ...
> action
>     The URI to lead.

106.Error: Typo.
     "lead" --> "load"

> ...
> A. XHTML module definition
> ...
> input
> ...
>     value (CDATA),

107.Error: Stray comma.

> ...
> fieldset
>     Common,  disabled ("disabled"), form (IDREF), help
>     (URI),

108.Error: Stray comma.

> ...
> The code>repeat attributes must either have the  value "template" or  
> be an integer (an  optional '-' character followed by one or more  
> decimal digits).

109.Error: Typo.
     *   "code>" --> "<code>"

-- 
Matthew Thomas
http://mpt.net.nz/




More information about the whatwg mailing list