Actually commit the changes from last night, rewriting the image() section.

Author: tabatkins

css3-images/Overview.src.html

@@ -197,48 +197,62 @@ <h3 id="url">
 <!-- ====================================================================== -->
 
 <h3 id="image-notation">
-Image Fallbacks: the ''image()'' notation</h3>
-
-	<p>The ''image()'' notation allows an author to specify multiple images,
-	each one a fallback for the previous. The UA must use only the first image
-	that it can load and display. The syntax for ''image()'' is defined as
-
-	<pre class="prod"><dfn>&lt;image-list></dfn> = 
-image( [ &lt;image-decl&gt; , ]* [ &lt;image-decl&gt; | &lt;color> | &lt;element-reference> | &lt;image-combination> | &lt;gradient> ] )</pre>
-
-	<p>where &lt;image-decl&gt; is given by
-
-	<pre class="prod"><dfn>&lt;image-decl></dfn> = 
-[ &lt;string&gt; | &lt;url-token&gt; ] [ snap? &amp;&amp; &lt;resolution&gt; ]?</pre>
-
-	<p>&lt;url-token&gt; is given as <code>[!#$%&amp;*-~]|{nonascii}|{escape}</code>
-	(i.e. the contents of ''url()'') using the productions in the
-	<a href="http://www.w3.org/TR/CSS21/syndata.html#tokenization">CSS2.1 tokenization</a>.
-	<strong>The &lt;url-token&gt; must not contain unescaped brackets, commas,
-	white space characters, single quotes (&#39;) or double quotes (&quot;);
-	if it does the ''image()'' containing it is invalid.</strong>
-
-	<p>Each string or url-token represents the URI of an image. If a resolution
-	is given, then the image must be rendered at the specified resolution. If the
-	''snap'' keyword is also specified, and the image is a raster image, then the
-	image must be rendered at the resolution closest to the specified resolution
-	that would result in no pixel rounding. <span class="issue">I don't think
-	"no pixel rounding" is the right terminology here... basically we want to
-	avoid blurry images.</span></p>
-
-	<p>The final argument may be a color or generated image, to serve as an
-	ultimate fallback if none of the preceeding <i>&lt;image-decl></i>s can be used.  
-	If it is a color, the <i>&lt;image-list></i> must represent a single-color 
-	image of that color with no <i>intrinsic dimensions</i>.</p>
+Image Annotations: the ''image()'' notation</h3>
+
+	<p>The ''image()'' notation allows an author to tag an image with a few types
+	of useful processing instructions which can affect the rendering of the image.
+	The author can specify the desired resolution the image should be rendered at,
+	declare the directionality of an image so that it can be automatically be 
+	reversed if used in text with a different directionality, or declare fallback
+	images to be used if the original image can't be decoded or is a type that the
+	browser doesn't recognize.</p>
+
+	<pre class='prod'><dfn>&lt;image-list></dfn> = 
+	image( [ &lt;image-decl> , ]* [ &lt;image-decl> | &lt;color> | &lt;image> ] )</pre>
+
+	<p>where &lt;image-decl> is given by:</p>
+
+	<pre class='prod'><dfn>&lt;image-decl></dfn> = 
+	[ &lt;string> | &lt;url> ] [ snap? && &lt;resolution> ]? [ ltr | rtl ]?
+
+	<p>Each <i>&lt;image-decl></i> represents an external image.  If a &lt;string>
+	is provided, it represents the same image that it would if the the string
+	were given to the ''url()'' function.</p>
+
+	<p>If a &lt;resolution> is given, the image must be rendered at that resolution.
+	<span class='note'>Recall that the default resolution of images is ''1dppx'',
+	so that one image pixel corresponds to one CSS ''px'' unit.</span>  If the 
+	''snap'' keyword is also specified, and the specified resolution would make 
+	one image pixel larger than one device pixel, the image must be rendered at 
+	the specified resolution, rounded to the nearest value that would map one image 
+	pixel to an integer number of device pixels; if the specified resolution would 
+	make one image pixel smaller than one device pixel, the image must be rendered 
+	at the specified resolution, rounded to the nearest value that would map an 
+	integer number of image pixels to one device pixel.</p>
+
+	<p>If a directional keyword (''ltr'' or ''rtl'') is given, the image itself
+	gains that directionality.  If the image is used in a property on an element
+	with opposite directionality, is must be rendered horizontally flipped (in the
+	image's own coordinate space).</p>
+
+	<p>Multiple arguments can be given, in which case the function represents
+	the first &lt;image-decl> representing an image that the browser can successfully
+	load and display.  The final argument can be a &lt;color> or other type of
+	&lt;image to serve as ultimate fallback if none of the preceding &lt;image-decl>s
+	can be used.  If the final argument is a &lt;color>, it represents a solid-color
+	image of the given color with no <i>intrinsic dimensions</i>.
 
 	<div class="example">
-		<p>For example, the rule below would tell the UA to load ''wavy.svg'' if
+		<p>The rule below would tell the UA to load ''wavy.svg'' if
 		it can; failing that to load ''wavy.png'' and display it at 150dpi;
 		failing that to display ''wavy.gif''; and finally, if none of the images
 		can be loaded and displayed, to use the color ''blue'' to create a
-		dimensionless background image.</p>
+		dimensionless background image.  For example, the browser may not understand
+		how to render SVG images, the PNG may be malformed, and the GIF may not 
+		exist on the server, so requesting it returns an HTML 404 page instead of 
+		an image.</p>
 
-		<pre>background-image: image(wavy.svg, 'wavy.png' 150dpi, "wavy.gif", blue);</pre>
+		<pre>background-image: image(url(wavy.svg), 'wavy.png' 150dpi, "wavy.gif", blue);</pre>
 
 		<p>The 'background-image' property specifies that dimensionless images
 		must stretch to cover the entire background positioning area