[whatwg] "must only" ambiguity

[Philip Taylor]

"Documents and document fragments / Structure" says "Authors must only
use elements in the HTML namespace in the contexts where they are
allowed, as defined for each element."

That phrase is unclear. It could be interpreted as:

"Authors must { only use elements in the HTML namespace } in { the
contexts where [elements in the HTML namespace] are allowed }", i.e.
contexts expecting HTML namespaced elements mustn't contain foreign
content.

"Authors must { [...] use elements in the HTML namespace } [only] { in
the contexts where they are allowed }", i.e. HTML elements must not be
used where they aren't allowed.

"Authors must only { use elements in the HTML namespace in the
contexts where they are allowed }", i.e. pretty much every imaginable
action in the entire world is disallowed, except for using elements
where allowed.

A suggested replacement: "Authors must not use elements in the HTML
namespace except where allowed by the context defined for the
element".


Similarly, "Authors must only put elements inside an element if that
element allows them to be there according to its content model" should
be fixed to say something like "Authors must not put elements inside
an element unless that element allows them to be there according to
its content model".


More generally, all uses of "must only" and "may only" etc seem
dangerous. The spec says "The key words [...] in the normative parts
of this document are to be interpreted as described in RFC2119", but
instead they have to be interpreted as described by the standard
English grammar rules when they're used in complex phrases like "must
only", which makes the spec harder to read when you're trying to read
the normative requirements, and can cause misunderstanding. (Does that
make things particularly harder for non-native-English-speaking
people?)

The conformance requirements would be clearer if all occurrences of "x
must only y" and "x may only y" were replaced by "x must not { not y
}" or by "x may y, and x must not { not y }".

Similarly, "x should only y if z" (e.g. "authors should only use these
elements if the absence of those elements would change the meaning of
the content") should be replaced by "x should y if z, and should not
do so otherwise" or "x should not y if not z" (depending on which
directions the 'should' applies in).

-- 
Philip Taylor
excors at gmail.com