--- a/editing.html Thu Aug 04 12:41:30 2011 -0600
+++ b/editing.html Fri Aug 05 10:38:58 2011 -0600
@@ -22,6 +22,7 @@
white-space: pre-wrap;
}
div.note > p:first-child::before { content: 'Note: '; }
+.note var { font-style: normal }
.XXX > :last-child { margin-bottom: 0 }
.XXX li {
margin-top: 0;
@@ -62,7 +63,7 @@
<body class=draft>
<div class=head id=head>
<h1>HTML Editing APIs</h1>
-<h2 class="no-num no-toc" id=work-in-progress-—-last-update-4-august-2011>Work in Progress — Last Update 4 August 2011</h2>
+<h2 class="no-num no-toc" id=work-in-progress-—-last-update-5-august-2011>Work in Progress — Last Update 5 August 2011</h2>
<dl>
<dt>Editor
<dd>Aryeh Gregor <<a href=mailto:ayg@aryeh.name>ayg@aryeh.name</a>>
@@ -938,6 +939,14 @@
location. In doing so, however, ignore the regular <a class=external data-anolis-spec=domrange href=http://html5.org/specs/dom-range.html#range-mutation-rules>range mutation rules</a>, and
instead follow these rules:
+<p class=note>Many of the algorithms in this specification move nodes around in
+the DOM. The normal rules for range mutation require that any range endpoints
+inside those nodes are moved to the node's parent as soon as the node is moved,
+which would corrupt the selection. For instance, if the user selects the text
+"foo" and then bolds it, first we produce <code title=""><b></b>foo</code>, then <code title=""><b>foo</b></code>. When
+we move the "foo" text node into its new parent, we have to do so "preserving
+ranges", so that the text "foo" is still selected.
+
<ol>
<li>Let <var title="">node</var> be the moved <a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-node title=concept-node>node</a>, <var title="">old parent</var> and
<var title="">old index</var> be the old <a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-tree-parent title=concept-tree-parent>parent</a> (which may be null) and <a class=external data-anolis-spec=domrange href=http://html5.org/specs/dom-range.html#concept-indexof title=concept-indexof>index</a>,
@@ -971,6 +980,12 @@
<p>To <dfn id=set-the-tag-name>set the tag name</dfn> of an <code class=external data-anolis-spec=domcore><a href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#element>Element</a></code> <var title="">element</var> to
<var title="">new name</var>:
+<p class=note>This is needed because the DOM doesn't allow any way of changing
+an existing element's name. Sometimes we want to, e.g., convert a markup
+element to a span. In that case we invoke this algorithm to create a new
+element, move it to the right place, copy attributes from the old element, move
+the old element's children, and remove the old element.
+
<ol>
<li>If <var title="">element</var> is an <a href=#html-element>HTML element</a> with <a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-element-local-name title=concept-element-local-name>local name</a>
equal to <var title="">new name</var>, return <var title="">element</var>.
@@ -998,6 +1013,10 @@
<p>To <dfn id=remove-extraneous-line-breaks-before>remove extraneous line breaks before</dfn> a <a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-node title=concept-node>node</a>
<var title="">node</var>:
+<p class=note><code title=""><br></code> sometimes has no effect in CSS, such
+as in the markup <code title="">foo<br><p>bar</p></code>. In such cases
+we like to remove the extra markup to keep things tidy.
+
<ol>
<li>Let <var title="">ref</var> be the <code class=external data-anolis-spec=domcore title=dom-Node-previousSibling><a href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-node-previoussibling>previousSibling</a></code> of <var title="">node</var>.
@@ -1048,6 +1067,15 @@
or null. If not provided, <var title="">sibling criteria</var> returns false and
<var title="">new parent instructions</var> returns null.
+<p class=note>This algorithm basically does two things. First, it looks at the
+previous and next siblings of the nodes in <var title="">node list</var>. If running
+<var title="">sibling criteria</var> on one or both of the siblings returns true, the
+nodes in <var title="">node list</var> are moved into the sibling(s). Otherwise,
+<var title="">new parent instructions</var> is run, and the result is used to wrap
+<var title="">node list</var>. For instance, to wrap <var title="">node list</var> in a <code title=""><b></code>, one might invoke this algorithm with <var title="">sibling
+criteria</var> returning true only for <code title=""><b></code> elements and
+<var title="">new parent instructions</var> creating and returning a new <code title=""><b></code> element.
+
<ol>
<li>If <var title="">node list</var> is empty, or the first member of <var title="">node
list</var> is not <a href=#editable>editable</a>, return null and abort these steps.
@@ -1270,6 +1298,13 @@
<p>A <a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-node title=concept-node>node</a> or string <var title="">child</var> is an <dfn id=allowed-child>allowed child</dfn> of a
<a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-node title=concept-node>node</a> or string <var title="">parent</var> if the following algorithm returns true:
+<p class=note>Often we move around nodes, and sometimes this can result in
+unreasonable things like two <code title=""><p></code>'s nested inside one
+another. This algorithm checks for DOMs we never want to have, so that other
+algorithms can avoid creating them or fix them if they do happen. The
+<a href=#fix-disallowed-ancestors>fix disallowed ancestors</a> algorithm is one frequently-invoked
+caller of this algorithm.
+
<ol>
<li>If <var title="">parent</var> is "colgroup", "table", "tbody", "tfoot", "thead",
"tr", or an <a href=#html-element>HTML element</a> with <a class=external data-anolis-spec=domcore href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-element-local-name title=concept-element-local-name>local name</a> equal to one of
@@ -1479,7 +1514,12 @@
</ul>
<p class=note>Conceptually, a simple modifiable element is a modifiable element
-which specifies a value for at most one command.
+which specifies a value for at most one command. As the names imply, inline
+formatting commands will try not to modify anything other than modifiable
+elements. For instance, <code title=""><dfn></code> normally creates italics,
+but it's not modifiable, so running <a href=#the-italic-command>the <code title="">italic</code>
+command</a> will not remove it: it will nest <code title=""><span
+style="font-style: normal"></code> inside.
<p>Two quantities are <dfn id=equivalent-values>equivalent values</dfn> for a <a href=#command>command</a>
if either both are null, or both are strings and they're equal and the
@@ -1511,7 +1551,7 @@
values and at least one whose <a href=#effective-command-value>effective command value</a> is not one
of the given values.
-<p class=comments> For bold and similar commands, IE 9 RC seems to consider the
+<p class=comments>For bold and similar commands, IE 9 RC seems to consider the
state true or false depending on the first element. All other browsers follow
the same general idea as the spec, considering a range bold only if all text in
it is bold, and this seems to match at least OpenOffice.org's bold feature.
@@ -1559,6 +1599,9 @@
cannot be null, since the boundary point node of a selection must always be
either an element or a text node that's the child of an element.
+<p class=note>The notions of inline command activated values and standard
+inline value commands are mostly just shorthand to avoid repeating the same
+boilerplate half a dozen times.
<h3 id=assorted-inline-formatting-command-algorithms><span class=secno>7.2 </span>Assorted inline formatting command algorithms</h3>
--- a/source.html Thu Aug 04 12:41:30 2011 -0600
+++ b/source.html Fri Aug 05 10:38:58 2011 -0600
@@ -24,6 +24,7 @@
white-space: pre-wrap;
}
div.note > p:first-child::before { content: 'Note: '; }
+.note var { font-style: normal }
.XXX > :last-child { margin-bottom: 0 }
.XXX li {
margin-top: 0;
@@ -893,6 +894,15 @@
location. In doing so, however, ignore the regular [[rangemutationrules]], and
instead follow these rules:
+<p class=note>Many of the algorithms in this specification move nodes around in
+the DOM. The normal rules for range mutation require that any range endpoints
+inside those nodes are moved to the node's parent as soon as the node is moved,
+which would corrupt the selection. For instance, if the user selects the text
+"foo" and then bolds it, first we produce <code
+title><b></b>foo</code>, then <code title><b>foo</b></code>. When
+we move the "foo" text node into its new parent, we have to do so "preserving
+ranges", so that the text "foo" is still selected.
+
<ol>
<li>Let <var>node</var> be the moved [[node]], <var>old parent</var> and
<var>old index</var> be the old [[parent]] (which may be null) and [[index]],
@@ -926,6 +936,12 @@
<p>To <dfn>set the tag name</dfn> of an [[element]] <var>element</var> to
<var>new name</var>:
+<p class=note>This is needed because the DOM doesn't allow any way of changing
+an existing element's name. Sometimes we want to, e.g., convert a markup
+element to a span. In that case we invoke this algorithm to create a new
+element, move it to the right place, copy attributes from the old element, move
+the old element's children, and remove the old element.
+
<ol>
<li>If <var>element</var> is an <span>HTML element</span> with [[localname]]
equal to <var>new name</var>, return <var>element</var>.
@@ -955,6 +971,10 @@
<p>To <dfn>remove extraneous line breaks before</dfn> a [[node]]
<var>node</var>:
+<p class=note><code title><br></code> sometimes has no effect in CSS, such
+as in the markup <code title>foo<br><p>bar</p></code>. In such cases
+we like to remove the extra markup to keep things tidy.
+
<ol>
<li>Let <var>ref</var> be the [[previoussibling]] of <var>node</var>.
@@ -1005,6 +1025,17 @@
or null. If not provided, <var>sibling criteria</var> returns false and
<var>new parent instructions</var> returns null.
+<p class=note>This algorithm basically does two things. First, it looks at the
+previous and next siblings of the nodes in <var>node list</var>. If running
+<var>sibling criteria</var> on one or both of the siblings returns true, the
+nodes in <var>node list</var> are moved into the sibling(s). Otherwise,
+<var>new parent instructions</var> is run, and the result is used to wrap
+<var>node list</var>. For instance, to wrap <var>node list</var> in a <code
+title><b></code>, one might invoke this algorithm with <var>sibling
+criteria</var> returning true only for <code title><b></code> elements and
+<var>new parent instructions</var> creating and returning a new <code
+title><b></code> element.
+
<ol>
<li>If <var>node list</var> is empty, or the first member of <var>node
list</var> is not <span>editable</span>, return null and abort these steps.
@@ -1237,6 +1268,13 @@
<p>A [[node]] or string <var>child</var> is an <dfn>allowed child</dfn> of a
[[node]] or string <var>parent</var> if the following algorithm returns true:
+<p class=note>Often we move around nodes, and sometimes this can result in
+unreasonable things like two <code title><p></code>'s nested inside one
+another. This algorithm checks for DOMs we never want to have, so that other
+algorithms can avoid creating them or fix them if they do happen. The
+<span>fix disallowed ancestors</span> algorithm is one frequently-invoked
+caller of this algorithm.
+
<ol>
<li>If <var>parent</var> is "colgroup", "table", "tbody", "tfoot", "thead",
"tr", or an <span>HTML element</span> with [[localname]] equal to one of
@@ -1446,7 +1484,12 @@
</ul>
<p class=note>Conceptually, a simple modifiable element is a modifiable element
-which specifies a value for at most one command.
+which specifies a value for at most one command. As the names imply, inline
+formatting commands will try not to modify anything other than modifiable
+elements. For instance, <code title><dfn></code> normally creates italics,
+but it's not modifiable, so running <span>the <code title>italic</code>
+command</span> will not remove it: it will nest <code title><span
+style="font-style: normal"></code> inside.
<p>Two quantities are <dfn>equivalent values</dfn> for a <span>command</span>
if either both are null, or both are strings and they're equal and the
@@ -1479,7 +1522,7 @@
values and at least one whose <span>effective command value</span> is not one
of the given values.
-<p class=comments> For bold and similar commands, IE 9 RC seems to consider the
+<p class=comments>For bold and similar commands, IE 9 RC seems to consider the
state true or false depending on the first element. All other browsers follow
the same general idea as the spec, considering a range bold only if all text in
it is bold, and this seems to match at least OpenOffice.org's bold feature.
@@ -1527,6 +1570,9 @@
cannot be null, since the boundary point node of a selection must always be
either an element or a text node that's the child of an element.
+<p class=note>The notions of inline command activated values and standard
+inline value commands are mostly just shorthand to avoid repeating the same
+boilerplate half a dozen times.
<!-- @} -->
<h3>Assorted inline formatting command algorithms</h3>