[whatwg] [html5] contenteditable specification

Tue Jul 19 19:59:14 PDT 2005

On Tue, 19 Jul 2005, Anne van Kesteren wrote:
>
> http://annevankesteren.nl/projects/whatwg/spec

Overall the main problem with this spec is the lack of the use of
RFC2119 normative words.

For example:

|    The contentEditable applies to all elements with some exceptions: It
|    does not apply to table elements, the html element and descendants of
|    the head element and the head element itself. It is expected that a
|    future revision of this draft includes support for editable tables.

This section says nothing normative, and is therefore, in theory,
merely describing the result of applying all the user agent normative
conformance criteria. However, the relevant conformance criteria is
the next sentence:

|    If an HTML element has a contentEditable attribute set to exactly the
|    literal value true, or if its nearest ancestor with the
|    contentEditable attribute set has its attribute set to exactly the
|    literal value true, then the UA must treat the element as editable (as
|    described below).

...which does not have any exceptions and therefore applies to any
HTML element, including all those that the first paragraph said the
attribute didn't apply to.

Another general comment is you're missing some sort of "processing
model" section. Your spec goes straight from "here's what an editing
host is" to "and if you hit enter then it does this", without
explaining that clicking an editing host might focus it, or that there
is a "current cursor position" in it, or that the cursor can be in a
text node. It doesn't say if you can put a cursor in between two
blocks, it doesn't say whether an empty block can have a cursor, etc.
These seem like quite important things.

As an implementor, looking at this spec, I'd have no idea what to do.

|    Creating a line-break inside an editing host must result in the
|    generation of a br element on the current cursor position.

What does "must result in the generation of a br element on the
current cursor position" mean?

I would rephrase the first two paragraphs of that section with
(RFC2119 terms are capitalised here so you can see them clearly):

   User agents SHOULD allow users to enter line breaks in editing
   hosts. The exact interface for this is implementation dependent.
   When the user requests a line break, the user agent MUST insert a
   br element at the current cursor position.

This is simpler, and more to the point, while having exactly the same
normative content. In non-normative prose like your first sentence
here, there's no point being as detailed as you are regarding events.
Just saying "In most UAs this will happen when the user hits
Shift+Enter" is ok, since it's non-normative anyway.

Having said that, maybe we should specify (normatively) that it must
happen as the default action of the keydown event (or whatever event
it is), when the target is the editing host, or some such.

|    When the editing host contains only inline level elements or p
|    elements creating a block-break will result in the generation of
|    a p element containing the entity  . If the text nodes and
|    or inline level elements inside the editing host were not yet
|    contained inside a p element the editor must wrap a p element
|    around them so that there are at least two sibling p elements
|    inside the editable parent element.

The first sentence here (the key sentence) has no normative criteria
(no "must", just a "will"). I also don't really understand it. An
element is generated (what does that mean?) but nothing is done with
it. Is it supposed to be inserted somewhere?

Does the new paragraph contain an entity reference node, or does it
contain an actual U+00A0 character? There is no such concept as "&nbsp
entity" in the DOM.

How does the wrapping work? What if you have something like:

   <div contentEditable>
    <em>AAA</em>
    <p>BBB</p>
    CCC
   </div>

...and you put the cursor in the As and ask the UA to create a new
block break, what happens? (If I interpret your text literally, then a
new element containing an entity reference node called "nbsp" will
be generated (but not inserted into the document anywhere, so it
doesn't matter that it was generated), then the and CCC nodes
will be wrapped in a , giving us:

   <div contentEditable>
    <p>
     <em>AAA</em>
     <p>BBB</p>
     CCC
    </p>
   </div>

...but there are still no two sibling <p> elements so presumably
that's not what you meant.)

What about if the cursor is in the BBB or CCC text? What if it is
after the element before the ?

|    In addition, when the editing host contains inline level elements
|    these must be duplicated inside the newly generated p elements
|    when creating a block-break happens before the last white-space
|    node or text node in the element. The a element must not be
|    duplicated.

I have no idea what this means. How do you "duplicate" a node? Which
inlines are duplicated? What's the difference between a "white-space
node" and a "text node"?

|    When the editing host contains a block level element as child element
|    (e.g. a div element) the block level element must be duplicated and no
|    p element must be generated.

Same problems as above: "duplicated" is meaningless in DOM terms, and
it doesn't say anything about what to do with the "duplicated"
element. (Does "duplicated" mean cloned? Deep cloned? Shallow cloned?
What happens to the contents of the original element?)

|    Some block level elements form an exception to this rule:
| 
|    hx elements
|           These elements will generate a p element when a block-break is
|           generated at the end of the element or one position before the
|           end of the element when the last character is a   entity.

No normative conformance criteria here.

|    li element
|           When creating a block-break inside an empty li element its
|           parent element must be closed when the parent element is ul or
|           ol and a p element shall be generated.

"closed" and "generated" aren't well defined terms.

|    Attributes on newly generated or duplicated elements must be
|    copied from the element or elements were the action for creating
|    these elements took place with the exception of the id attribute.

Content attributes? DOM attributes? Both?

|    The selected text must be copied to the clipboard and after that
|    removed from the DOM. This action does not apply when no text is
|    selected.

What happens if the selection is non-contiguous? What if it spans out
of the contentEditable section? What if it crosses elements in the
DOM? Is only text copied or is any of the structure copied too? Are
only text nodes removed from the DOM or are elements removed too? What
if images are part of the selection? Is the text that is copied the
text from the DOM or from the rendering?

|    Denotes the start and end of an important phrase. If text is already
|    selected the selected text must be markup up as being important.

How, exactly?

|    Element that must be used for denoting is strong. If no text is
|    selected the action acts like a boolean. When denoting importance is
|    turned off it must be turned on and the other way around.

How exactly does that work?

|    img elements inside an editable region can be selected, resized
|    (with respect to their containing block) and copied. The first
|    time you resize the img element its height and width attribute
|    gets set. If you later resize the img again the height and width
|    attribute stay the same and the style attribute is used instead
|    using the height and width properties from CSS. If the height and
|    width attributes were already set they must not be changed by the
|    UA.

No conformance criteria. Same applies to most of the text in this and
nearby sections.

|    input elements with a type attribute value of text, password,
|    button, submit, reset can have a value attribute set when they
|    are double clicked upon. input elements with a type attribute
|    value of radio or checkbox can have the checked boolean attribute
|    set through user interaction. When type is radio this is only
|    possible when a name attribute is set.

This paragraph needs a LOT of work. It's probably the kind of thing
that should go up into the processing model section I mentioned
earlier. It needs to be much more detailed. "can have a value
attribute set"? What does that mean? And so on.

|    The commandIdentifier argument is case-insensitive.

What exactly does this mean, in terms of Unicode?

| backColor (deprecated)
| value must be a <color> value as defined in CSS 2.1. # may be
| omitted for three-digit and six-digit RGB notation.
| 
| When text is selected it must be wrapped inside a font element.
| This element has a style attribute using the background-color
| property from CSS to denote the color specified in the value
| argument.

This isn't very clear. How can text spanning elements be wrapped
inside a single element? What about non-contiguous selections? Does
the colour specified have to be taken literally or is it interpreted?

| [...]

I haven't looked at the rest yet.

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