[whatwg] Web Forms 2.0 Editorial [minor] Abstract -> Section 2

[Ian Hickson]

On Fri, 11 Jun 2004, fantasai wrote:
>
>    This specification defines Web Forms 2.0, an extension >of< the forms features

Extensions are made to things, not of things.

>    >defined< in HTML 4.01's

Many of the features are not defined in HTML4 but in other drafts
referred to by that spec.

>    >F<orms chapter.

Fixed.

>    Web Forms 2.0 >extends< both HTML and XHTML

That changes the meaning quite drastically. The point of the sentence is
that it applies to both HTML and XHTML UAs, not that it extends any spec,
something which is covered earlier.

>    >providing< new strongly-typed input fields,

"providing" doesn't read as well with the rest of this list.

>    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. This specification
>    also standardises and codifies existing practice in areas that have not been
>    previously documented. <> Web Forms 2.0 thus extends HTML4, XHTML1.1>,< and

I think you omitted some change marks here, but apart from the comma I
don't really see the advantage of the change.

>    the DOM in a manner >that< has a clear migration path from existing HTML

Oops.

>    forms, leveraging the knowledge authors have built up >in< their experience
>    with HTML so far.

You build something with experience, not in experience.

> # This document is the result of a loose collaboration between interested
> # parties in the context of the Web hypertext application technology working
> # group.                            ^         ^           ^          ^
>    ^
> Capitalize.

Fixed.


> 1. Introduction
> ---------------
>
> # This is an update to the forms features found in HTML 4.01's forms chapter
>
>    >Web Forms 2.0< is an update to the forms features found in HTML 4.01's

The omission of the spec's name from most of the spec is intentional and
is intended to make changing the name of the spec, as well as copy and
pasting prose from the spec, significantly easier.

>    >F<orms chapter

Fixed.

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

Fixed.

> # Basic data typing, providing new controls for commonly used types, so that
> # authors do not need
>
>    Basic data typing, providing new controls for commonly used types<> so that
>    authors do not need

Fixed.

> # 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.
>
>    Simple<> validation on the client side (while recognizing that server side

A spec should never claim to be simple. It's bad form, IMHO. It also
leaves you open to being criticised for not succeeding at one of your
requirements, whereas if you say you want to be _simpler_, it's much
easier to check if you succeeded.

>    validation will still be required), with declarative solutions for the common
>    case>s and< strong DOM support so that less common cases can easily be handled

I don't see how that helps. The "but" is pivotal in that sentence.

>    >by< scripting.

Scripting doesn't magically solve things, you have to use it to solve
things.

> # The ability to initialize forms from external data sources, so that authors do
> # not have to dynamically rewrite the form content itself to prefill forms, but
> # can instead use static pages with scripts that dynamically generate only the
> # data part.
>
>    Initialization from external data sources, so that authors do not have to
>    dynamically rewrite the form content itself to prefill forms<> but can instead

Why?

>    use static pages with scripts that dynamically generate only >a data block<.

Eh? It's "the data part" as opposed to "the form part", what's a data
block?

> 1.3 Relationship to XForms
> --------------------------
>
> # due to its dependencies on technologies not widely supported by Web browsers,
> # it has not been widely implemented by those browsers itself.
>
>    due to its dependencies on technologies not widely supported by Web browsers,
>    it has not been widely implemented by >them<.

The "them" is introduced in a subclause and is therefore not in scope of
the final part of the sentence. At least that's what it feels like when I
read that.

> # The majority of the features that XForms supports using declarative syntax
> # are, in this specification, handled by using scripting.
>
>    The majority of the features that XForms supports using declarative syntax
>    are, in this specification, handled by <> scripting.

See above. They aren't handled by script. They are handled by _using_ the
script.

> 1.5 Missing Features
> --------------------
>
> # Again, however, this need may addressed in a future version of this
> # specification.
>
>    <> >T<his need may addressed in a future version of this specification.

What's wrong with "Again, however"?

> 1.6 Conformance Requirements
> ----------------------------
>
> # All other content in this specification is intended to be normative.
>
>    All other content in this specification is <> normative.

Some might debate that change but yeah, fair enough.

> # Compliant UAs must implement all the semantics of those specifications
> # to claim compliance to this one.
>
>    Compliant UAs must implement all the >requirements< of those specifications
>    to claim compliance to this one.

Fixed.

> # Other aspects of this specification that are defined in terms of an events
> # model
>
>    Other >features in< this specification that are defined in terms of an
>    events model

That paragraph was written by careful coordination with someone who wanted
it in there so I'm not going to touch it.

> # there may be implementation specific limits
>
>    there may be implementation>-<specific limits

Fixed.

> 1.7 Terminology
> ---------------
>
> # Generally, when the specification states that a feature applies to HTML or
> # XHTML, it also includes the other. When a feature specifically only applies
> # to one of the two languages, it is called out explicitly, as in:
>
>   Generally, when the specification states that a feature applies to HTML>, it
>   also includes XHTML and vice versa<. When a feature specifically only applies
>   to one of the two languages, it is called out explicitly, as in:

That doesn't seem as easy to read, to me.

> #   ...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).
>
> This example makes no sense in this context. Find another one.

I don't understand why it makes no sense. The semantic of the sentence is
not what matters, it's the phrasing. That it makes no sense might even be
a positive thing.

What would you suggest instead?

> 2. Extensions to form control elements
> --------------------------------------
>
> # Also, as controls no longer need to be contained within their form element to
> # be associated with it, 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). This is therefore allowed, although only
> # when the form element is empty.
>
>    Also, as controls no longer need to be contained >by< form element to be

I don't see how that is better.

>    associated with it, it is possible <> to declare the page's forms in

That loses the reasoning of the paragraph, without which I would just
remove the entire thing.

>    advance<>. >The <form> element is therefore allowed in the <head> element of
>    XHTML documents<, although only when the form element is empty. >(This does
>    not apply to HTML.)<

That doesn't seem as friendly as the original text.

> # Forms are not related to ancestor forms in any way semantically,
>
>    Forms are not >semantically< related to ancestor forms in any way<>,

Fixed.

> 2.1 Extensions to the input element
> -----------------------------------
>
> # UAs must not submit numbers in invalid formats (whatever the user might
> # enter).
>
> Delete this. It's covered by the type-checking requirements, same as with
> all the other types.

No, it isn't. Assuming the number passes all the type checking, the UA
could still decide to send a number in an invalid format, such as +0.

> # Although if they are required fields, they will stop submission
>
>    Although if they are required fields, they will >block< submission

Stop seems more accurate given the model in question.

> 2.1.1 Ranges
> ------------
>
> > To limit the range of values allowed by the above types, two new attributes
> > are introduced, which apply to the date-related, time-related, numeric, and
> > file upload types:
>     ...
> > For date, time and numeric fields, the values indicate the allowed range. For
> >  file upload fields, the values indicate the allowed number of files.
>
>
>    To limit the range of values allowed by the above types, two new attributes
>    are introduced<>:
>     ...
>    For date, time and numeric fields, the values indicate the allowed range. For
>    file upload fields, the values indicate the allowed number of files. >For all
>    other types, the attributes must be ignored.<

I prefer saying up front what the attribute applies to. Many people ask me
"what does it apply to" when I omit a clear statement at the top.

> # If a UA needs to round a number to its nearest binary equivalent, for example
> # when converting a user-supplied decimal
>
>    If a UA needs to round a number to its nearest binary equivalent, >as, <for
>    example>,< when converting a user-supplied decimal

I don't see how this helps.

> 2.2 The output element
> ----------------------
>
> # The output element acts very much like a span element, except that
> # it is considered to be a form control
>
>    The output element acts very much like a span element<> except that
>    it is considered to be a form control

Don't see how that helps. I find the comma adds a pause to the sentence
that makes the reader reflect (minutely) on the previous part of the
sentence before jumping into the detail.

> # It has no attributes beyond the common attributes
>                                    ^^^^^^^^^^^^^^^^^
> Link to http://www.w3.org/TR/html40/sgml/dtd.html#attrs

Fixed.

> # This is similar to the way textarea elements work, except that the
> # contents of an element for output controls reflects the current value
> # not the initial, or default, value.
>
>    This is similar to the way textarea elements work, except that the
>    contents of an >output element< reflects the current value>,< not the
>    initial<> value >(defaultValue)<.

Changed, although not to exactly what you suggest.

> # Its value can be set dynamically via the value DOM attribute,
> # thus replacing the contents of the element.
>
>    Its value can be set dynamically via the value DOM attribute,
>    >whose value then replaces< the contents of the element.

Changed, although not to exactly what you suggest.

> 2.3 Extensions to the select element
> ------------------------------------
>
> # Previous versions of Web Forms were inconsistent about whether the initial
> # option element of a single-select select
>
>    Previous versions of Web Forms were inconsistent about whether the >first<
>    option element of a single-select select

Fixed.

> # User agents implementing this specification must select the initial option
> # element of a single-select select element with no otherwise-selected items.
>
>    If no other options are selected, user agents implementing this spec must
>    select the first option element of a single-select element.

I don't understand why that would be better.

> 2.7 Extensions to the submit buttons
> ------------------------------------
>
> # 2.7 Extensions to the submit buttons
>
>    2.7 Extensions to <> submit buttons

That sounds like they are extensions that ubbmit buttons.

> # For this reason, the following attributes are allowed on submit buttons:
> # action, method, enctype, replace, and target. **When not specified, their
> # values default to the values given by their form element.**
> #
> # 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 form.**
>
> Highlighted phrases should be reduced to just one. (Also, the remaining phrase
> should be clear as to whether getting the attribute value from the DOM would do
> a lookup on the form element or not.)

Fixed.

> 2.8 Extensions to existing attributes
> -------------------------------------
>
> # When applied to a fieldset element it overrides the disabled attributes of
> # any descendent form controls
>
>    When applied to a fieldset element it >disables all< descendent form controls

Not clear enough. Does it thus change their attribute? At least with
"override" that is more clear (in context, at least).

> 2.9 The pattern attribute
> -------------------------
>
> # In the case of the email, tel, and uri, the pattern attribute specifies
>
>    In the case of the email, tel, and uri >types<, the pattern attribute
>    specifies

Fixed.

> # When the value doesn't match the field's type, a ERROR_TYPE_MISMATCH error
> # occurs; when the value doesn't match the pattern, a ERROR_PATTERN_MISMATCH
> # error occurs.
>
>    When the value doesn't match the field's type, >an< ERROR_TYPE_MISMATCH error
>    occurs; when the value doesn't match the pattern, >an< ERROR_PATTERN_MISMATCH
>    error occurs.

Fixed.

> # Additional information could also be included, so long as it assists the user
> # in entering the field. Otherwise, assistive technology would be impaired.
>
>    Additional information could also be included, >so< long as it assists the

?

>    user in entering the field. Otherwise<> assistive technology would be
>    impaired.

Not sure how this improves readability.

> # For instance, if the title attribute contained the caption of the control,
> # assistive technology could end up saying something like The text you have
> # entered does not match the required pattern. Birthday which is not useful.
>
> Insert an em dash before "which is not useful", and please make the <samp>
> display: block.

Used a comma.

> 2.11 The form attribute
> -----------------------
>
> # Setting an element's form attribute either to a non-existent ID, to the empty
> # string, or to an ID that identifies an element that is not an HTML form
> # element, disassociates the form control from its form, leaving it unassociated
> # with any form.
>
>    Setting an element's form attribute either to >an ID that does not identify an
>    HTML form element or to the empty string< disassociates the form control from
>    its form, leaving it unassociated with any form.

That seems vaguer.

> # unless they have form attributes of their own, or are contained inside forms
>
>    unless they have form attributes of their own<> or are contained inside forms

Not sure I agree but fixed anyway.

> # When forms are submitted, reset, or have their form controls enumerated
>
>    When forms are submitted, >are< reset, or have their form controls enumerated

Fixed.

> 2.16 Handling unexpected elements and values
> --------------------------------------------
>
> # The value of the control, if not specified explicitly, is initialized using
>
> I suspect that you can be a bit more precise than saying "the value of the
> control". I'm not sure though. It just kinda stood out...

Not sure what else you would call it.

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