Expanded the <resolution> section to actually talk about what the unit means.

Author: tabatkins

css3-images/Overview.html

@@ -342,8 +342,37 @@ <h2 id=resolution-units><span class=secno>3. </span> Resolution Units: the
    <dd>dots per &lsquo;<code class=css>px</code>&rsquo; unit
   </dl>
 
-  <p class=note>The default resolution of raster images in CSS is
-   &lsquo;<code class=css>1dppx</code>&rsquo;.</p>
+  <p>The &lt;resolution> unit represents the size of a single "dot" of an
+   image. For raster images, a dot is an image pixel. For vector images, a
+   dot is a pixel in the outermost coordinate space of the image. A
+   &lt;resolution> defines how many of these dots fit in a CSS &lsquo;<code
+   class=property>in</code>&rsquo;, &lsquo;<code
+   class=property>cm</code>&rsquo;, or &lsquo;<code
+   class=property>px</code>&rsquo; so that images can be sized accordingly.
+   <span class=note>The default resolution of raster images in CSS is
+   &lsquo;<code class=css>1dppx</code>&rsquo;, which is equivalent to
+   &lsquo;<code class=css>96dpi</code>&rsquo;.</span>
+
+  <div class=example>
+   <p>Printers tend to have substantially higher resolution than computer
+    monitors; due to this, an image that looks fine on the screen may look
+    pixellated when printed out. A &lt;resolution> may be used in the
+    &lsquo;<a href="#image-resolution0"><code
+    class=property>image-resolution</code></a>&rsquo; property to embed a
+    high-resolution image into the document that maintains an appropriate
+    size, ensuring attractive display both on screen and on paper:</p>
+
+   <pre class=css><code>
+img.high-res {
+	image-resolution: 300dpi;
+}</code></pre>
+
+   <p>With this set, an image meant to be 5 inches wide that was saved at
+    300dpi will actually display as 5 inches wide; without this set, the
+    image would display as approximately 15.6 inches wide since the image is
+    15000 image pixels across, and by default there are 96 image pixels per
+    inch.</p>
+  </div>
   <!-- ====================================================================== -->
 
   <h2 id=image><span class=secno>4. </span> Image Values: the &lt;image>
@@ -463,7 +492,7 @@ <h3 id=image-notation><span class=secno>4.2. </span> Image Annotations and
   <p>If a directional keyword (&lsquo;<code class=css>ltr</code>&rsquo; or
    &lsquo;<code class=css>rtl</code>&rsquo;) is given, the image itself gains
    that directionality. If the image is used in a property on an element with
-   opposite directionality, it must be mirrored in the inline dimension when
+   opposite directionality, is must be mirrored in the inline dimension when
    rendered.
 
   <p>Multiple arguments can be given separated by commas, in which case the
@@ -514,8 +543,8 @@ <h3 id=element-reference><span class=secno>4.3. </span> Using Elements as
    slide in a slideshow. The syntax for &lsquo;<code
    class=css>element()</code>&rsquo; is defined as:
 
-  <pre class=prod><dfn id=ltelement-reference>&lt;element-reference></dfn> = 
-	element( [&lt;id-selector> | &lt;identifier> ] )</pre>
+  <pre
+   class=prod><dfn id=ltelement-reference>&lt;element-reference></dfn> = element( [&lt;id-selector> | &lt;identifier> ] )</pre>
 
   <p>where &lt;id-selector> is an ID selector <a href="#SELECT"
    rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>, and &lt;identifier> is an
@@ -540,14 +569,14 @@ <h3 id=element-reference><span class=secno>4.3. </span> Using Elements as
 
   <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 bounding box of the border boxes 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
+   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
@@ -566,22 +595,7 @@ <h3 id=element-reference><span class=secno>4.3. </span> Using Elements as
    regeneration process. That is, the image must look identical to the
    referenced element, modulo rasterization quality.
 
-  <p class=note>While the decision is up to the host language, it is intended
-   that element() can validly refer to some types of elements that are
-   associated with the document but not descendants of the root element. For
-   example, in HTML the &lt;img>, &lt;video>, and &lt;canvas> elements all
-   have a reasonable notion of what it means to "be rendered" without being
-   part of a document, and so they can be created with Javascript, associated
-   with a <a href="#css-element-reference-identifier"><i>CSS Element
-   Reference Identifier</i></a>, and used in element() without being appended
-   to the document.
-
   <div class=example> TODO: copy an example from the MozHacks article</div>
-
-  <p class=issue>Moz's implementation allows directly referencing SVG paint
-   servers. This doesn't come for free - do we want to spec it out? I want to
-   be able to use SVG paint servers *somehow*. I'm not sure if this is quite
-   the place to do it, though.</p>
   <!-- ====================================================================== -->
 
   <h4 class="no-num no-toc" id=element-cycles> Detecting and Resolving

css3-images/Overview.src.html

@@ -149,7 +149,29 @@ <h2 id='resolution-units'>
 		<dd>dots per ''px'' unit</dd>
 	</dl>
 
-	<p class="note">The default resolution of raster images in CSS is ''1dppx''.</p>
+	<p>The &lt;resolution> unit represents the size of a single "dot" of an image.  For raster images,
+	a dot is an image pixel.  For vector images, a dot is a pixel in the outermost coordinate space of
+	the image.  A &lt;resolution> defines how many of these dots fit in a CSS 'in', 'cm', or 'px' so that 
+	images can be sized accordingly. <span class='note'>The default resolution of raster images in 
+	CSS is ''1dppx'', which is equivalent to ''96dpi''.</span></p>
+
+	<div class='example'>
+		<p>Printers tend to have substantially higher resolution than computer monitors; due to this,
+		an image that looks fine on the screen may look pixellated when printed out.  A
+		&lt;resolution> may be used in the 'image-resolution' property to embed a high-resolution
+		image into the document that maintains an appropriate size, ensuring attractive display
+		both on screen and on paper:</p>
+
+		<pre class='css'><code>
+img.high-res {
+	image-resolution: 300dpi;
+}</code></pre>
+
+		<p>With this set, an image meant to be 5 inches wide that was saved at 300dpi will actually
+		display as 5 inches wide; without this set, the image would display as approximately 15.6 inches
+		wide since the image is 15000 image pixels across, and by default there are 96 image pixels per
+		inch.</p>
+	</div>
 
 <!-- ====================================================================== -->