Review of XForms 2.0 sections 1-3

All,

For reference, this is the document I reviewed:

    http://homepages.cwi.nl/~steven/forms/WD-xforms20-20140702/Overview.html#The_function_Element

A few things, nothing major so far:

1. "XForms are the successor to HTML forms"

This use of "are" might have fallen through the cracks. I really
prefer "is". Also, it's a bit pretentious to say it is "the"
successor. What about:

   "XForms is a successor to HTML forms"

2. "http:" URLs

We have a lot of "http:" URLs in particular in the "Introduction to
XForms" section, where credit card information is submitted! I suggest
replacing all "http:" URLs with "https:" URLs, as the web is moving in
that direction anyway.

3. 'choose()' function

In section 2.7, we use the `choose()` function. We seem to be using
XPath 2 in other places, so I would use the XPath 2 `if` construct,
which is more natural:

    <output class="{if (total ge 0) then 'positive' else 'negative'}"
ref="total"/>

4. `function` and `result` elements in table

The table at the beginning of section "3.2 The XForms Core Module"
lists the `function` and the `result` elements, but these two are not
described in this section. Instead, they are described in section
"4.11 The function Element". We might want to remove those from the
core module, or to add an indirection, as we do for the `submission`
element.

5. Inconsistencies referring to exceptions and errors

This is not extremely important, and goes beyond sections 1-3, but I
couldn't help noticing that we use different language all over the
place to refer to exceptions and errors. Here are some examples:

"dispatching the event xforms-version-exception"
"after dispatching an xforms-link-exception"
"by signaling an exception (xforms-compute-exception)"
"it is treated as an exception (The xforms-link-exception Event)."
"halts with an exception (The xforms-link-exception Event)."
"must report an exception (The xforms-compute-exception Event)."
"causes an exception (The xforms-compute-exception Event)"
"an exception (The xforms-compute-exception Event) must be thrown"

"an (xforms-binding-error) occurs"
"An (The xforms-binding-error Event) must"
"It is an error (The xforms-binding-error Event) if"
"An error (The xforms-expression-error Event) must be thrown"
"dispatching an xforms-expression-error Event, "
"after dispatching xforms-submit-error with" [not linked in 7.2 The
xforms-submit Event]
"an (xforms-binding-error) occurs"
"results in an xforms-submit-error event" [unlinked in 7.10.3 SOAP HTTP Binding]
"which is to say that an xforms-submit-error event is dispatched"
"an xforms-binding-error must occur"
"element should result in an xforms-output-error"
"the submit process concludes with either an xforms-submit-done or
xforms-submit-error event"
etc.

6. "The p3ptype is deprecated"

In section "6.1.7 The p3ptype Property (deprecated)", this is to be
the missing word. Suggesting:

    The p3ptype attribute is deprecated

That's it for today! Feedback welcome,

-Erik

Received on Tuesday, 23 September 2014 22:41:25 UTC