Comments on XForms

Attached are some comments on the 18 January 2002 XForms draft.  Sorry
they are so late.
-- 
Shane P. McCarron				Inet: shane@aptest.com
Managing Director				Phone: +1 763 786-8160 x120

This document contains my comments on the XForms 1.0 draft from 18
January 2002.  This review is NOT a complete testability analysis, but
does contain comments that are relevant to the testability of any
implementation of this specification.  It also contains editorial
comments, usability comments, and technical comments.  Since there is
no formal commenting structure or content mechanism, I have tried to
present my comments sensibly. 

Note that each comment is separated by a line containing only '-----'.
This SHOULD make it easy to separate the comments.

-----

Section: All

Paragraph: All

Type: technical

Priority: high

Problem:

This specification uses "camel-case" for attibute names.  While I
personally prefer that, the HTML Working Group has elected to avoid
using this convention because of the difficulty it causes users.

Recommended Solution:

Change the attribute names to all lower-case.

-----

Section: All

Paragraph: All

Type: technical

Priority: high

Problem:

Throughout the document there are some normative, "assertive" terms
used.  Some of these are defined by reference to RFC 2119.  Others are
not defined, and they need to be.

Recommended Solution:

Add definitions for "undefined", "unspecified", and "implementation
defined".  The latter is not used in this specification yet, but it
should be in a few cases (see my later comments). [Yes, I will assist
with defining these terms.]

-----
Section: All

Type: Editorial

Priority: High

Problem:

Internal references in this document are usually links, and they
usually have a section number and name attached to them.  Likely this
was to facilitate reading a printed version and following the
references.  The problem with this is that, since the printed version
does not have proper page headers and footers that show section
identifiers, it is actually very hard to follow the references.

Recommended Solution:

Remove the explicit section numbers and names (unless they are the
actual link).  Rely upon the tool html2ps to generate a postscript and
pdf version of the specification suitable for printing. [Yes, I
volunteer to assist with this effort.

-----

Section: All

Paragraph: All

Type: Editorial

Priority: Low

Problem:

In many cases where an enumerated list is presented in prose, it takes
the form "item1, item2, item3 and item4."  This is more properly
presented as "item1, item2, item3, and item4."

Recommended Solution:

Fix the prose lists so they are consistent.

-----

Section: All

Paragraph: All

Type: Technical

Priority: High

Problem:

When elements, their content models, and their attribute lists are
presented formally, this document uses a syntax defined in section
1.4.  That syntax may be something that is used in other
specifications, but the HTML Working group has adopted a different
format.  For consistency with the XHTML specifications, this document
should adopt those conventions.

Recommended Solution:

Convert the XML syntax representations of the elements to the
abstract module notation as defined in XHTML Modularization 1.0. [Yes,
I volunteer to assist with this.]

-----

Section: All

Paragraph: All

Type: technical

Priority: high

Problem:

This specification relies upon XLink.  I thought that the HTML working
group determined that we didn't like XLink.  If Xlink functionality is
sufficient for this specification, I guess that is okay.  But it is
inconsistent.

Recommended Solution:

I would prefer that this specification rely upon the same mechanism as
that of XHTML 2.0 for expressing linkimg semantics.

-----

Section: all

Paragraph: all

Type: technical

Priority: high

Problem: 

The spec does not indicate which attributes are required. 

Recommended Solution:

Ensure that in each element definition, any required attributes are clearly
defined.

-----

Section: Abstract

Paragraph: 1

Type:  Editorial

Priority: Low

Problem:

The term "Forms for the Web" seems a little colloquial or something.
If it was a long-consdered pithy marking phrase or something, great.
If not, we sort of need one.  Something like "XForms - it's not your
father's <form> element". :-)

Recommended Solution:

I don't really have one, but good marketing is as important as a good
specification - probably more important.  Someone should think about
this.


-----

Section: 2.1

Paragraph: External schema augmentation

Type: Editorial

Priority: low

Problem:

The first sentence is missing a word.

Recommended Solution:

Change "This enables the XForms author go beyond..." to "This enables
the XForms author to go beyond..."

-----

Section: Section 2.2

Paragraph: last

Type: editorial

Priority: low

Problem:

The last sentence is kind of awkward.  I would rephrase it as

Recommended Solution:

"In contrast, XForms greatly improves the expressive capabilities of
electronic forms."

-----

Section: 2.3

Paragraph: first PRE block

Type: editorial/technical

Priority: medium

Problem:

The URL uses examples.com.  This should be example.com

Recommended Solution:

Change "examples.com" to "example.com".

-----

Section: 2.5

Paragraph: 1

Type: editorial

Priority: medium

Problem:

This paragraph is awkward.

Recommended Solution:

Rephrase as "XForms allows data to be checked for validity on the
client. In classic HTML forms, constraints like the following could
only be enforced through the addition of sophisticated scripts:"  Or
something like that, if that is what you were trying to say.

-----

Section: 2.6

Paragraph: 2

Type: editorial

Priority: medium

Problem:

This paragraph is awkward.

Recommended Solution:

Rephrase as "In addition, form controls need to identify the model
element that contains the instance data to which they are bound. This
is done via a model attribute, in conjunction with the ref attribute.
The default value for the model attribute is the first model element
(in document order)." Or something like that.
-----

Section: 3.2

Paragraph: 1

Type: editorial

Priority: low

Problem:

The phase "see the schema for XForms" in the middle of this paragraph
is not really necessary, and makes no sense if that phrase is
considered a dependent clause.

Recommended Solution:

Change to read "Every element defined in this specification declares
attribute id or type xsd:ID. Such elements are referencable via
attributes of type xsd:idref" and ensure that xsd:ID and xsd:idref are
links to the definition of those types elsewhere in the document.

-----

Section: 3.2

Paragraph: 3

Type: editorial

Priority: medium

Problem:

The Schema for XForms should be a link.

Recommended Solution:

Make it one.

-----

Section: 3.3

Paragraph: 1

Type: technical

Priority: critical

Problem:

This paragraph reads "The content of element model is typically not
rendered." This is a throw away phrase. We need to assert the behavior
of this element w.r.t. presentation.

Recommended Solution:

Change to read "The default behavior for the content of element model
is that it is not rendered."  Alternately, and better in my opinion,
"The content of element model must not be rendered."  Otherwise a
conforming implementation could be displaying the model, and we all
know we don't want that.  Ever.

-----

Section: 3.6

Paragraph: last

Type: editorial

Priority: high

Problem:

There is no reference to SOAP where a SOAP envelope is mentioned.

Recommended Solution:

Insert a reference to [SOAP], with a link into the informative
references.

-----

Section: 3.8.1

Paragraph: 2

Type: technical

Priority: high

Problem:

The prose says that the example is unusual because there is a default
xlink:type attribute.  I am sure there is, in the schema.  But we have
not really been introduced to the schema yet, and the syntax
definition in section 3.5 does not specify the default xlink:type
setting for the xlink:href attribute.  

Recommended Solution:

Ensure that whenever there is an xlink attribute presented in a syntax
definition, its default type is explicitly specified (if appropriate).
Add more descriptive text here about that attribute's importance.
Provide a link back to section 3.5.

-----

Section: 4.2.5

Paragraph: last

Type: technical

Priority: high

Problem:

This section introduces two important concepts with no explanation:
xforms without models, and multiply rooted instances data.  Neither
had been discussed before.  These are critical and difficult concepts,
and need to be defined and discussed before they are used.

Recommended Solution:

Add a definition of "multiply rooted" in the glossary/terms section,
and describe the behavior when there is no model element in section
3.3.  Note that in that section, it indicates that there may be one or
more model elements, so the absence of a model element is confusing
even to me.

-----

Section: 4.3.1

Paragraph: last

Type: technical

Priority: high

Problem:

According to the text, I am required to use scripting to bind events
to the instance data.  However, I think that if the instance data is
predeclared, and if that data has "id" attributes, it should be
possible to use XML Events to bind events to specific instances or to
whole collections of instance data.

Recommended Solution:

Make it clear that XML Events can be used in addition to scripts.

-----

Section: 4.3.2

Paragraph: list items 1 through 4

Type: technical

Priority: high

Problem:

This document introduces a navIndex attribute, using it in favor of
the tabindex attribute that is used in XHTML.  That's fine, but it is
not clear how the tabbing/navigation order of an XHTML document would
intersect with that of an embedded form.

Recommended Solution:

Clarify the relationship of navIndex to tabindex - here or in an
appendix.

-----

Section: 4.3.5

Paragraph: 2 (example)

Type: technical

Priority: high

Problem:

The example describes a situation where input validation is done. This
section (and others such as 4.3.12) implies that if an input field is
invalid (violates constraints?), an error would be displayed and the
user required to satisfy the constraints of the field.  This means that,
for example, if I start to enter my credit card number, then decide I
want to fill in some other field first, I can't.

Recommended Solution:

Don't have one.  I am hoping you will tell me I am wrong.

-----
Section: 4.3.5

Paragraph: 3

Type: editorial

Priority: low

Problem:

A word is missing.

Recommended Solution:

Change "... are expected optimize processing..." to "...are expected to
optimize processing..."

-----

Section: 4.3.17

Paragraph: list items 1 & 2

Type: technical

Priority: medium

Problem:

These are good assertions, but they are untestable.

Recommended Solution:

None, really.  I just wanted to be sure that you meant to have untestable
assertions as requirements for implementors.

-----

Section: 4.3.17

Paragraph: list item 4

Type: editorial

Priority: medium

Problem:

Why is MUST in uppercase in this paragraph?

Recommended Solution:

Change MUST to must.
-----

Section: 4.4.1

Paragraph: list item 1

Type: editorial

Priority: medium

Problem:

The second sentence doesn't make sense.

Recommended Solution:

Change it to read "This node and all child nodes are used in the remainder of
the submit process."

-----

Section: 4.4.1

Paragraph: list item 2

Type: technical

Priority: high

Problem:

This item indicates that invalid instance data encountered during the submit
process stops submit processing.  It does not indicate what (if any) events
are raised when this happens, or how errors are manifested to the user.

Recommended Solution:

Make it clear what happens when submit processing stops.

-----

Section: 4.4.1

Paragraph: list item 3

Type: editorial

Priority: low

Problem:

THe second sentence is awkward.

Recommended Solution:

Change to read "Nodes that have associated relevant constraints that evaluate
to false are not serialized."

-----

Section: 4.4.2

Paragraph: 3

Type: editorial

Priority: medium

Problem:

Wrong word.

Recommended Solution:

Change "expresses" to "express".
-----

Section: 4.4.2

Paragraph: all

Type: technical

Priority: high

Problem:

This section uses the term urlencoded, but that term is not defined.

Recommended Solution:

Define the term.
-----

Section: 4.4.4

Paragraph: list item 2

Type: editorial

Priority: low

Problem:

Wrong word.

Recommended Solution:

Change "an the above" to "the above" - I think.  This whole item reads very
strangely.
-----

Section: 4.5

Paragraph: all

Type: technical

Priority: high

Problem:

The items in this section talk about default error handling, but that is not
defined.

Recommended Solution:

Define default error handling.

-----

Section: 6.1.4

Paragraph: user interaction table

Type: technical

Priority: high

Problem:

The false items use "should".  I believe these are "must" constraints.

Recommended Solution:

Change "should" to "must".

-----

Section: 6.2.1

Paragraph: list item 4

Type: editorial

Priority: low

Problem:

Missing quotes.

Recommended Solution:

Put quotes around the attribute value.

-----

Section: 6.3.2

Paragraph: example text

Type: technical

Priority: high

Problem:

I don't think this example actually does what it is supposed to.  The union
doesn't seem to be a combination of the enumerated set and an "other" item.

Recommended Solution:

Fix the example or show me that I am wrong.

-----

Section: 6.4.2

Paragraph: list item 1

Type: editorial

Priority: low

Problem:

The formatting of the example seems wrong.

Recommended Solution:

Fix the indentation.

-----

Section: 6.4.2

Paragraph: last

Type: technical

Priority: high

Problem:

This section indicates that processing can terminate with a fatal error.  It
does not, however, define what that error is, or what event might be raised.

Recommended Solution:

Describe what it means to terminate with a fatal error.

-----

Section: 7.4.2

Paragraph: all

Type: technical

Priority: medium

Problem:

Many of the items in this section talk about NaN.  On platforms that do not
support IEEE Floating Point, is there a concept of Nan?

Recommended Solution:

If there is, do nothing.  If not, let's describe what happens on platforms
without IEEE Floating Point.

-----

Section: 7.4.2.5

Paragraph: last

Type: technical

Priority: High

Problem:

This section indicates that an error is thrown, but does not indicate what
type of error.

Recommended Solution:

Define the error.
-----

Section: 7.4.4

Paragraph: last

Type: editorial

Priority: low

Problem:

Missing word.

Recommended Solution:

Change "...XForms processors detect the..." to "...XForms processors to detect
the...".

-----

Section: 8

Paragraph: all

Type: technical

Priority: medium

Problem:

Throughout this section you indicate that form controls can by styled by using
CSS in conjunction with the class attribute.  I believe that you can also use
the id attribute.

Recommended Solution:

If I am correct, add id to the discussion of styling form controls.

-----

Section: 8.2

Paragraph: last

Type: technical

Priority: high

Problem:

The example has a caption element, but it does not show up in the sample
output.

Recommended Solution:

Fix the example source or the example output.

-----

Section: 8.4

Paragraph: 1

Type: technical

Priority: medium

Problem:

The concept of "display:inline" has not been defined in this spec.

Recommended Solution:

Define it by reference to CSS or remove the text about layout (it isn't really
needed here).

-----

Section: 8.5

Paragraph: 1

Type: editorial

Priority: medium

Problem:

The first sentence is a little colloquial.

Recommended Solution:

Change it to "This form control enables uploading of files from the local file
system, as well as..."

-----

Section: 8.5

Paragraph: Implementation requirements

Type: editorial

Priority: medium

Problem:

Wrong word.

Recommended Solution:

Change "Implementations may provide proprietary implementations..." to
"Implementations may provide proprietary interfaces..."

-----

Section: 8.6

Paragraph: 3

Type: editorial

Priority: medium

Problem:

The whole paragraph is really awkward.

Recommended Solution:

Rewrite it so it is more than one sentence.

-----

Section: 8.7

Paragraph: 1

Type: editorial

Priority: low

Problem:

The phrasing of the whole second sentence is a little weird.

Recommended Solution:

Change to read "This form control may also be used to construct other custom
form controls."

-----

Section: 8.9

Paragraph: 3

Type: technical

Priority: high

Problem:

This section seems to imply that an item of a selection list must always be
selected.  I think there should be a way have a list with nothing selected.

Recommended Solution:

Clarify how a list can have no items selected.

-----

Section: 8.9

Paragraph: 5 & 6

Type: editorial

Priority: high

Problem:

These paragraphs seem to be saying the same thing in different ways.

Recommended Solution:

Consolidate them.

-----

Section: 8.12.3

Paragraph: last

Type: technical

Priority: high

Problem:

This says it is an error if...  Is this just a usage constraint, or is there
an actial error event that is raised when these conditions are met?

Recommended Solution:

Clarify this.

-----

Section: 8.12.4.4

Paragraph: last

Type: editorial

Priority: medium

Problem:

extra word.

Recommended Solution:

Change "exist at in instance" to "exist in instance".

-----

Section: 9.3.1

Paragraph: list item 4

Type: technical

Priority: high

Problem:

This item indicates that an error is signalled and processing stops.  Is there
an actual error event?  And what does it mean that processing stops?

Recommended Solution:

Clarify this.

-----

Section: 9.3.1

Paragraph: last - 1

Type: editorial

Priority: low

Problem:

Wrong number.

Recommended Solution:

Change "...node-set represent a homogenous..." to "...node-set represents a
homogenous..."

-----

Section: 10.6

Paragraph: 1

Type: technical

Priority: high

Problem:

The treatment of both items being present is inconsistent with the way
multiple items are treated in other elements.

Recommended Solution:

Change so that the xlink:href attribute takes precedence.

-----

Section: 10.6

Paragraph: all

Type: technical

Priority: high

Problem:

The spec currently uses the term "application-specific".  I prefer the term
"implementation-defined", as that requires the application to define how it
behaves.

Recommended Solution:

Change "application-specific" to "implementation-defined".

-----

Section: 10.7

Paragraph: last

Type: technical

Priority: high

Problem:

This section shows that you can set the value of a node to the smpty string.
Is there a way to set the value to null or undef?

Recommended Solution:

None.

-----

Section:  10.14

Paragraph: 1

Type: technical

Priority: medium

Problem:

This section seems to imply that an ev:handler value must be a script.  I
think that xml events permits handlers to be non-scripted.

Recommended Solution:

If I am right, change the text so that it does not imply that the event
handlers must be scripts.

-----

Section: 11.1

Paragraph: all

Type: technical

Priority: medium

Problem:

This conformance requirements say "should" when hey should really say "must".

Recommended Solution:

Change "should" to "must".

-----

Section: B

Paragraph: XHTML 1.0

Type: tecnical

Priority: high

Problem:

I think that this should reference XHTML 1.1, not 1.0.

Recommended Solution:

Change the reference.

-----

Section: C.1

Paragraph: 2

Type: technical

Priority: high

Problem:

This section also indicates that there can be a fatal exception.

Recommended Solution:

Clarify what really happens.

-----

Section: E.1

Paragraph: example

Type: editorial

Priority: high

Problem:

When you imported the text, you neglected to escape the dollarsigns.  That
means that the CVS Id at the top became the Id of the spec, instead of the Id
of the example.

Recommended Solution:

Escape dollarsigns when importing examples into the document.

-----