hixie: Provide advice to authors regarding styling editing regions (whatwg r6570)

hixie: Provide advice to authors regarding styling editing regions
(whatwg r6570)

http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.5263&r2=1.5264&f=h
http://html5.org/tools/web-apps-tracker?from=6569&to=6570

===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.5263
retrieving revision 1.5264
diff -u -d -r1.5263 -r1.5264
--- Overview.html 22 Sep 2011 23:53:52 -0000 1.5263
+++ Overview.html 23 Sep 2011 00:17:09 -0000 1.5264
@@ -321,7 +321,7 @@
 
    <h1>HTML5</h1>
    <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
-   <h2 class="no-num no-toc" id="editor-s-draft-22-september-2011">Editor's Draft 22 September 2011</h2>
+   <h2 class="no-num no-toc" id="editor-s-draft-23-september-2011">Editor's Draft 23 September 2011</h2>
    <dl><dt>Latest Published Version:</dt>
     <dd><a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a></dd>
     <dt>Latest Editor's Draft:</dt>
@@ -467,7 +467,7 @@
   Group</a> is the W3C working group responsible for this
   specification's progress along the W3C Recommendation
   track.
-  This specification is the 22 September 2011 Editor's Draft.
+  This specification is the 23 September 2011 Editor's Draft.
   </p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>Work on this specification is also done at the <a href="http://www.whatwg.org/">WHATWG</a>. The W3C HTML working group
   actively pursues convergence with the WHATWG, as required by the <a href="http://www.w3.org/2007/03/HTML-WG-charter">W3C HTML working
   group charter</a>.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
@@ -1101,9 +1101,10 @@
      <li><a href="#contenteditable"><span class="secno">7.5.1 </span>Making document regions editable: The <code title="attr-contenteditable">contenteditable</code> content
   attribute</a></li>
      <li><a href="#making-entire-documents-editable:-the-designmode-idl-attribute"><span class="secno">7.5.2 </span>Making entire documents editable: The <code title="dom-document-designMode">designMode</code> IDL attribute</a></li>
-     <li><a href="#user-editing-actions"><span class="secno">7.5.3 </span>User editing actions</a></li>
-     <li><a href="#editing-apis"><span class="secno">7.5.4 </span>Editing APIs</a></li>
-     <li><a href="#spelling-and-grammar-checking"><span class="secno">7.5.5 </span>Spelling and grammar checking</a></ol></li>
+     <li><a href="#best-practices-for-in-page-editors"><span class="secno">7.5.3 </span>Best practices for in-page editors</a></li>
+     <li><a href="#user-editing-actions"><span class="secno">7.5.4 </span>User editing actions</a></li>
+     <li><a href="#editing-apis"><span class="secno">7.5.5 </span>Editing APIs</a></li>
+     <li><a href="#spelling-and-grammar-checking"><span class="secno">7.5.6 </span>Spelling and grammar checking</a></ol></li>
    <li><a href="#dnd"><span class="secno">7.6 </span>Drag and drop</a>
     <ol>
      <li><a href="#introduction-7"><span class="secno">7.6.1 </span>Introduction</a></li>
@@ -33277,9 +33278,9 @@
   section 3.5</a>. <a href="#refsABNF">[ABNF]</a> <a href="#refsRFC5322">[RFC5322]</a> <a href="#refsRFC1034">[RFC1034]</a></p><p class="note">This requirement is a <a href="#willful-violation">willful violation</a>
   of RFC 5322, which defines a syntax for e-mail addresses that is
   simultaneously too strict (before the "@" character), too vague
-  (after the "@" character), and too lax (allowing comments, white
-  space characters, and quoted strings in manners unfamiliar to most
-  users) to be of practical use here.<p>A <dfn id="valid-e-mail-address-list">valid e-mail address list</dfn> is a <a href="#set-of-comma-separated-tokens">set of
+  (after the "@" character), and too lax (allowing comments,
+  whitespace characters, and quoted strings in manners unfamiliar to
+  most users) to be of practical use here.<p>A <dfn id="valid-e-mail-address-list">valid e-mail address list</dfn> is a <a href="#set-of-comma-separated-tokens">set of
   comma-separated tokens</a>, where each token is itself a
   <a href="#valid-e-mail-address">valid e-mail address</a>. <span class="impl">To obtain the
   list of tokens from a <a href="#valid-e-mail-address-list">valid e-mail address list</a>, and
@@ -52716,9 +52717,40 @@
   <p>The last state set must persist until the document is destroyed
   or the state is changed. Initially, documents must have their <code title="dom-document-designMode"><a href="#designMode">designMode</a></code> disabled.</p>
 
+  </div><h4 id="best-practices-for-in-page-editors"><span class="secno">7.5.3 </span>Best practices for in-page editors</h4><p>Authors are encouraged to set the 'white-space' property on <a href="#editing-host" title="editing host">editing hosts</a> and on markup that was
+  originally created through these editing mechanisms to the value
+  'pre-wrap'. Default HTML whitespace handling is not well suited to
+  WYSIWYG editing, and line wrapping will not work correctly in some
+  corner cases if 'white-space' is left at its default value.<div class="example">
+
+   <p>As an example of problems that occur if the default 'normal'
+   value is used instead, consider the case of the user typing
+   "<kbd>yellow&#9251;&#9251;ball</kbd>", with two spaces (here
+   represented by "2423;") between the words. With the editing
+   rules in place for the default value of 'white-space' ('normal'),
+   the resulting markup will either consist of
+   "<samp>yellow&amp;nbsp;&nbsp;ball</samp>" or
+   "<samp>yellow&nbsp;&amp;nbsp;ball</samp>"; i.e., there will be a
+   non-breaking space between the two words in addition to the regular
+   space. This is necessary because the 'normal' value for
+   'white-space' requires adjacent regular spaces to be collapsed
+   together.</p>
+
+   <p>In the former case, "<samp>yellow&#9085;</samp>" might wrap to
+   the next line ("&#9085;" being used here to represent a
+   non-breaking space) even though "<samp>yellow</samp>" alone might
+   fit at the end of the line; in the latter case,
+   "<samp>&#9085;ball</samp>", if wrapped to the start of the line,
+   would have visible indentation from the non-breaking space.</p>
+
+   <p>When 'white-space' is set to 'pre-wrap', however, the editing
+   rules will instead simply put two regular spaces between the words,
+   and should the two words be split at the end of a line, the spaces
+   would be neatly removed from the rendering.</p>
+
   </div><div class="impl">
 
-  <h4 id="user-editing-actions"><span class="secno">7.5.3 </span>User editing actions</h4>
+  <h4 id="user-editing-actions"><span class="secno">7.5.4 </span>User editing actions</h4>
 
   <p class="XXX">This section will be removed shortly. What remains
   here is simply what has not yet been merged into Aryeh's spec.</p>
@@ -52790,7 +52822,7 @@
   history</a> of the <a href="#editing-host">editing host</a>'s
   <code><a href="#document">Document</a></code> object each time an action is triggered.</p>
 
-  </div><h4 id="editing-apis"><span class="secno">7.5.4 </span>Editing APIs</h4><p>The definition of the terms <dfn id="active-range">active range</dfn>, <dfn id="editing-host">editing
+  </div><h4 id="editing-apis"><span class="secno">7.5.5 </span>Editing APIs</h4><p>The definition of the terms <dfn id="active-range">active range</dfn>, <dfn id="editing-host">editing
   host</dfn>, and <dfn id="editable">editable</dfn>, the user interface requirements
   of elements that are <a href="#editing-host" title="editing host">editing hosts</a>
   or <a href="#editable">editable</a>, and the
@@ -52807,7 +52839,7 @@
   interaction of editing and the undo/redo features in user agents is
   defined by the UndoManager and DOM Transaction specification. <a href="#refsEDITING">[EDITING]</a> <a href="#refsDOMRANGE">[DOMRANGE]</a> <a href="#refsUNDO">[UNDO]</a><p class="XXX">Need to decide what to do with the <dfn id="formatblock-candidate"><code title="">formatBlock</code> candidate</dfn> category.<p class="XXX"><dfn id="undo-transaction-history">undo transaction history</dfn> is currently
   defined in <a href="#refsUNDO">[UNDO]</a> but this spec hasn't been
-  updated to make sense with the new definition</p><h4 id="spelling-and-grammar-checking"><span class="secno">7.5.5 </span>Spelling and grammar checking</h4><div class="impl">
+  updated to make sense with the new definition</p><h4 id="spelling-and-grammar-checking"><span class="secno">7.5.6 </span>Spelling and grammar checking</h4><div class="impl">
 
   <p>User agents can support the checking of spelling and grammar of
   editable text, either in form controls (such as the value of

Received on Friday, 23 September 2011 00:17:25 UTC