Add more documentation, and an XXX
authorAryeh Gregor <ayg@aryeh.name>
Thu, 19 Jan 2012 12:16:54 -0700
changeset 696 758b94dabbe3
parent 695 7a3dd651793b
child 697 02bc6abebc3a
Add more documentation, and an XXX
editing.html
source.html
--- a/editing.html	Tue Jan 17 11:43:07 2012 -0700
+++ b/editing.html	Thu Jan 19 12:16:54 2012 -0700
@@ -67,7 +67,7 @@
 <body class=draft>
 <div class=head id=head>
 <h1>HTML Editing APIs</h1>
-<h2 class="no-num no-toc" id=work-in-progress-&mdash;-last-update-17-january-2012>Work in Progress &mdash; Last Update 17 January 2012</h2>
+<h2 class="no-num no-toc" id=work-in-progress-&mdash;-last-update-19-january-2012>Work in Progress &mdash; Last Update 19 January 2012</h2>
 <dl>
  <dt>Editor
  <dd>Aryeh Gregor &lt;<a href=mailto:ayg@aryeh.name>ayg@aryeh.name</a>&gt;
@@ -1077,7 +1077,12 @@
 method must run the following steps:
 
 <ol>
-  <li>Let <var title="">range</var> be a new <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-range title=concept-range>range</a>.
+  <li>
+  <p class=comments>The new range replaces any existing one, doesn't mutate it.
+  This matches IE9 and Firefox 12.0a1.  (Chrome 17 dev and Opera Next 12.00
+  alpha can't be tested, because getRangeAt() returns a copy anyway.)
+
+  <p>Let <var title="">range</var> be a new <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-range title=concept-range>range</a>.
 
   <li><a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-range-bp-set title=concept-range-bp-set>Set</a> <var title="">range</var>'s <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-range-start title=concept-range-start>start</a> to (<var title="">node</var>, 0).
 
@@ -1089,11 +1094,20 @@
   <li>Set the <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#context-object>context object</a>'s <a href=#concept-selection-dir title=concept-selection-dir>direction</a> to <i title="">forwards</i>.
 </ol>
 
+<p class=comments>This is the one method that actually mutates the range
+instead of replacing it.  This matches IE9 and Firefox 12.0a1.  (Chrome 17 dev
+and Opera Next 12.00 alpha can't be tested, because getRangeAt() returns a copy
+anyway.)
+
 <p>The <dfn id=dom-selection-deletefromdocument title=dom-Selection-deleteFromDocument><code>deleteFromDocument()</code></dfn>
 method must do nothing if the <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#context-object>context object</a>'s <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-range title=concept-range>range</a> is null, and
 otherwise must invoke the <code class=external data-anolis-spec=dom title=dom-Range-deleteContents><a href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-range-deletecontents>deleteContents()</a></code> method on the
 <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#context-object>context object</a>'s <a class=external data-anolis-spec=dom href=http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-range title=concept-range>range</a>.
 
+<p class=XXX>Should we replace the range rather than mutating it here?  This is
+currently the only Selection method that actually mutates an existing range in
+place.
+
 <dl class=domintro>
   <dt><var title="">selection</var> . <code title=dom-Selection-rangeCount><a href=#dom-selection-rangecount>rangeCount</a></code>
   <dd>
--- a/source.html	Tue Jan 17 11:43:07 2012 -0700
+++ b/source.html	Thu Jan 19 12:16:54 2012 -0700
@@ -1025,7 +1025,12 @@
 method must run the following steps:
 
 <ol>
-  <li>Let <var>range</var> be a new [[range]].
+  <li>
+  <p class=comments>The new range replaces any existing one, doesn't mutate it.
+  This matches IE9 and Firefox 12.0a1.  (Chrome 17 dev and Opera Next 12.00
+  alpha can't be tested, because getRangeAt() returns a copy anyway.)
+
+  <p>Let <var>range</var> be a new [[range]].
 
   <li>[[Rangeset]] <var>range</var>'s [[rangestart]] to (<var>node</var>, 0).
 
@@ -1037,6 +1042,11 @@
   <li>Set the [[contextobject]]'s [[seldir]] to <i title>forwards</i>.
 </ol>
 
+<p class=comments>This is the one method that actually mutates the range
+instead of replacing it.  This matches IE9 and Firefox 12.0a1.  (Chrome 17 dev
+and Opera Next 12.00 alpha can't be tested, because getRangeAt() returns a copy
+anyway.)
+
 <p>The <dfn
 title=dom-Selection-deleteFromDocument><code>deleteFromDocument()</code></dfn>
 method must do nothing if the [[contextobject]]'s [[range]] is null, and
@@ -1044,6 +1054,10 @@
 title=dom-Range-deleteContents>deleteContents()</code> method on the
 [[contextobject]]'s [[range]].
 
+<p class=XXX>Should we replace the range rather than mutating it here?  This is
+currently the only Selection method that actually mutates an existing range in
+place.
+
 <dl class=domintro>
   <dt><var>selection</var> . <code title=dom-Selection-rangeCount>rangeCount</code>
   <dd>