Editorial rewrite of the radial gradient size/shape keywords section.

Author: tabatkins

css3-images/Overview.html

@@ -20,10 +20,10 @@
 
    <h1>CSS Image Values and Replaced Content Module Level 3</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 11 August 2011</h2>
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 12 August 2011</h2>
 
    <dl><!--<dt>This version:</dt>
-		<dd><a href="http://www.w3.org/TR/2011/ED-css3-images-20110811/">http://www.w3.org/TR/2011/ED-css3-images-20110811/</a>-->
+		<dd><a href="http://www.w3.org/TR/2011/ED-css3-images-20110812/">http://www.w3.org/TR/2011/ED-css3-images-20110812/</a>-->
 
     <dt>Latest version:
 
@@ -786,56 +786,78 @@ <h4 class=no-toc id=radial-gradient-syntax><span class=secno>5.2.1. </span>
      <em>implicitly</em> with a size and shape keyword. The <a
      href="#ltshape"><i>&lt;shape></i></a> is defined as</p>
 
-    <pre><code><dfn id=ltshape>&lt;shape></dfn> = [ circle | ellipse ]</code></pre>
+    <pre><code><dfn id=ltshape>&lt;shape></dfn> = circle | ellipse</code></pre>
 
     <p>&lsquo;<code class=css>circle</code>&rsquo; indicates that the
      ending-ellipse will be a circle with a constant radius. &lsquo;<code
      class=css>ellipse</code>&rsquo; indicates that the gradient-shape will
      be an axis-aligned ellipse (that is, its major and minor radiuses will
      be horizontal and vertical, not necessarily in that order).</p>
 
-    <p>The <a href="#ltsize"><i>&lt;size></i></a> keyword is defined as</p>
-
-    <pre><code><dfn id=ltsize>&lt;size></dfn> = [ closest-side | closest-corner | farthest-side | farthest-corner | contain | cover ]</code></pre>
-
-    <p>If <a href="#ltshape"><i>&lt;shape></i></a> is &lsquo;<code
-     class=css>circle</code>&rsquo; and <a
-     href="#ltsize"><i>&lt;size></i></a> is &lsquo;<code
-     class=css>closest-side</code>&rsquo;, the ending-shape is a circle sized
-     so that it exactly meets the side of the box closest to its center. For
-     example, if the box was 100px wide and 200px tall, and the center of the
-     gradient was &lsquo;<code class=css>10% 10%</code>&rsquo;, then the
-     closest side is the left side of the box (it is 10px from the
-     starting-point, while the top is 20px from it, and the right and bottom
-     sides are much further). The gradient-shape would thus be a circle with
-     a radius of 10px. If <a href="#ltshape"><i>&lt;shape></i></a> is
-     &lsquo;<code class=css>ellipse</code>&rsquo; and <a
-     href="#ltsize"><i>&lt;size></i></a> is &lsquo;<code
-     class=css>closest-side</code>&rsquo;, the gradient-shape is an ellipse
-     sized so that it exactly meets the vertical and horizontal sides of the
-     box closest to its center. Using the same box and starting-point as the
-     previous example, the gradient-shape would be an ellipse with a 20px
-     vertical radius and a 10px horizontal radius. (If necessary, such as if
-     the starting-point is outside of the box, extend the sides of the box so
-     that there is a line the ellipse can meet.)</p>
-
-    <p>&lsquo;<code class=css>farthest-side</code>&rsquo; is identical to
-     &lsquo;<code class=css>closest-side</code>&rsquo;, except that the
-     gradient-shape is sized to meet the side of the box that is farthest
-     from its center (or the farthest vertical and horizontal sides, if the
-     shape is &lsquo;<code class=css>ellipse</code>&rsquo;). &lsquo;<code
-     class=css>closest-corner</code>&rsquo; and &lsquo;<code
-     class=css>farthest-corner</code>&rsquo; size the gradient-shape so that
-     it exactly meets the closest or farthest corner of the box from its
-     center, respectively. If <a href="#ltshape"><i>&lt;shape></i></a> is
-     &lsquo;<code class=css>ellipse</code>&rsquo;, the gradient-shape has the
-     same ratio of width to height that it would if &lsquo;<code
-     class=css>closest-side</code>&rsquo; or &lsquo;<code
-     class=css>farthest-side</code>&rsquo; were specified, as appropriate.
-     &lsquo;<code class=css>contain</code>&rsquo; is a synonym for
-     &lsquo;<code class=css>closest-side</code>&rsquo;, and &lsquo;<code
-     class=css>cover</code>&rsquo; is a synonym for &lsquo;<code
-     class=css>farthest-corner</code>&rsquo;.</p>
+    <p>The <a href="#ltsize"><i>&lt;size></i></a> keyword is defined as:</p>
+
+    <pre><code><dfn id=ltsize>&lt;size></dfn> = closest-side | closest-corner | farthest-side | farthest-corner | contain | cover</code></pre>
+
+    <p>Its values are defined in the list below. For the purpose of these
+     definitions, consider the box edges as extending infinitely in both
+     directions, rather than being finite line segments.</p>
+
+    <dl>
+     <dt><dfn id=radial-closest-side>closest-side</dfn>
+
+     <dd>
+      <p>If the <a href="#ltshape"><i>&lt;shape></i></a> is &lsquo;<code
+       class=css>circle</code>&rsquo;, the ending-shape must be a circle
+       sized so that it exactly meets the closest side of the box.</p>
+
+      <p>If the <a href="#ltshape"><i>&lt;shape></i></a> is &lsquo;<code
+       class=css>ellipse</code>&rsquo;, the ending-shape must be an ellipse
+       sized so that it exactly meets the closest horizontal and vertical
+       sides of the box.</p>
+
+     <dt><dfn id=radial-farthest-side>farthest-side</dfn>
+
+     <dd>Same as &lsquo;<a href="#radial-closest-side"><code
+      class=css>closest-side</code></a>&rsquo;, except the ending-shape must
+      be sized based on the farthest side(s).
+
+     <dt><dfn id=radial-closest-corner>closest-corner</dfn>
+
+     <dd>
+      <p>If the <a href="#ltshape"><i>&lt;shape></i></a> is &lsquo;<code
+       class=css>circle</code>&rsquo;, the ending-shape must be a circle
+       sized so that it exactly meets the closest corner of the box.</p>
+
+      <p>If the <a href="#ltshape"><i>&lt;shape></i></a> is &lsquo;<code
+       class=css>ellipse</code>&rsquo;, the ending-shape must be an ellipse
+       with the same aspect-ratio it would have if &lsquo;<a
+       href="#radial-closest-side"><code
+       class=css>closest-side</code></a>&rsquo; were specified, but sized so
+       that it exactly meets the closest corner of the box.</p>
+
+     <dt><dfn id=radial-farthest-corner>farthest-corner</dfn>
+
+     <dd>Same as &lsquo;<a href="#radial-closest-corner"><code
+      class=css>closest-corner</code></a>&rsquo;, except the ending-shape
+      must be sized based on the farthest corner. If <a
+      href="#ltshape"><i>&lt;shape></i></a> is &lsquo;<code
+      class=css>ellipse</code>&rsquo;, the ending-shape must have the same
+      aspect ratio it would have if &lsquo;<a
+      href="#radial-farthest-side"><code
+      class=css>farthest-side</code></a>&rsquo; were specified.
+
+     <dt><dfn id=radial-contain>contain</dfn>
+
+     <dd>This value is an alias for &lsquo;<a
+      href="#radial-closest-side"><code
+      class=css>closest-side</code></a>&rsquo;, and has the same meaning.
+
+     <dt><dfn id=radial-cover>cover</dfn>
+
+     <dd>This value is an alias for &lsquo;<a
+      href="#radial-farthest-corner"><code
+      class=css>farthest-corner</code></a>&rsquo;, and has the same meaning.
+    </dl>
 
    <dt>Explicitly
 
@@ -850,12 +872,22 @@ <h4 class=no-toc id=radial-gradient-syntax><span class=secno>5.2.1. </span>
      box, while percentages used in the second value are relative to the
      height of the box.</p>
 
-    <p>Both of the values must be non-negative. Specifying either as
-     &lsquo;<code class=css>0</code>&rsquo; is allowed, but produces a
-     degenerate shape. The handling of degenerate ending-shapes is specified
-     later in this specification.</p>
+    <p>Negative lengths or percentages are a syntax error.</p>
   </dl>
 
+  <p>Some combinations of position, size, and shape will produce a <dfn
+   id=degenerate-shape>degenerate shape</dfn> - a circle or ellipse with a
+   radius of 0. This will occur if the position is on a box edge and the
+   second argument is &lsquo;<code class=css>circle
+   closest-side</code>&rsquo;, &lsquo;<code class=css>ellipse
+   closest-side</code>&rsquo;, or &lsquo;<code class=css>ellipse
+   closest-corner</code>&rsquo;, or if the position is on a box corner and
+   the shape is &lsquo;<a href="#radial-closest-corner"><code
+   class=css>closest-corner</code></a>&rsquo;, or if the size and shape are
+   given explicitly and either of the radiuses are &lsquo;<code
+   class=css>0</code>&rsquo;. In these instances, the the gradient represents
+   a solid-color image equal to the color of the last color-stop.
+
   <p>If this argument is omitted, it defaults to &lsquo;<code
    class=css>ellipse cover</code>&rsquo;.
 
@@ -864,16 +896,6 @@ <h4 class=no-toc id=radial-gradient-syntax><span class=secno>5.2.1. </span>
    &lsquo;<code class=css>radial-gradient(10% 10%, red, blue)</code>&rsquo;),
    it must be interpreted as a position.
 
-  <p>In certain circumstances the given parameters may define a degenerate
-   shape - a circle or ellipse with a radius of 0. In these instances the
-   gradient image is just a solid color equal to the color of the last
-   color-stop in the rule. The following combinations of values will trigger
-   this: &lsquo;<code class=css>closest-side</code>&rsquo; if the
-   starting-point is on a box edge, &lsquo;<code
-   class=css>closest-corner</code>&rsquo; if the starting-point is on a box
-   corner, and &lsquo;<code class=css>ellipse closest-corner</code>&rsquo; if
-   the starting-point is on a box edge.
-
   <p>Color-stops are placed on an imaginary line extending from the center of
    the gradient toward the right, with the 0% point at the center of the
    gradient, and 100% at the point where the line intersects the
@@ -930,8 +952,8 @@ <h4 class=no-toc id=radial-gradient-examples><span class=secno>5.2.2.
   </div>
 
   <div class=example>
-   <p>Here we illustrate a &lsquo;<code class=property>contain</code>&rsquo;
-    gradient.</p>
+   <p>Here we illustrate a &lsquo;<a href="#radial-contain"><code
+    class=property>contain</code></a>&rsquo; gradient.</p>
 
    <pre><code>radial-gradient(20px 30px, contain, red, yellow, green);
 radial-gradient(20px 30px, 20px 30px, red, yellow, green);</code></pre>
@@ -1560,13 +1582,15 @@ <h3 id=object-fit><span class=secno>6.4. </span> Sizing Objects: the
 
    <dd>
     <p>Size the content as if &lsquo;<code class=property>none</code>&rsquo;
-     or &lsquo;<code class=property>contain</code>&rsquo; were specified,
-     whichever would result in a smaller size.</p>
+     or &lsquo;<a href="#radial-contain"><code
+     class=property>contain</code></a>&rsquo; were specified, whichever would
+     result in a smaller size.</p>
 
     <p class=note>Note that both &lsquo;<code
-     class=property>none</code>&rsquo; and &lsquo;<code
-     class=property>contain</code>&rsquo; respect the content's intrinsic
-     aspect ratio, so the concept of "smaller" is well-defined.</p>
+     class=property>none</code>&rsquo; and &lsquo;<a
+     href="#radial-contain"><code class=property>contain</code></a>&rsquo;
+     respect the content's intrinsic aspect ratio, so the concept of
+     "smaller" is well-defined.</p>
   </dl>
 
   <p>If the content does not completely fill the replaced element, the
@@ -1588,7 +1612,8 @@ <h3 id=object-fit><span class=secno>6.4. </span> Sizing Objects: the
     for &lsquo;<a href="#object-position0"><code
     class=property>object-position</code></a>&rsquo;. The fifth value,
     &lsquo;<code class=css><span class=css>scale-down</span>, in this case
-    looks identical to </code>&rsquo;<span class=css>contain</span>.</p>
+    looks identical to </code>&rsquo;<a class=css
+    href="#radial-contain">contain</a>.</p>
   </div>
 
   <p class=note>Note: the &lsquo;<a href="#object-fit0"><code

css3-images/Overview.src.html

@@ -525,43 +525,46 @@ <h4 class='no-toc' id='radial-gradient-syntax'>
 			<em>implicitly</em> with a size and shape keyword.  The <i>&lt;shape></i> 
 			is defined as </p>
 
-			<pre><code><dfn>&lt;shape></dfn> = [ circle | ellipse ]</code></pre>
+			<pre><code><dfn>&lt;shape></dfn> = circle | ellipse</code></pre>
 
 			<p>''circle'' indicates that the ending-ellipse will be a circle with 
 			a constant radius.  ''ellipse'' indicates that the gradient-shape 
 			will be an axis-aligned ellipse (that is, its major and minor radiuses 
 			will be horizontal and vertical, not necessarily in that order).</p>
 
-			<p>The <i>&lt;size></i> keyword is defined as </p>
-
-			<pre><code><dfn>&lt;size></dfn> = [ closest-side | closest-corner | farthest-side | farthest-corner | contain | cover ]</code></pre>
-
-			<p>If <i>&lt;shape></i> is ''circle'' and <i>&lt;size></i> is ''closest-side'', 
-			the ending-shape is a circle sized so that it exactly meets the side 
-			of the box closest to its center.  For example, if the box was 100px 
-			wide and 200px tall, and the center of the gradient was ''10% 10%'', 
-			then the closest side is the left side of the box (it is 10px from 
-			the starting-point, while the top is 20px from it, and the right and 
-			bottom sides are much further).  The gradient-shape would thus be a 
-			circle with a radius of 10px.  If <i>&lt;shape></i> is ''ellipse'' and 
-			<i>&lt;size></i> is ''closest-side'', the gradient-shape is an ellipse 
-			sized so that it exactly meets the vertical and horizontal sides of 
-			the box closest to its center.  Using the same box and starting-point 
-			as the previous example, the gradient-shape would be an ellipse with 
-			a 20px vertical radius and a 10px horizontal radius.  (If necessary, 
-			such as if the starting-point is outside of the box, extend the sides 
-			of the box so that there is a line the ellipse can meet.)</p>
-
-			<p>''farthest-side'' is identical to ''closest-side'', except that 
-			the gradient-shape is sized to meet the side of the box that is farthest 
-			from its center (or the farthest vertical and horizontal sides, if 
-			the shape is ''ellipse'').  ''closest-corner'' and ''farthest-corner'' 
-			size the gradient-shape so that it exactly meets the closest or farthest 
-			corner of the box from its center, respectively.  If <i>&lt;shape></i>
-			is ''ellipse'', the gradient-shape has the same ratio of width to height 
-			that it would if ''closest-side'' or ''farthest-side'' were specified, 
-			as appropriate.  ''contain'' is a synonym for ''closest-side'', and 
-			''cover'' is a synonym for ''farthest-corner''.</p>
+			<p>The <i>&lt;size></i> keyword is defined as:</p>
+
+			<pre><code><dfn>&lt;size></dfn> = closest-side | closest-corner | farthest-side | farthest-corner | contain | cover</code></pre>
+
+			<p>Its values are defined in the list below.  For the purpose of these definitions, consider the box edges as extending infinitely in both directions, rather than being finite line segments.</p>
+
+			<dl>
+				<dt><dfn id='radial-closest-side'>closest-side</dfn></dt>
+				<dd>
+					<p>If the <i>&lt;shape></i> is ''circle'', the ending-shape must be a circle sized so that it exactly meets the closest side of the box.</p>
+
+					<p>If the <i>&lt;shape></i> is ''ellipse'', the ending-shape must be an ellipse sized so that it exactly meets the closest horizontal and vertical sides of the box.</p>
+				</dd>
+
+				<dt><dfn id='radial-farthest-side'>farthest-side</dfn></dt>
+				<dd>Same as ''closest-side'', except the ending-shape must be sized based on the farthest side(s).</dd>
+
+				<dt><dfn id='radial-closest-corner'>closest-corner</dfn></dt>
+				<dd>
+					<p>If the <i>&lt;shape></i> is ''circle'', the ending-shape must be a circle sized so that it exactly meets the closest corner of the box.</p>
+
+					<p>If the <i>&lt;shape></i> is ''ellipse'', the ending-shape must be an ellipse with the same aspect-ratio it would have if ''closest-side'' were specified, but sized so that it exactly meets the closest corner of the box.</p>
+				</dd>
+
+				<dt><dfn id='radial-farthest-corner'>farthest-corner</dfn></dt>
+				<dd>Same as ''closest-corner'', except the ending-shape must be sized based on the farthest corner.  If <i>&lt;shape></i> is ''ellipse'', the ending-shape must have the same aspect ratio it would have if ''farthest-side'' were specified.</dd>
+
+				<dt><dfn id='radial-contain'>contain</dfn></dt>
+				<dd>This value is an alias for ''closest-side'', and has the same meaning.</dd>
+
+				<dt><dfn id='radial-cover'>cover</dfn></dt>
+				<dd>This value is an alias for ''farthest-corner'', and has the same meaning.</dd>
+			</dl>
 		</dd>
 
 		<dt>Explicitly</dt>
@@ -577,26 +580,18 @@ <h4 class='no-toc' id='radial-gradient-syntax'>
 			the box, while percentages used in the second value are relative to 
 			the height of the box.</p>
 
-			<p>Both of the values must be non-negative.  Specifying either as
-			''0'' is allowed, but produces a degenerate shape.  The handling of
-			degenerate ending-shapes is specified later in this specification.</p>
+			<p>Negative lengths or percentages are a syntax error.</p>
 		</dd>
 	</dl>
 
+	<p>Some combinations of position, size, and shape will produce a <dfn>degenerate shape</dfn> - a circle or ellipse with a radius of 0.  This will occur if the position is on a box edge and the second argument is ''circle closest-side'', ''ellipse closest-side'', or ''ellipse closest-corner'', or if the position is on a box corner and the shape is ''closest-corner'', or if the size and shape are given explicitly and either of the radiuses are ''0''.  In these instances, the the gradient represents a solid-color image equal to the color of the last color-stop.</p>
+
 	<p>If this argument is omitted, it defaults to ''ellipse cover''.</p>
 
 	<p>If only one argument is provided before the color-stops, and it could
 	be interpreted as either a position or an explicit size (for example, in
 	''radial-gradient(10% 10%, red, blue)''), it must be interpreted as a position.</p>
 
-	<p>In certain circumstances the given parameters may define a degenerate 
-	shape - a circle or ellipse with a radius of 0. In these instances the 
-	gradient image is just a solid color equal to the color of the last color-stop 
-	in the rule.  The following combinations of values will trigger this: 
-	''closest-side'' if the starting-point is on a box edge, ''closest-corner'' 
-	if the starting-point is on a box corner, and ''ellipse closest-corner'' 
-	if the starting-point is on a box edge.</p>
-
 	<p>Color-stops are placed on an imaginary line extending from the center 
 	of the gradient toward the right, with the 0% point at the center of the 
 	gradient, and 100% at the point where the line intersects the ending-ellipse.  
@@ -705,7 +700,7 @@ <h3 id='repeating-gradients'>
 
 		<pre><code>repeating-radial-gradient(20px 30px, circle contain, red, yellow, green 100%, yellow 150%, red 200%)</code></pre>
 		<p><img src="repeating3.png" alt=""></p>
-	</div>
+		</div>
 
 	<p>If the distance between the first and last color-stops is non-zero, but is small enough that the implementation knows that the physical resolution of the output device is insufficient to faithfully render the gradient, the implementation must <i title="gradient-average-color">find the average color of the gradient</i> and render the gradient as a solid-color image equal to the average color.</p>