[css4-images] Remove most of the serialization section in favor of a nice paragraph of rules.

Author: tabatkins

css4-images/Overview.html

@@ -286,22 +286,6 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
 
    <li><a href="#serialization"><span class=secno>8. </span>
     Serialization</a>
-    <ul class=toc>
-     <li><a href="#serializing-image-notation"><span class=secno>8.1. </span>
-      Serializing the ‘<code class=css>image()</code>’ /
-      <var>&lt;image-list></var> notation</a>
-
-     <li><a href="#serializing-element-notation"><span class=secno>8.2.
-      </span> Serializing the ‘<code class=css>element()</code>’ /
-      <var>&lt;element-image></var> notation</a>
-
-     <li><a href="#serializing-cross-fade"><span class=secno>8.3. </span>
-      Serializing the ‘<code class=css>cross-fade()</code>’ /
-      <var>&lt;image-combination></var> notation</a>
-
-     <li><a href="#serializing-gradients"><span class=secno>8.4. </span>
-      Serializing Gradients</a>
-    </ul>
 
    <li><a href="#conformance"><span class=secno>9. </span> Conformance</a>
     <ul class=toc>
@@ -532,14 +516,14 @@ <h3 id=image-notation><span class=secno>3.2. </span> Image Fallbacks and
   <pre class=prod><br><!--
 	--><dfn
    id=image-list-type>&lt;image-list></dfn> = image( <a
-   href="#image-annotations-type"><var>&lt;image-annotations></var></a>? [ <a
-   href="#image-decl-type"><var>&lt;image-decl></var></a> , ]* [ <a
-   href="#image-decl-type"><var>&lt;image-decl></var></a> | <var>&lt;color></var> ] )<br><!--
+   href="#image-tags-type"><var>&lt;image-tags></var></a>? [ <a
+   href="#image-src-type"><var>&lt;image-src></var></a> , ]* [ <a
+   href="#image-src-type"><var>&lt;image-src></var></a> | <var>&lt;color></var> ] )<br><!--
 	--><dfn
-   id=image-annotations-type>&lt;image-annotations></dfn> = [ ltr | rtl ]
+   id=image-tags-type>&lt;image-tags></dfn> = [ ltr | rtl ]
 <!--
 	--><dfn
-   id=image-decl-type>&lt;image-decl></dfn> = [ <var>&lt;url></var> | <var>&lt;string></var> ]</pre>
+   id=image-src-type>&lt;image-src></dfn> = [ <var>&lt;url></var> | <var>&lt;string></var> ]</pre>
 
   <p> Each ‘<code class=css>&lt;string></code>’ or ‘<code
    class=css>&lt;url></code>’ inside ‘<code class=css>image()</code>’
@@ -597,20 +581,20 @@ <h4 id=image-fragments><span class=secno>3.2.1. </span> Image Fragments</h4>
 
   <h4 id=image-fallbacks><span class=secno>3.2.2. </span> Image Fallbacks</h4>
 
-  <p> Multiple ‘<a href="#image-decl-type"><code
-   class=css>&lt;image-decl>s</code></a>’ can be given separated by commas,
+  <p> Multiple ‘<a href="#image-src-type"><code
+   class=css>&lt;image-src>s</code></a>’ can be given separated by commas,
    in which case the function represents the first image that's not an <a
    href="#invalid-image"><i>invalid image</i></a>. The final argument can
    specify a ‘<code class=css>&lt;color></code>’ to serve as an ultimate
    fallback; this can be used, e.g. for ‘<code
    class=property>background-image</code>’, to ensure adequate contrast if
-   none of the preceding ‘<a href="#image-decl-type"><code
-   class=css>&lt;image-decl>s</code></a>’ can be used. If the final
-   argument is a ‘<code class=css>&lt;color></code>’, it represents a
-   solid-color image of the given color with no <a
+   none of the preceding ‘<a href="#image-src-type"><code
+   class=css>&lt;image-src>s</code></a>’ can be used. If the final argument
+   is a ‘<code class=css>&lt;color></code>’, it represents a solid-color
+   image of the given color with no <a
    href="#intrinsic-dimensions"><i>intrinsic dimensions</i></a>. If all of
-   the provided ‘<a href="#image-decl-type"><code
-   class=css>&lt;image-decl>s</code></a>’ are <a
+   the provided ‘<a href="#image-src-type"><code
+   class=css>&lt;image-src>s</code></a>’ are <a
    href="#invalid-image"><i>invalid images</i></a> and a fallback color was
    not provided as the last argument, the entire ‘<code
    class=css>image()</code>’ function must be treated as an <a
@@ -690,7 +674,7 @@ <h4 id=color-images><span class=secno>3.2.3. </span> Solid-color Images</h4>
   <h4 id=bidi-images><span class=secno>3.2.4. </span> Bidi-sensitive Images</h4>
 
   <p> Before listing any <a
-   href="#image-decl-type"><code>&lt;image-decl>s</code></a>, the author may
+   href="#image-src-type"><code>&lt;image-src>s</code></a>, the author may
    specify a directionality for the image, similar to adding a
    <code>dir</code> attribute to an element in HTML. If a directional image
    is used on or in an element with opposite <a
@@ -3660,217 +3644,27 @@ <h2 id=serialization><span class=secno>8. </span> Serialization</h2>
    interfacing with the CSS Object Model <a href="#CSSOM"
    rel=biblioentry>[CSSOM]<!--{{CSSOM}}--></a>.
 
-  <p> All of these algorithms refer to a variable "s". For each, let s
-   initially be the empty string, run the steps described, and then return s.
-
-  <p class=issue> These descriptions are all old, and need to be updated to
-   the current state of the various value types.
-
-  <h3 id=serializing-image-notation><span class=secno>8.1. </span>
-   Serializing the ‘<code class=css>image()</code>’ / <a
-   href="#image-list-type"><var>&lt;image-list></var></a> notation</h3>
-
-  <p> To serialize an <a
-   href="#image-list-type"><var>&lt;image-list></var></a>:
-
-  <ol>
-   <li> Append "image(" to s.
-
-   <li> For each argument, serialize the argument as an <a
-    href="#image-decl-type"><var>&lt;image-decl></var></a> or
-    <var>&lt;color></var> as appropriate, and append it to s. Then, if it is
-    not the final argument, append a comma and a space ", " to s.
-
-   <li> Append a close parenthesis ")" to s.
-  </ol>
-
-  <p> To serialize an <a
-   href="#image-decl-type"><var>&lt;image-decl></var></a>:
-
-  <ol>
-   <li> Serialize the first part of the value (the <var>&lt;string></var>) as
-    a string.
-
-   <li> If a <var>&lt;resolution></var> was provided, append a space " " to
-    s. Then serialize the <var>&lt;resolution></var> and append it to s.
-
-   <li> If the ‘<code class=property>snap</code>’ keyword was provided,
-    append a space " " and the literal string "snap" to s.
-
-   <li> If a directional keyword was provided, append a space " " to s, then
-    append the keyword to s.
-  </ol>
-
-  <h3 id=serializing-element-notation><span class=secno>8.2. </span>
-   Serializing the ‘<code class=css>element()</code>’ / <a
-   href="#element-image-type"><var>&lt;element-image></var></a> notation</h3>
-
-  <p> To serialize an <a
-   href="#element-image-type"><var>&lt;element-image></var></a>:
-
-  <ol>
-   <li> Append "element(" to s.
-
-   <li> Serialize the argument as a selector or identifier, as appropriate,
-    and append it to s.
-
-   <li> Append a close parenthesis ")" to s.
-  </ol>
-
-  <h3 id=serializing-cross-fade><span class=secno>8.3. </span> Serializing
-   the ‘<code class=css>cross-fade()</code>’ / <a
-   href="#ltimage-combination"><var>&lt;image-combination></var></a> notation</h3>
-
-  <p> To serialize an <a
-   href="#ltimage-combination"><var>&lt;image-combination></var></a>:
-
-  <ol>
-   <li> Append "cross-fade(" to s.
-
-   <li> Serialize the first argument to the function as an <a
-    href="#image-type"><var>&lt;image></var></a>, and append it to s.
-
-   <li> Append a comma and a space ", " to s.
-
-   <li> Serialize the second argument to the function as an <a
-    href="#image-type"><var>&lt;image></var></a>, and append it to s.
-
-   <li> Append a comma and a space ", " to s.
+  <p> To serialize any function defined in this module, serialize it per its
+   individual grammar, in the order its grammar is written in, omitting
+   components when possible without changing the meaning, joining
+   space-separated tokens with a single space, and following each serialized
+   comma with a single space.
 
-   <li> Serialize the third argument to the function as a
-    <var>&lt;percentage></var>, and append it to s.
+  <p> For ‘<code class=css>cross-fade()</code>’, always serialize the
+   <var>&lt;percentage></var>.
 
-   <li> Append a close parenthesis ")" to s.
-  </ol>
-
-  <h3 id=serializing-gradients><span class=secno>8.4. </span> Serializing
-   Gradients</h3>
-
-  <p> To serialize a <a
-   href="#linear-gradient-type"><var>&lt;linear-gradient></var></a>:
-
-  <ol>
-   <li> Append "linear-gradient(" to s.
-
-   <li>
-    <ul>
-     <li> If the first argument to the gradient function was a single
-      keyword, serialize the keyword and append it to s.
-
-     <li> Otherwise, if the first argument to the gradient function was two
-      keywords, serialize the vertical keyword (‘<code
-      class=css>top</code>’ or ‘<code class=css>bottom</code>’) and
-      append it to s, then append a space " " to s, then serialize the
-      horizontal keyword (‘<code class=css>left</code>’ or ‘<code
-      class=css>right</code>’) and append it to s.
-
-     <li> Otherwise, if the first argument to the gradient function was an
-      <var>&lt;angle></var>, serialize the <var>&lt;angle></var> and append
-      it to s.
-
-     <li> Otherwise, append "top" to s.
-    </ul>
-
-   <li> Append a comma and a space ", " to s.
-
-   <li> For each color-stop in the gradient, serialize the color-stop, and
-    append it to s. Then, if it is not the final color-stop, append a comma
-    and a space ", " to s.
-
-   <li> Append a close parenthesis ")" to s.
-  </ol>
-
-  <p> To serialize a <a
-   href="#radial-gradient-type"><var>&lt;radial-gradient></var></a>:
-
-  <ol>
-   <li> Append "radial-gradient(" to s.
-
-   <li> If a <a href="#position"><var>&lt;position></var></a> was specified
-    in the first argument to the gradient function, serialize it and append
-    it to s. Otherwise, append "center" to s.
-
-   <li> Append a comma and a space ", " to s.
-
-   <li>
-    <ul>
-     <li> If a <a href="#shape"><var>&lt;shape></var></a> and/or <a
-      href="#size"><var>&lt;size></var></a> was specified in the second
-      argument to the gradient function:
-      <ol>
-       <li> If a <a href="#shape"><var>&lt;shape></var></a> was specified,
-        serialize it as a keyword and append it to s. Otherwise, append
-        "ellipse" to s.
-
-       <li> Append a space " " to s.
-
-       <li> If a <a href="#size"><var>&lt;size></var></a> was specified,
-        serialize it as a keyword and append it to s. Otherwise, append
-        "cover" to s.
-      </ol>
-
-     <li> Otherwise, if two <a
-      href="#radial-size-circle"><var>&lt;length></var></a>s or
-      <var>&lt;percentage></var>s were specified in the second argument to
-      the gradient function:
-      <ol>
-       <li> Serialize the first <a
-        href="#radial-size-circle"><var>&lt;length></var></a> or
-        <var>&lt;percentage></var> and append it to s.
-
-       <li> Append a space " " to s.
-
-       <li> Serialize the second <a
-        href="#radial-size-circle"><var>&lt;length></var></a> or
-        <var>&lt;percentage></var> and append it to s.
-      </ol>
-
-     <li> Otherwise, append "ellipse cover" to s.
-    </ul>
-
-   <li> Append a comma and a space ", " to s.
-
-   <li> For each color-stop in the gradient, serialize the color-stop, and
-    append it to s. Then, if it is not the final color-stop, append a comma
-    and a space ", " to s.
-
-   <li> Append a close parenthesis ")" to s.
-  </ol>
-
-  <p> To serialize a <a
-   href="#repeating-linear-gradient-type"><var>&lt;repeating-linear-gradient></var></a>:
-
-  <ol>
-   <li> Append "repeating-linear-gradient(" to s.
-
-   <li> Follow the steps for serializing a <a
-    href="#linear-gradient-type"><var>&lt;linear-gradient></var></a>, except
-    skip step 1.
-  </ol>
-
-  <p> To serialize a <a
-   href="#repeating-radial-gradient-type"><var>&lt;repeating-radial-gradient></var></a>:
-
-  <ol>
-   <li> Append "repeating-radial-gradient(" to s.
+  <div class=example>
+   <p> For example, a gradient specified as:
 
-   <li> Follow the steps for serializing a <a
-    href="#radial-gradient-type"><var>&lt;radial-gradient></var></a>, except
-    skip step 1.
-  </ol>
+   <pre>Linear-Gradient( to bottom, red 0%,yellow,black 100px)</pre>
 
-  <p> To serialize a <a
-   href="#color-stop-type"><var>&lt;color-stop></var></a>:
+   <p> ...must serialize as:
 
-  <ol>
-   <li> Serialize the <var>&lt;color></var>, and append it to s.
+   <pre>linear-gradient(red, yellow, black 100px)</pre>
+  </div>
 
-   <li> If a <a href="#radial-size-circle"><var>&lt;length></var></a> or
-    <var>&lt;percentage></var> was specified, append a space " " to s, then
-    serialize the <a href="#radial-size-circle"><var>&lt;length></var></a> or
-    <var>&lt;percentage></var> and append it to s.
-  </ol>
-  <!--  
+  <p class=issue> The serialization of <var>&lt;color></var> is still
+   undefined. <!--  
                                                                                                                         dddddddd
 TTTTTTTTTTTTTTTTTTTTTTThhhhhhh                                      EEEEEEEEEEEEEEEEEEEEEE                              d::::::d
 T:::::::::::::::::::::Th:::::h                                      E::::::::::::::::::::E                              d::::::d
@@ -4375,15 +4169,9 @@ <h2 class=no-num id=index>Index</h2>
    <li>&lt;image>, <a href="#image-type"
     title="&lt;image>"><strong>3.</strong></a>
 
-   <li>&lt;image-annotations>, <a href="#image-annotations-type"
-    title="&lt;image-annotations>"><strong>3.2.</strong></a>
-
    <li>&lt;image-combination>, <a href="#ltimage-combination"
     title="&lt;image-combination>"><strong>3.5.</strong></a>
 
-   <li>&lt;image-decl>, <a href="#image-decl-type"
-    title="&lt;image-decl>"><strong>3.2.</strong></a>
-
    <li>&lt;image-list>, <a href="#image-list-type"
     title="&lt;image-list>"><strong>3.2.</strong></a>
 
@@ -4402,6 +4190,12 @@ <h2 class=no-num id=index>Index</h2>
    <li>&lt;image-set-decl>, <a href="#image-set-decl-type"
     title="&lt;image-set-decl>"><strong>3.3.</strong></a>
 
+   <li>&lt;image-src>, <a href="#image-src-type"
+    title="&lt;image-src>"><strong>3.2.</strong></a>
+
+   <li>&lt;image-tags>, <a href="#image-tags-type"
+    title="&lt;image-tags>"><strong>3.2.</strong></a>
+
    <li>intrinsic aspect ratio, <a href="#intrinsic-aspect-ratio"
     title="intrinsic aspect ratio"><strong>5.1.</strong></a>