Cleaned up and better specified the element() section.

Author: tabatkins

css3-images/Overview.html

@@ -19,12 +19,12 @@
 
    <h1>CSS Image Values and Replaced Content Module Level 3</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 14 December
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 15 December
     2010</h2>
 
    <dl>
     <dt>This version:</dt>
-    <!-- <dd><a href="http://www.w3.org/TR/2010/CR-css3-images-20101214/">http://www.w3.org/TR/2010/CR-css3-images-20101214/</a></dd> -->
+    <!-- <dd><a href="http://www.w3.org/TR/2010/CR-css3-images-20101215/">http://www.w3.org/TR/2010/CR-css3-images-20101215/</a></dd> -->
 
     <dd><a
      href="http://dev.w3.org/csswg/css3-images/">http://dev.w3.org/csswg/css3-images/</a>
@@ -482,36 +482,65 @@ <h3 id=element-reference><span class=secno>4.3. </span>Using Elements as
      function is an ID selector, the function references the element matched
      by the selector. If it's an identifier, the function references the
      element who's <dfn id=css-element-reference-identifier>CSS element
-     reference identifier</dfn> is the identifier. (CSS does not define how
-     an element acquires a &lsquo;<a
+     reference identifier</dfn> is the given identifier. (CSS does not define
+     how an element acquires a &lsquo;<a
      href="#css-element-reference-identifier"><code class=css>CSS element
      reference identifier</code></a>&rsquo;; that is determined by the host
      language.) If no element in the document matches the selector, or no
      element has the identifier as its &lsquo;<a
      href="#css-element-reference-identifier"><code class=css>CSS element
      reference identifier</code></a>&rsquo;, the function represents a fully
      transparent image with no intrinsic dimensions, equivalent to
-     <code>image(transparent)</code>. Otherwise, the function represents an
-     image with width and height equal to the width and height of the
-     referenced element, with an appearance exactly equivalent to that of the
-     referenced element. Whether or not the referenced element is currently
-     being rendered on-screen, for media types where this is relevant, must
-     not affect the appearance of the image represented by the function; the
-     image must always be equivalent to how the element would appear when
-     rendered on-screen. If the document changes so that which element is
-     matched, or whether an element is matched at all, changes, the image
-     represented by the function must change accordingly.</p>
+     <code>image(transparent)</code>. If the document changes so that which
+     element is matched, or whether an element is matched at all, changes,
+     the image represented by the function must change accordingly.</p>
+
+    <p>If the &lsquo;<code class=css>element()</code>&rsquo; function refers
+     to an element, then it represents an image with width and height equal
+     to the width and height of the margin box of the referenced element. The
+     image must be constructed by rendering the referenced element and its
+     descendants at the same size that the element would be in its document,
+     over an infinite transparent black background, positioned so that the
+     edges of the margin box of the element is flush with the edges of the
+     image. <span class=note>If the element has decorations or descendants
+     that extend outside the margin box, these will be clipped to the margin
+     box in the generated image by default. &lsquo;<code
+     class=css>background-repeat:extend</code>&rsquo; may allow the author to
+     override this behavior so that decorations and descendants outside the
+     margin box are still painted.</span> If the referenced element or an
+     ancestor of the referenced element has a transform applied to it, the
+     transform must be ignored for the purpose of constructing this image
+     (transforms on descendants must be unaffected).</p>
 
     <p>If the argument passed to &lsquo;<code
      class=css>element()</code>&rsquo; isn't an ID selector or an ident, it
      is a syntax error.</p>
 
     <div class=example> TODO: copy an example from the MozHacks article</div>
 
-    <div class=issue> This can pretty obviously result in dependency cycles.
-     An element can try to use itself as a background, for example. I need to
-     add a section about determining the dependency graph and what to do when
-     a cycle is detected.</div>
+    <div>
+     <h4 class="no-num no-toc" id=element-cycles>Detecting and Resolving
+      Circular Relationships Introduced by &lsquo;<code
+      class=css>element()</code>&rsquo;</h4>
+
+     <p>The &lsquo;<code class=css>element()</code>&rsquo; function can
+      produce nonsensical circular relationships, such as an element using
+      itself as its own background. These relationships can be easily and
+      reliably detected and resolved, however, by keeping track of a
+      dependency graph and using common cycle-detection algorithms.</p>
+
+     <p>Populate the dependency graph initially by having every element
+      depend on each of its children. Then, whenever a property on an element
+      A uses the &lsquo;<code class=css>element()</code>&rsquo; function to
+      refer to an element B, add an edge to the graph by having A depend on
+      B. If a dependency cycle is detected, any &lsquo;<code
+      class=css>element()</code>&rsquo; functions that produced a dependency
+      in the cycle represent a fully transparent image with no intrinsic
+      dimensions.</p>
+
+     <p class=issue>Someone else needs to review this and make sure that I'm
+      not missing any cycles.</p>
+    </div>
    </div>
 
    <div>

css3-images/Overview.src.html

@@ -231,13 +231,17 @@ <h3 id=element-reference>Using Elements as Images: The ''element()'' notation</h
 		<p>The ''element()'' function allows an author to reference an element in the document that should be used as an image.  As the referenced element changes, for example, by the user typing into a &lt;textarea> element or a script drawing into a &lt;canvas> element in HTML, the image produced by the ''element()'' function stays in sync, allowing dynamic effects such as script-animated background images or previews of the next slide in a slideshow.  The syntax for ''element()'' is defined as:</p>
 		<pre class=prod><dfn>&lt;element-reference></dfn> = element( [&lt;id-selector> | &lt;identifier> ] )</pre>
 		<p>where &lt;id-selector> is an ID selector [[!SELECT]], and &lt;identifier> is an identifer [[!CSS3VAL]].</p>
-		<p>If the argument to the ''element()'' function is an ID selector, the function references the element matched by the selector.  If it's an identifier, the function references the element who's <dfn>CSS element reference identifier</dfn> is the identifier.  (CSS does not define how an element acquires a ''CSS element reference identifier''; that is determined by the host language.)  If no element in the document matches the selector, or no element has the identifier as its ''CSS element reference identifier'', the function represents a fully transparent image with no intrinsic dimensions, equivalent to <code>image(transparent)</code>.  Otherwise, the function represents an image with width and height equal to the width and height of the referenced element, with an appearance exactly equivalent to that of the referenced element.  Whether or not the referenced element is currently being rendered on-screen, for media types where this is relevant, must not affect the appearance of the image represented by the function; the image must always be equivalent to how the element would appear when rendered on-screen.  If the document changes so that which element is matched, or whether an element is matched at all, changes, the image represented by the function must change accordingly.</p>
+		<p>If the argument to the ''element()'' function is an ID selector, the function references the element matched by the selector.  If it's an identifier, the function references the element who's <dfn>CSS element reference identifier</dfn> is the given identifier.  (CSS does not define how an element acquires a ''CSS element reference identifier''; that is determined by the host language.)  If no element in the document matches the selector, or no element has the identifier as its ''CSS element reference identifier'', the function represents a fully transparent image with no intrinsic dimensions, equivalent to <code>image(transparent)</code>.  If the document changes so that which element is matched, or whether an element is matched at all, changes, the image represented by the function must change accordingly.</p>
+		<p>If the ''element()'' function refers to an element, then it represents an image with width and height equal to the width and height of the margin box of the referenced element.  The image must be constructed by rendering the referenced element and its descendants at the same size that the element would be in its document, over an infinite transparent black background, positioned so that the edges of the margin box of the element is flush with the edges of the image.  <span class=note>If the element has decorations or descendants that extend outside the margin box, these will be clipped to the margin box in the generated image by default.  ''background-repeat:extend'' may allow the author to override this behavior so that decorations and descendants outside the margin box are still painted.</span>  If the referenced element or an ancestor of the referenced element has a transform applied to it, the transform must be ignored for the purpose of constructing this image (transforms on descendants must be unaffected).</p>
 		<p>If the argument passed to ''element()'' isn't an ID selector or an ident, it is a syntax error.</p>
 		<div class=example>
 			TODO: copy an example from the MozHacks article
 		</div>
-		<div class=issue>
-			This can pretty obviously result in dependency cycles.  An element can try to use itself as a background, for example.  I need to add a section about determining the dependency graph and what to do when a cycle is detected.
+		<div>
+			<h4 class="no-num no-toc" id=element-cycles>Detecting and Resolving Circular Relationships Introduced by ''element()''</h4>
+			<p>The ''element()'' function can produce nonsensical circular relationships, such as an element using itself as its own background.  These relationships can be easily and reliably detected and resolved, however, by keeping track of a dependency graph and using common cycle-detection algorithms.</p>
+			<p>Populate the dependency graph initially by having every element depend on each of its children.  Then, whenever a property on an element A uses the ''element()'' function to refer to an element B, add an edge to the graph by having A depend on B.  If a dependency cycle is detected, any ''element()'' functions that produced a dependency in the cycle represent a fully transparent image with no intrinsic dimensions.</p>
+			<p class=issue>Someone else needs to review this and make sure that I'm not missing any cycles.</p>
 		</div>
 	</div>