[css-timing-1] Re-order the updated step timing function section

Author: birtles

css-timing-1/Overview.bs

@@ -209,47 +209,131 @@ Step timing functions: ''step-start'', ''step-end'', ''steps()'' {#step-timing-f
 A <dfn>step timing function</dfn> is a type of <a>timing function</a>
 that divides the input time into a specified number of intervals that
 are equal in length.
+It is defined by a number of <dfn>steps</dfn>, and a <dfn>step position</dfn>.
+It has following syntax:
 
-Some example step timing functions are illustrated below.
+<div class="prod">
+  <dfn type>&lt;step-timing-function&gt;</dfn> =
+  ''step-start'' | ''step-end'' |
+  <span class="atom"><a lt="steps()" function>steps</a>(<<integer>>[,
+    <<step-position>>]?)</span>
 
-<figure>
-  <img src="step-timing-func-examples.svg" width="500"
-      alt="Example step timing functions.">
-  <figcaption>
-    Example step timing functions.
-    In each case the domain is the input progress whilst the range
-    represents the output progress produced by the step function.<br>
-    The first row shows the function for each transition point when only
-    one step is specified whilst the second row shows the same for three
-    steps.
-  </figcaption>
-</figure>
+  <dfn type>&lt;step-position&gt;</dfn> =
+    ''jump-start'' | ''jump-end'' |
+    ''jump-none'' | ''jump-both'' |
+    ''start'' | ''end''</div>
+
+The meaning of each value is as follows:
+
+<dl dfn-type=value dfn-for="step-timing-function, <step-timing-function>">
+
+:   <dfn>step-start</dfn>
+::  Computes to ''steps(1, start)''
+:   <dfn>step-end</dfn>
+::  Computes to ''steps(1, end)''
+
+    <figure>
+      <img src="step-timing-keyword-examples.svg" width="500"
+          alt="Example step timing keywords.">
+      <figcaption>
+        Example step timing function keyword values.
+      </figcaption>
+    </figure>
+
+:   <dfn function lt="steps()">steps(&lt;integer&gt;[, &lt;step-position&gt; ]?)</dfn>
+::  The first parameter specifies the number of intervals in the function.
+    It must be a positive integer greater than 0
+    unless the second parameter is <a value for="steps()">jump-none</a>
+    in which case it must be a positive integer greater than 1.
+
+    The second parameter, which is optional, specifies the [=step position=]
+    using one of the following values:
+
+    <dl dfn-type=value dfn-for="step-position, <step-position>">
+
+    :   <dfn value for="steps()">jump-start</dfn>
+    ::  The first rise occurs at [=input progress value=] of 0.
+    :   <dfn value for="steps()">jump-end</dfn>
+    ::  The last rise occurs at [=input progress value=] of 1.
+    :   <dfn value for="steps()">jump-none</dfn>
+    ::  All rises occur within the range (0, 1).
+    :   <dfn value for="steps()">jump-both</dfn>
+    ::  The first rise occurs at [=input progress value=] of 0
+        and the last rise occurs at [=input progress value=] of 1.
+    :   <dfn value for="steps()">start</dfn>
+    ::  Behaves as <a value for="steps()">jump-start</a>.
+    :   <dfn value for="steps()">end</dfn>
+    ::  Behaves as <a value for="steps()">jump-end</a>.
 
-A [=step timing function=] is defined by a non-zero positive number of
-<dfn>steps</dfn>, and a <dfn>step position</dfn> property that may one of:
-<a value for="steps()">jump-start</a>,
-<a value for="steps()">jump-end</a>,
-<a value for="steps()">jump-none</a>, or
-<a value for="steps()">jump-both</a>, or the legacy
-<a value for="steps()">start</a> or
-<a value for="steps()">end</a> values.
+    </dl>
+
+    If the second parameter is omitted, the value ''end'' is assumed.
+
+    These values are illustrated below:
+
+    <figure>
+      <img src="step-timing-func-examples.svg" width="500"
+          alt="Example step timing functions.">
+      <figcaption>
+        Example step timing functions.
+      </figcaption>
+    </figure>
+
+</dl>
+
+### Output of a step timing function ### {#step-timing-function-algo}
 
 At the exact point where a step occurs, the result of the function is
 conceptually the top of the step. However, an additional <dfn>before flag</dfn>
 passed as input to the [=step timing function=], if true, will cause the
 result of the function to correspond to the bottom of the step at the step
 point.
 
+<div class=example>
+
+As an example of how the [=before flag=] affects the behavior of this function,
+consider an animation with a [=step timing function=] whose [=step
+position=] is <a value for="steps()">start</a> and which has a positive
+delay and backwards fill.
+
+For example, using CSS animation:
+
+<pre class='lang-css'>
+animation: moveRight 5s 1s steps(5, start);
+</pre>
+
+During the delay phase, the [=input progress value=] will be zero but if the
+[=before flag=] is set to indicate that the animation has yet to reach its
+animation interval, the timing function will produce zero as its [=output
+progress value=], i.e. the bottom of the first step.
+
+At the exact moment when the animation interval begins, the [=input progress
+value=] will still be zero, but the [=before flag=] will not be set and hence
+the result of the timing function will correspond to the top of the first step.
+
+</div>
+
+For the purposes of calculating the [=output progress value=], the
+[=step position=] <a value for="steps()">start</a> is considered equivalent to
+<a value for="steps()">jump-start</a>.
+Likewise <a value for="steps()">end</a> is considered equivalent to <a value
+for="steps()">jump-end</a>.
+As a result, the following algorithm does not make explicit reference to
+<a value for="steps()">start</a> or <a value for="steps()">end</a>.
+
+Note: User agents must still differentiate between
+<a value for="steps()">jump-start</a> and <a value for="steps()">start</a> for
+the purpose of serialization (see [[#serializing-a-timing-function]]).
+
 The [=output progress value=] is calculated from the [=input progress value=]
 and [=before flag=] as follows:
 
-1.   Calculate the <var>current step</var> as <code>floor([=input progress
-     value=] &times; [=steps=])</code>.
+1.   Calculate the <var>current step</var> as
+     <code>floor([=input progress value=] &times; [=steps=])</code>.
 
 1.   If the [=step position=] property is one of:
 
      * <a value for="steps()">jump-start</a>,
-     * <a value for="steps()">start</a>, or
      * <a value for="steps()">jump-both</a>,
 
      increment <var>current step</var> by one.
@@ -268,10 +352,8 @@ and [=before flag=] as follows:
 
 1.   Calculate |jumps| based on the [=step position=] as follows:
 
-      :   <a value for="steps()">jump-start</a>,
-          <a value for="steps()">start</a>,
-          <a value for="steps()">jump-end</a>, or
-          <a value for="steps()">end</a>
+      :   <a value for="steps()">jump-start</a> or
+          <a value for="steps()">jump-end</a>
       ::  [=steps=]
       :   <a value for="steps()">jump-none</a>
       ::  [=steps=] - 1
@@ -288,89 +370,22 @@ and [=before flag=] as follows:
      [=output progress value=] outside that range.
 
      For example, although mathematically we might expect that a step timing
-     function with a [=step position=] of <a value for="steps()">start</a>
+     function with a [=step position=] of <a value for="steps()">jump-start</a>
      would step up (i.e. beyond 1) when the [=input progress value=] is 1,
      intuitively,
      when we apply such a timing function to a forwards-filling animation,
      we expect it to produce an [=output progress value=] of 1
      as the animation fills forwards.
 
-     A similar situation arises for a step timing function with a [=step
-     position=] of <a value for="steps()">end</a> when applied to an animation
-     during its delay phase.
+     A similar situation arises for a step timing function with
+     a [=step position=] of <a value for="steps()">jump-end</a>
+     when applied to an animation during its delay phase.
 
      </div>
 
 1.   The [=output progress value=] is <code><var>current step</var> /
      |jumps|</code>.
 
-<div class=example>
-
-As an example of how the [=before flag=] affects the behavior of this function,
-consider an animation with a [=step timing function=] whose [=step
-position=] is <a value for="steps()">start</a> and which has a positive
-delay and backwards fill.
-
-For example, using CSS animation:
-
-<pre class='lang-css'>
-animation: moveRight 5s 1s steps(5, start);
-</pre>
-
-During the delay phase, the [=input progress value=] will be zero but if the
-[=before flag=] is set to indicate that the animation has yet to reach its
-animation interval, the timing function will produce zero as its [=output
-progress value=], i.e. the bottom of the first step.
-
-At the exact moment when the animation interval begins, the [=input progress
-value=] will still be zero, but the [=before flag=] will not be set and hence
-the result of the timing function will correspond to the top of the first step.
-
-</div>
-
-The syntax for specifying a step timing function is as follows:
-
-<div class="prod">
-  <dfn type>&lt;step-position&gt;</dfn> =
-    ''jump-start'' | ''jump-end'' |
-    ''jump-none'' | ''jump-both'' |
-    ''start'' | ''end''
-
-  <dfn type>&lt;step-timing-function&gt;</dfn> =
-  ''step-start'' | ''step-end'' |
-  <span class="atom"><a lt="steps()" function>steps</a>(<<integer>>[,
-    <<step-position>>]?)</span></div>
-
-The meaning of each value is as follows:
-
-<dl dfn-type=value dfn-for="step-timing-function, <step-timing-function>">
-
-:   <dfn>step-start</dfn>
-::  Equivalent to steps(1, start);
-:   <dfn>step-end</dfn>
-::  Equivalent to steps(1, end);
-:   <dfn function lt="steps()">steps(&lt;integer&gt;[, &lt;step-position&gt; ]?)</dfn>
-::  Specifies a <a>step timing function</a>.
-
-    The first parameter specifies the number of intervals in the function.
-    It must be a positive integer greater than 0
-    unless the second parameter is <a value for="steps()">jump-none</a>
-    in which case it must be a positive integer greather than 1.
-
-    The second parameter, which is optional, specifies the [=step position=]
-    using one of the following values:
-
-    * <dfn value for="steps()">jump-start</dfn>
-    * <dfn value for="steps()">jump-end</dfn>
-    * <dfn value for="steps()">jump-none</dfn>
-    * <dfn value for="steps()">jump-both</dfn>
-    * <dfn value for="steps()">start</dfn>
-    * <dfn value for="steps()">end</dfn>
-
-    If the second parameter is omitted, it is given the value ''end''.
-
-</dl>
-
 
 Serialization {#serializing-a-timing-function}
 -------------