[css-will-change] Rearrange some examples and notes.

tabatkins · tabatkins · commit 0ce03df952bd · 2014-05-05T08:43:21.000-07:00
diff --git a/css-will-change/Overview.bs b/css-will-change/Overview.bs
@@ -57,6 +57,26 @@ Hinting at Future Behavior: the 'will-change' property</h2>
 	This allows the user agent to perform ahead-of-time any optimizations necessary for rendering those changes smoothly,
 	avoiding “jank” when the author does begin changing or animating that feature.
 
+	<div class='note'>
+		Different browsers can use the information from 'will-change' in different ways,
+		and even a single browser might use it in different ways at different time.
+		For example, a browser that promotes elements to their own “GPU layer”
+		when they have ''will-change: transform'' specified
+		might avoid doing that when there are <em>too many</em> elements declaring that,
+		to avoid exhausting GPU memory.
+
+		Authors should avoid overusing this property,
+		and shouldn't apply it to an element unless it is known (or expected)
+		that the element will change in the indicated way soon.
+		For example, applying 'will-change' to an element from a static CSS stylesheet
+		is probably an error;
+		most of the time,
+		'will-change' should be applied by scripting,
+		some time shortly before starting an animation or other change,
+		and should be promptly reset to its initial value of ''auto''
+		when the element stops changing.
+	</div>
+
 	Values have the following meanings:
 
 	<dl dfn-for="will-change" dfn-type="value">
@@ -101,6 +121,15 @@ Hinting at Future Behavior: the 'will-change' property</h2>
 			It is still <em>safe</em> to specify them, though;
 			it'll simply have no effect.
 
+			<p class='example'>
+				For example, browsers often handle elements with 'transform' set to a non-initial value very differently from normal elements,
+				perhaps rendering them to their own “GPU layer”
+				or using other mechanisms to make it easier to quickly make the sort of transformations that 'transform' can produce.
+				A browser might take a value of 'transform' as a signal
+				that it should go ahead and promote the element to its own layer immediately,
+				before the element starts to be transformed,
+				to avoid any delay involved in rerendering the old and new layers.
+
 			If any non-initial value of a property would create a stacking context on the element,
 			specifying that property in 'will-change' must create a stacking context on the element.
 
@@ -113,44 +142,13 @@ Hinting at Future Behavior: the 'will-change' property</h2>
 			to avoid sudden rendering differences when the property is eventually changed.
 
 			<p class='example'>
-				For example, browsers often handle elements with 'transform' set to a non-initial value very differently from normal elements,
-				perhaps rendering them to their own “GPU layer”
-				or using other mechanisms to make it easier to quickly make the sort of transformations that 'transform' can produce.
-				A browser might take a value of 'transform' as a signal
-				that it should go ahead and promote the element to its own layer immediately,
-				before the element starts to be transformed,
-				to avoid any delay involved in rerendering the old and new layers.
+				For example, setting 'opacity' to any value other than ''1'' creates a stacking context on the element.
+				Thus, setting ''will-change: opacity'' also creates a stacking context,
+				even if 'opacity' is <em>currently</em> still equal to ''1''.
 	</dl>
 
-
-	<div class='example'>
-		For example, setting 'opacity' to any value other than ''1'' creates a stacking context on the element.
-		Thus, setting ''will-change: opacity'' also creates a stacking context,
-		even if 'opacity' is <em>currently</em> still equal to ''1''.
-	</div>
-
 	The 'will-change' property has no <em>direct</em> effect on the element it is specified on,
 	beyond the creation of stacking contexts and containing blocks as specified above.
 	It is solely a rendering hint to the user agent,
 	allowing it set up potentially-expensive optimizations for certain types of changes
 	before the changes actually start occurring.
-
-	<div class='note'>
-		Different browsers can use the information from 'will-change' in different ways,
-		and even a single browser might use it in different ways at different time.
-		For example, a browser that promotes elements to their own “GPU layer”
-		when they have ''will-change: transform'' specified
-		might avoid doing that when there are <em>too many</em> elements declaring that,
-		to avoid exhausting GPU memory.
-
-		Authors should avoid overusing this property,
-		and shouldn't apply it to an element unless it is known (or expected)
-		that the element will change in the indicated way soon.
-		For example, applying 'will-change' to an element from a static CSS stylesheet
-		is probably an error;
-		most of the time,
-		'will-change' should be applied by scripting,
-		some time shortly before starting an animation or other change,
-		and should be promptly reset to its initial value of ''auto''
-		when the element stops changing.
-	</div>
diff --git a/css-will-change/Overview.html b/css-will-change/Overview.html
@@ -13,8 +13,8 @@
 </p>
   <h1 class="p-name no-ref" id=title>CSS Will Change Module Level 1</h1>
   <h2 class="no-num no-toc no-ref heading settled heading" id=subtitle><span class=content>W3C First Public Working Draft,
-    <span class=dt-updated><span class=value-title title=20140422>22 April 2014</span></span></span></h2>
-  <div data-fill-with=spec-metadata><dl><dt>This version:<dd><a class=u-url href=http://www.w3.org/TR/2014/WD-css-will-change-1-20140422/>http://www.w3.org/TR/2014/WD-css-will-change-1-20140422/</a><dt>Latest version:<dd><a href=http://www.w3.org/TR/css-will-change/>http://www.w3.org/TR/css-will-change/</a><dt>Editor’s Draft:<dd><a href=http://dev.w3.org/csswg/css-will-change/>http://dev.w3.org/csswg/css-will-change/</a>
+    <span class=dt-updated><span class=value-title title=20140505>5 May 2014</span></span></span></h2>
+  <div data-fill-with=spec-metadata><dl><dt>This version:<dd><a class=u-url href=http://www.w3.org/TR/2014/WD-css-will-change-1-20140505/>http://www.w3.org/TR/2014/WD-css-will-change-1-20140505/</a><dt>Latest version:<dd><a href=http://www.w3.org/TR/css-will-change/>http://www.w3.org/TR/css-will-change/</a><dt>Editor’s Draft:<dd><a href=http://dev.w3.org/csswg/css-will-change/>http://dev.w3.org/csswg/css-will-change/</a>
     <dt>Feedback:</dt>
         <dd><a href="mailto:www-style@w3.org?subject=%5Bcss-will-change%5D%20feedback">www-style@w3.org</a>
             with subject line
@@ -90,7 +90,7 @@ <h2 class="no-num no-toc no-ref heading settled heading" id=contents><span class
 <h2 class="heading settled heading" data-level=1 id=intro><span class=secno>1 </span><span class=content>
 Introduction</span><a class=self-link href=#intro></a></h2>
 
-<p>	Modern CSS renderers perform a number of complex optimizations in order to render webpages quickly and efficiently.
+<p>Modern CSS renderers perform a number of complex optimizations in order to render webpages quickly and efficiently.
 	Unfortunately, employing these optimizations often has a non-trivial start-up cost,
 	which can have a negative impact on the responsiveness of a page.
 
@@ -102,11 +102,11 @@ <h2 class="heading settled heading" data-level=1 id=intro><span class=secno>1 </
 		if the element’s transform is the only thing that changes between frames,
 		and often provides significant speed benefits.
 
-<p>		However, setting up the element in a fresh layer is a relatively expensive operation,
+<p>However, setting up the element in a fresh layer is a relatively expensive operation,
 		which can delay the start of a <a class=property data-link-type=propdesc href=http://www.w3.org/TR/css3-transforms/#propdef-transform title=transform>transform</a> animation by a noticeable fraction of a second.
 	</div>
 
-<p>	The <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> property defined in this specification allows an author to declare ahead-of-time what properties are likely to change in the future,
+<p>The <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> property defined in this specification allows an author to declare ahead-of-time what properties are likely to change in the future,
 	so the UA can set up the appropriate optimizations some time before they’re needed.
 	This way, when the actual change happens,
 	the page updates in a snappy manner.
@@ -116,12 +116,32 @@ <h2 class="heading settled heading" data-level=2 id=will-change><span class=secn
 
 <table class="definition propdef"><tr><th>Name:<td><dfn class=css-code data-dfn-type=property data-export="" id=propdef-will-change>will-change<a class=self-link href=#propdef-will-change></a></dfn><tr><th>Value:<td class=prod>auto | <a class="production css-code" data-link-type=type href=#typedef-animateable-feature title="<animateable-feature>">&lt;animateable-feature&gt;</a>#<tr><th>Initial:<td>auto<tr><th>Applies to:<td>all elements<tr><th>Inherited:<td>no<tr><th>Media:<td>all<tr><th>Computed value:<td>specified value<tr><th>Percentages:<td>n/a</table>
 <pre class=prod><dfn class=css-code data-dfn-type=type data-export="" id=typedef-animateable-feature>&lt;animateable-feature&gt;<a class=self-link href=#typedef-animateable-feature></a></dfn> = scroll-position | contents | <a class="production css-code" data-link-type=type href=http://www.w3.org/TR/css3-values/#identifier-value title="<custom-ident>">&lt;custom-ident&gt;</a></pre>
-<p>	The <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> property provides a rendering hint to the user agent,
+<p>The <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> property provides a rendering hint to the user agent,
 	stating what kinds of changes the author expects to perform on the element.
 	This allows the user agent to perform ahead-of-time any optimizations necessary for rendering those changes smoothly,
 	avoiding “jank” when the author does begin changing or animating that feature.
 
-<p>	Values have the following meanings:
+	<div class=note>
+		Different browsers can use the information from <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> in different ways,
+		and even a single browser might use it in different ways at different time.
+		For example, a browser that promotes elements to their own “GPU layer”
+		when they have <a class=css data-link-type=propdesc href=#propdef-will-change title=will-change>will-change: transform</a> specified
+		might avoid doing that when there are <em>too many</em> elements declaring that,
+		to avoid exhausting GPU memory.
+
+<p>Authors should avoid overusing this property,
+		and shouldn’t apply it to an element unless it is known (or expected)
+		that the element will change in the indicated way soon.
+		For example, applying <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> to an element from a static CSS stylesheet
+		is probably an error;
+		most of the time,
+		<a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> should be applied by scripting,
+		some time shortly before starting an animation or other change,
+		and should be promptly reset to its initial value of <a class=css data-link-type=maybe href=#valuedef-auto title=auto>auto</a>
+		when the element stops changing.
+	</div>
+
+<p>Values have the following meanings:
 
 	<dl data-dfn-for=will-change data-dfn-type=value>
 		<dt><dfn class=css-code data-dfn-for=will-change data-dfn-type=value data-export="" id=valuedef-auto>auto<a class=self-link href=#valuedef-auto></a></dfn>
@@ -157,25 +177,14 @@ <h2 class="heading settled heading" data-level=2 id=will-change><span class=secn
 		<dd>
 			Indicates that the author expects to animate or change the property with the given name on the element in the near future.
 
-<p>			The <a class="production css-code" data-link-type=type href=http://www.w3.org/TR/css3-values/#identifier-value title="<custom-ident>">&lt;custom-ident&gt;</a> production used here excludes the keywords <span class=css data-link-type=maybe title=will-change>will-change</span>, <span class=css data-link-type=maybe title=none>none</span>, <span class=css data-link-type=maybe title=all>all</span>, <a class=css data-link-type=maybe href=#valuedef-auto title=auto>auto</a>, <a class=css data-link-type=maybe href=#valuedef-scroll-position title=scroll-position>scroll-position</a>, and <a class=css data-link-type=maybe href=#valuedef-contents title=contents>contents</a>,
+<p>The <a class="production css-code" data-link-type=type href=http://www.w3.org/TR/css3-values/#identifier-value title="<custom-ident>">&lt;custom-ident&gt;</a> production used here excludes the keywords <span class=css data-link-type=maybe title=will-change>will-change</span>, <span class=css data-link-type=maybe title=none>none</span>, <span class=css data-link-type=maybe title=all>all</span>, <a class=css data-link-type=maybe href=#valuedef-auto title=auto>auto</a>, <a class=css data-link-type=maybe href=#valuedef-scroll-position title=scroll-position>scroll-position</a>, and <a class=css data-link-type=maybe href=#valuedef-contents title=contents>contents</a>,
 			in addition to the keywords normally excluded from <a class="production css-code" data-link-type=type href=http://www.w3.org/TR/css3-values/#identifier-value title="<custom-ident>">&lt;custom-ident&gt;</a>.
 
-<p class=note>			Note: Note that most properties will have no effect when specified,
+<p class=note>Note: Note that most properties will have no effect when specified,
 			as the user agent doesn’t perform any special optimizations for changes in most properties.
 			It is still <em>safe</em> to specify them, though;
 			it’ll simply have no effect.
 
-<p>			If any non-initial value of a property would create a stacking context on the element,
-			specifying that property in <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> must create a stacking context on the element.
-
-<p>			If any non-initial value of a property would cause the element to generate a containing block for fixed-position elements,
-			specifying that property in <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> must cause the element to generate a containing block for fixed-position elements.
-
-<p>			If a non-initial value of a property would cause rendering differences on the element
-			(such as using a different anti-aliasing strategy for text),
-			the user agent should use that alternate rendering when the property is specified in <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a>,
-			to avoid sudden rendering differences when the property is eventually changed.
-
 			<p class=example>
 				For example, browsers often handle elements with <a class=property data-link-type=propdesc href=http://www.w3.org/TR/css3-transforms/#propdef-transform title=transform>transform</a> set to a non-initial value very differently from normal elements,
 				perhaps rendering them to their own “GPU layer”
@@ -184,41 +193,30 @@ <h2 class="heading settled heading" data-level=2 id=will-change><span class=secn
 				that it should go ahead and promote the element to its own layer immediately,
 				before the element starts to be transformed,
 				to avoid any delay involved in rerendering the old and new layers.
-	</dl>
 
+<p>If any non-initial value of a property would create a stacking context on the element,
+			specifying that property in <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> must create a stacking context on the element.
+
+<p>If any non-initial value of a property would cause the element to generate a containing block for fixed-position elements,
+			specifying that property in <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> must cause the element to generate a containing block for fixed-position elements.
 
-	<div class=example>
-		For example, setting <a class=property data-link-type=propdesc href=http://www.w3.org/TR/css3-color/#opacity title=opacity>opacity</a> to any value other than <span class=css data-link-type=maybe title=1>1</span> creates a stacking context on the element.
-		Thus, setting <a class=css data-link-type=propdesc href=#propdef-will-change title=will-change>will-change: opacity</a> also creates a stacking context,
-		even if <a class=property data-link-type=propdesc href=http://www.w3.org/TR/css3-color/#opacity title=opacity>opacity</a> is <em>currently</em> still equal to <span class=css data-link-type=maybe title=1>1</span>.
-	</div>
+<p>If a non-initial value of a property would cause rendering differences on the element
+			(such as using a different anti-aliasing strategy for text),
+			the user agent should use that alternate rendering when the property is specified in <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a>,
+			to avoid sudden rendering differences when the property is eventually changed.
 
-<p>	The <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> property has no <em>direct</em> effect on the element it is specified on,
+			<p class=example>
+				For example, setting <a class=property data-link-type=propdesc href=http://www.w3.org/TR/css3-color/#opacity title=opacity>opacity</a> to any value other than <span class=css data-link-type=maybe title=1>1</span> creates a stacking context on the element.
+				Thus, setting <a class=css data-link-type=propdesc href=#propdef-will-change title=will-change>will-change: opacity</a> also creates a stacking context,
+				even if <a class=property data-link-type=propdesc href=http://www.w3.org/TR/css3-color/#opacity title=opacity>opacity</a> is <em>currently</em> still equal to <span class=css data-link-type=maybe title=1>1</span>.
+	</dl>
+
+<p>The <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> property has no <em>direct</em> effect on the element it is specified on,
 	beyond the creation of stacking contexts and containing blocks as specified above.
 	It is solely a rendering hint to the user agent,
 	allowing it set up potentially-expensive optimizations for certain types of changes
 	before the changes actually start occurring.
 
-	<div class=note>
-		Different browsers can use the information from <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> in different ways,
-		and even a single browser might use it in different ways at different time.
-		For example, a browser that promotes elements to their own “GPU layer”
-		when they have <a class=css data-link-type=propdesc href=#propdef-will-change title=will-change>will-change: transform</a> specified
-		might avoid doing that when there are <em>too many</em> elements declaring that,
-		to avoid exhausting GPU memory.
-
-<p>		Authors should avoid overusing this property,
-		and shouldn’t apply it to an element unless it is known (or expected)
-		that the element will change in the indicated way soon.
-		For example, applying <a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> to an element from a static CSS stylesheet
-		is probably an error;
-		most of the time,
-		<a class=property data-link-type=propdesc href=#propdef-will-change title=will-change>will-change</a> should be applied by scripting,
-		some time shortly before starting an animation or other change,
-		and should be promptly reset to its initial value of <a class=css data-link-type=maybe href=#valuedef-auto title=auto>auto</a>
-		when the element stops changing.
-	</div>
-
 <h2 class="no-ref no-num heading settled heading" id=conformance><span class=content>
 Conformance</span><a class=self-link href=#conformance></a></h2>
 
