Renamed regionOverflow to regionOverset. Added state diagram for NamedFlow state and added more precise wording on getFlowByName following bug https://www.w3.org/Bugs/Public/show_bug.cgi?id=14948

--HG--
extra : rebase_source : 6ea009a2caf0ab935c4d2b41902f6f2b202665a0

Author: vhardy

css3-regions/Overview.src.html

@@ -1237,7 +1237,7 @@ <h3 id="the-region-overflow-property">The region-overflow property</h3>
         "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15832">Bug-15832</a>
 
         <div class="issue-details">
-            <p class="short-desc">Should we have region-overflow:nobreak and have region-overflow apply to all regions, not just the last?</p>
+            <p class="short-desc">Should we have region-overflow:nobreak and have 'region-overflow' apply to all regions, not just the last?</p>
         </div>
     </div>
 
@@ -1686,6 +1686,19 @@ <h2 id="cssom_view_and_css_regions">CSSOM view and CSS regions</h2>
     </div>
 
     <h3 id="the-namedflow-interface">The NamedFlow interface</h3>
+    
+    <p>A <span>named flow</span> is created when it becomes referenced by the 
+        'flow-into' and 'flow-from' computed values. The following APIs also allow
+        scripts to reference a <code class="idl">NamedFlow</code> object representation
+        of a <span>named flow</span>.</p>
+        
+    <p>The possible states for a <span>named flow</span> are described in the following 
+        figure and referenced in subsequent text.</p>
+        
+    <div class="figure">
+        <img src="images/named-flow-states.svg" alt="NamedFlow states" width="600px" />
+        <p class="caption"><span>named flow</span> states and transitions</p>
+    </div>
 
     <div class="issue-marker" data-bug_id="14948" data-bug_status="NEW">
         <a href=
@@ -1704,22 +1717,44 @@ <h3 id="the-namedflow-interface">The NamedFlow interface</h3>
     <pre class="idl">
 partial interface <a href=
 "http://www.w3.org/TR/dom/#interface-document">Document</a> {
-  <a href="#dom-namedflow">NamedFlow</a> getFlowByName(DOMString name);
-  <a href="#dom-namedflow-collection">NamedFlowCollection</a> getNamedFlows();
+  <a href="#dom-namedflow">NamedFlow?</a> getFlowByName(DOMString name);
+  readonly attribute <a href="#dom-namedflow-collection">NamedFlowCollection</a> namedFlows;
 };               
 </pre>
 
-    <p>The <code class="idl">getNamedFlows</code> method on the <a href=
+    <p>The <code class="idl">namedFlows</code> attribute on the <a href=
     "http://www.w3.org/TR/dom/#interface-document"><code class=
-    "idl">Document</code></a> interface returns the list of all the <span>named
+    "idl">Document</code></a> interface returns the live list of all the current <span>named
     flow</span>s in the document.</p>
 
+    <p>The <code class="idl">namedFlows</code> collection must include all <span>named flow</span> 
+    that are currently in the <code>CREATED</code> and <code>CREATED-REFERENCED</code>state. 
+    The list may include <span>named flows</span>
+    that are in the <code>REFERENCED</code> state. The list
+    may also include <span>named flow</code> instances that are in the STALE state.</p>
+    
     <p>The <code class="idl">getFlowByName</code> method on the <a href=
     "http://www.w3.org/TR/dom/#interface-document"><code class=
     "idl">Document</code></a> interface provides access to the document's <span
-    >named flow</span> instances.</p>
+    >named flow</span> instances. The return value depends on the <span>named flow</span>
+    state:</p>
+    
+    <ul>
+        <li><code class="idl">NULL</code>: the user agent must return <code>null</code></li> 
+        <li><code class="idl">STALE</code> the user agent may return null or a valid 
+            <code class="idl">NamedFlow</code> instance. 
+            If the user agent returns a valid instance, subsequent calls to the <code class="idl">getFlowByName</code> method
+            must return the same object instance, no matter what the state of the 
+            <span>named flow</span> is.</li>
+        <li><code class="idl">CREATED</code> or <code class="idl">CREATED-REFERENCED</code>: the 
+            user agent must return a valid <code class="idl">NamedFlow</code> instance.</li>
+        <li><code class="idl">REFERENCED</code>: the user agent may return <code>null</code> or it may return a 
+            valid <code class="idl">NamedFlow</code> instance. If the user agent returns a 
+            valid object, subsequent calls to the <code class="idl">getFlowByName</code> method
+            must return the same object instance, no matter what the state of the 
+            <span>named flow</span> is.</li>
+    </ul>
 
-
     <div class="issue-marker" data-bug_id="15828" data-bug_status="NEW">
         <a href=
         "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15828">Bug-15828</a>
@@ -1806,33 +1841,35 @@ <h3 id="extension-to-the-element-interface">Extension to the Element
     <pre class="idl">
 partial interface <a href=
 "http://www.w3.org/TR/dom/#interface-element">Element</a> {
-    readonly attribute DOMString <a href="#dom-element-regionoverflow">regionOverflow</a>;
+    readonly attribute DOMString <a href="#dom-element-regionoverset">regionOverset</a>;
     sequence&lt;<a href="#">Range</a>&gt; <a href=
 "#dom-element-getregionflowranges">getRegionFlowRanges()</a>;
 };               
 
 </pre>
 
-    <p>The <dfn id="dom-element-regionoverflow"><code class=
-    "idl">regionOverflow</code></dfn> attribute returns one of the following
+    <p>The <dfn id="dom-element-regionoverset"><code class=
+    "idl">regionOverset</code></dfn> attribute returns one of the following
     values:</p>
 
     <dl>
-        <dt>'overflow'</dt>
+        <dt>'overset'</dt>
 
         <dd>the region is the last one in the 
         <span title="region-chain">region chain</span> and
         not able to fit the remaining content from the <span>named flow</span>.
         Note that the region's <a href=
         "http://www.w3.org/TR/CSS21/visufx.html#overflow"><code class=
         "idl">overflow</code></a> property value can be used to control the
-        visibility of the overflowing content. </dd>
+        visibility of the overflowing content and the 
+        'region-overflow' property controls whether or not fragmentation happens 
+        on the content that flows in the last region.</dd>
 
         <dt>'fit'</dt>
 
-        <dd>the region element's content fits into the region's <a href=
+        <dd>the region element's flow fragment content fits into the region's <a href=
         "http://www.w3.org/TR/CSS21/box.html#box-dimensions">content box</a>.
-        It does not overflow. If the region is the last one in the <span title=
+        If the region is the last one in the <span title=
         "region-chain">region chain</span>, it means that the content fits
         without overflowing. If the region is not the last one in the region
         chain, that means the <span>named flow</span>
@@ -1846,9 +1883,6 @@ <h3 id="extension-to-the-element-interface">Extension to the Element
         <dd>the region element has no content and is empty. All content from
         the <span>named flow</span> was fitted in regions
         with a lower document order.</dd>
-        
-        <dt>'undefined'</dt>
-        <dd>The element is not a <span>region</span>.</dd>
     </dl>
 
     <p>Note that if there is no content in the named flow, all regions associated
@@ -1969,6 +2003,9 @@ <h3 id="changes_from_June_09_2011">Changes from <a href="http://www.w3.org/TR/20
         <li>Fixed DOM references to now point to the DOM TR</li>
         <li>Fixed Web IDL issues as reported in <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15931">Issue 15931</a></li>
         <li>Added text to explain support for multi-column elements as required by <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15191">Issue 15191</a> and <a href="http://www.w3.org/Style/CSS/Tracker/actions/375">Action 375</a>.</li>
+        <li>Renamed 'regionOverflow' to 'regionOverset' to avoid confusion between fitting a flow in 
+            regions and the concept of visual overflow that the word 'overflow' (and the property) carry.</li>
+        <li>Reworked the partial document interface following the <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14948">Issue 14948</a> on <code>getFlowByName</code>.</li>
     </ul>