2010-03-23 simon.fraser@apple.com

- Better start to the Keyframes section
- Example 1 changed to use an identifier, rather than a string for the keyframes name.
- Changed paragraph stating that 'from' and 'to' keyframes are required to say that these
  are implied if missing, using the computed values. Added ISSUE related to repeating animations.
- Added NOTE to clarify behavior when a property is not specified in all keyframes.
- Move the contents Animation Behavior section into the Animation section, so we introduce general
animation behavior before diving into keyframes.

Author: smfr

css3-animations/ChangeLog

@@ -1,3 +1,12 @@
+2010-03-23 simon.fraser@apple.com
+- Better start to the Keyframes section
+- Example 1 changed to use an identifier, rather than a string for the keyframes name.
+- Changed paragraph stating that 'from' and 'to' keyframes are required to say that these
+  are implied if missing, using the computed values. Added ISSUE related to repeating animations.
+- Added NOTE to clarify behavior when a property is not specified in all keyframes.
+- Move the contents Animation Behavior section into the Animation section, so we introduce general
+animation behavior before diving into keyframes.
+
 2010-03-10 simon.fraser@apple.com
 
 - enhance the Abstract and Introduction.

css3-animations/Overview.html

@@ -29,14 +29,14 @@
 
    <h1>CSS Animations Module Level 3</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 10 March 2010</h2>
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 23 March 2010</h2>
 
    <dl>
     <dt>This version:
 
     <dd><a
-     href="http://www.w3.org/TR/2010/ED-css3-animations-20100310">http://dev.w3.org/csswg/css3-animations/</a>
-     <!--http://www.w3.org/TR/2010/WD-css3-animations-20100310-->
+     href="http://www.w3.org/TR/2010/ED-css3-animations-20100323">http://dev.w3.org/csswg/css3-animations/</a>
+     <!--http://www.w3.org/TR/2010/WD-css3-animations-20100323-->
 
     <dt>Latest version:
 
@@ -129,16 +129,12 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
   <ul class=toc>
    <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
 
-   <li><a href="#keyframes"><span class=secno>2. </span>Keyframes</a>
-    <ul class=toc>
-     <li><a href="#timing-functions-for-keyframes-"><span class=secno>2.1.
-      </span> Timing functions for keyframes </a>
-    </ul>
+   <li><a href="#animations"><span class=secno>2. </span>Animations</a>
 
-   <li><a href="#animations-"><span class=secno>3. </span> Animations </a>
+   <li><a href="#keyframes"><span class=secno>3. </span>Keyframes</a>
     <ul class=toc>
-     <li><a href="#animation-behavior-"><span class=secno>3.1. </span>
-      Animation behavior </a>
+     <li><a href="#timing-functions-for-keyframes-"><span class=secno>3.1.
+      </span> Timing functions for keyframes </a>
 
      <li><a href="#the-animation-name-property-"><span class=secno>3.2.
       </span> The <span class=prop-name>&lsquo;<code
@@ -209,23 +205,109 @@ <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
 
   <p> This proposal introduces <em>defined animations</em>, in which the
    author can specify the changes in CSS properties over time as a set of
-   keyframes. Unlike transitions, which are triggered by changes in the
-   underlying property values, keyframe animations are triggered by the
-   application of the animation properties themselves. While the animation is
-   running, the property values in the keyframes are applied at the
-   appropriate times.
+   keyframes. Animations are similar to transitions in that they change the
+   presentational value of CSS properties over time. The principal difference
+   is that while transitions trigger <i>implicitly</i> when property values
+   change, animations are <i>explicitly</i> executed when the animation
+   properties are applied. Because of this, animations require explicit
+   values for the properties being animated. These values are specified using
+   animation keyframes, described below.
+
+  <p> Many aspects of the animation can be controlled, including how many
+   times the animation iterates, whether or not it alternates between the
+   begin and end values, and whether or not the animation should be running
+   or paused. An animation can also delay its start time.
+
+  <h2 id=animations><span class=secno>2. </span>Animations</h2>
+
+  <p> CSS Animations affect computed property values. During the execution of
+   an animation, the computed value for a property is controlled by the
+   animation. This overrides the value specified in the normal styling
+   system.
+
+  <p> In the case of multiple animations specifying behavior for the same
+   property, the animation defined last will override the previously defined
+   animations.
+
+  <p> An animation does not affect the computed value before the application
+   of the animation, before the animation delay has expired, and after the
+   end of the animation.
+
+  <div class=figure> <img alt="" src=sandwich.png></div>
+
+  <p class=caption> Computation of animated property values
+
+  <p> The diagram above shows how property values are computed. The intrinsic
+   style is shown at the top of the diagram. The computed value is derived
+   from intrinsic style at the times when an animation is not running and
+   also when an animation is delayed (see below for specification of
+   animation delay). During an animation, the computed style is derived from
+   the animated value.
+
+  <p> The start time of an animation is the latter of two moments: the time
+   at which the style is resolved that specifies the animation, or the time
+   the document's load event is fired. Therefore, an animation specified in
+   the document stylesheet will begin at the document load. An animation
+   specified on an element by modifying the style after the document has
+   loaded will start when the style is resolved. That may be immediately in
+   the case of a pseudo style rule such as hover, or may be when the
+   scripting engine returns control to the browser (in the case of style
+   applied by script).
+
+  <p> An animation applies to an element if the element has a value for <span
+   class=prop-name>&lsquo;<code class=property><a
+   href="#animation-name">animation-name</a></code>&rsquo;</span> that
+   references a valid keyframes rule. Once an animation has started it
+   continues until it ends or the <span class=prop-name>&lsquo;<code
+   class=property><a
+   href="#animation-name">animation-name</a></code>&rsquo;</span> is removed.
+   The values used for the keyframes and animation properties are snapshotted
+   at the time the animation starts. Changing them during the execution of
+   the animation has no effect. Note also, that changing the value of <span
+   class=prop-name>&lsquo;<code class=property><a
+   href="#animation-name">animation-name</a></code>&rsquo;</span> does not
+   necessarily restart an animation (e.g. if a list of animations are applied
+   and one is removed from the list, only that animation will stop; The other
+   animations will continue). In order to restart an animation, it must be
+   removed then reapplied.
 
-  <p> CSS Animations also provide greater control over the animation behavior
-   than transitions. Animation properties allow the author to control how may
-   times the animation repeats, the behavior when repeating, and to pause the
-   animation mid-cycle.
+  <p class=note> Describe the effects of fill-mode here.
 
-  <h2 id=keyframes><span class=secno>2. </span>Keyframes</h2>
+  <div class=example>
+   <p style="display:none"> Example(s):</p>
 
-  <p> In a simple transition, since both the starting value and ending value
-   are known, a single timing function and duration determine the
-   intermediate values of the animating property. If finer control of the
-   intermediate values is required, keyframes can be used.
+   <pre>
+    div {
+      animation-name: diagonal-slide;
+      animation-duration: 5s;
+      animation-iteration-count: 10;
+    }
+
+    @keyframes diagonal-slide {
+
+      from {
+        left: 0;
+        top: 0;
+      }
+
+      to {
+        left: 100px;
+        top: 100px;
+      }
+
+    }
+
+    </pre>
+   This will produce an animation that moves an element from (0, 0) to
+   (100px, 100px) over five seconds and repeats itself nine times (for a
+   total of ten iterations).</div>
+
+  <h2 id=keyframes><span class=secno>3. </span>Keyframes</h2>
+
+  <p> Keyframes are used to specify the values for the animating properties
+   at various points during the animation. The keyframes specify the behavior
+   of one cycle of the animation; the animation may iterate one or more
+   times.
 
   <p> Keyframes are specified using a specialized CSS at-rule. A <span
    class=prop-name>@keyframes</span> rule consists of the keyword
@@ -247,22 +329,32 @@ <h2 id=keyframes><span class=secno>2. </span>Keyframes</h2>
    value 100%. Note that the percentage unit specifier must be used on
    percentage values. Therefore, "0" is an invalid keyframe selector.
 
-  <p> Keyframes can be specified in any order. The selector determines the
-   placement of the keyframe in the animation.
+  <p> If a 0% or "from" keyframe is not specified, then the user agent
+   constructs a 0% keyframe using the computed values of the properties being
+   animated. If a 100% or "to" keyframe is not specified, then the user agent
+   constructs a 100% keyframe using the computed values of the properties
+   being animated.
+   <!--Every keyframe declaration must have a keyframe rule for 
+        0% or 100%, possibly defined using "from" or "to". A keyframe
+        declaration without these keyframe selectors is invalid and will not
+        be available for animation. -->
+   
 
-  <p> Every keyframe declaration must have a keyframe rule for 0% or 100%,
-   possibly defined using "from" or "to". A keyframe declaration without
-   these keyframe selectors is invalid and will not be available for
-   animation.
+  <p class=issue> ISSUE: how does this work with repeating animations?
 
   <p> The <i>keyframe declaration</i> for a keyframe rule consists of
    properties and values. Properties that are unable to be animated are
    ignored in these rules, with the exception of <a class=prop-name
    href="#animation-timing-function">animation-timing-function'</a>, the
    behavior of which is described below.
 
+  <p class=note> NOTE: describe what happens if a property is not present in
+   all keyframes.
+
   <p> The @keyframes rule that is used by an animation will be the last one
-   encountered in sorted rules order that matches the name of the animation.
+   encountered in sorted rules order that matches the name of the animation
+   specified by the <span class=prop-name>&lsquo;<code class=property><a
+   href="#animation-name">animation-name</a></code>&rsquo;</span> property.
    <span class=prop-name>@keyframes</span> rules do not cascade; therefore an
    animation will never derive keyframes from more than one <span
    class=prop-name>@keyframes</span> rule.
@@ -278,7 +370,7 @@ <h2 id=keyframes><span class=secno>2. </span>Keyframes</h2>
    <p style="display:none"> Example(s):</p>
 
    <pre>
-  @keyframes 'wobble' {
+  @keyframes wobble {
 
     0% {
       left: 100px;
@@ -325,7 +417,7 @@ <h2 id=keyframes><span class=secno>2. </span>Keyframes</h2>
       </pre>
   <!-- ======================================================================================================= -->
 
-  <h3 id=timing-functions-for-keyframes-><span class=secno>2.1. </span>
+  <h3 id=timing-functions-for-keyframes-><span class=secno>3.1. </span>
    Timing functions for keyframes</h3>
 
   <p> A keyframe style rule may also declare the timing function that is to
@@ -335,7 +427,7 @@ <h3 id=timing-functions-for-keyframes-><span class=secno>2.1. </span>
    <p style="display:none"> Example(s):</p>
 
    <pre>
-  @keyframes 'bounce' {
+  @keyframes bounce {
 
     from {
       top: 100px;
@@ -379,105 +471,6 @@ <h3 id=timing-functions-for-keyframes-><span class=secno>2.1. </span>
    class=property>animation-timing-function</code>&rsquo;</span> property</a>
    for more information.</p>
   <!-- ======================================================================================================= -->
-
-  <h2 id=animations-><span class=secno>3. </span> Animations</h2>
-
-  <p> Animations are similar to transitions in that they change the
-   presentational value of CSS properties over time. The principal difference
-   is that while transitions trigger <i>implicitly</i> when property values
-   change, animations are <i>explicitly</i> executed when the animation
-   properties are applied. Because of this, animations require explicit
-   values for the properties being animated. These values are specified using
-   animation keyframes, described above.
-
-  <p> Many aspects of the animation can be controlled, including how many
-   times the animation iterates, whether or not it alternates between the
-   begin and end values, and whether or not the animation should be running
-   or paused. An animation can also delay its start time.
-
-  <div class=example>
-   <p style="display:none"> Example(s):</p>
-
-   <pre>
-  div {
-    animation-name: 'diagonal-slide';
-    animation-duration: 5s;
-    animation-iteration-count: 10;
-  }
-
-  @keyframes 'diagonal-slide' {
-
-    from {
-      left: 0;
-      top: 0;
-    }
-
-    to {
-      left: 100px;
-      top: 100px;
-    }
-
-  }
-
-  </pre>
-   This will produce an animation that moves an element from (0, 0) to
-   (100px, 100px) over five seconds and repeats itself nine times (for a
-   total of ten iterations).</div>
-  <!-- ======================================================================================================= -->
-
-  <h3 id=animation-behavior-><span class=secno>3.1. </span> Animation
-   behavior</h3>
-
-  <p> CSS Animations affect computed property values. During the execution of
-   an animation, the computed value for a property is controlled by the
-   animation. This overrides the value specified in the normal styling
-   system.
-
-  <p> In the case of multiple animations specifying behavior for the same
-   property, the animation defined last will override the previously defined
-   animations.
-
-  <p> An animation does not affect the computed value before the application
-   of the animation, before the animation delay has expired, and after the
-   end of the animation.
-
-  <div class=figure> <img alt="" src=sandwich.png></div>
-
-  <p class=caption> Computation of animated property values
-
-  <p> The diagram above shows how property values are computed. The intrinsic
-   style is shown at the top of the diagram. The computed value is derived
-   from intrinsic style at the times when an animation is not running and
-   also when an animation is delayed (see below for specification of
-   animation delay). During an animation, the computed style is derived from
-   the animated value.
-
-  <p> The start time of an animation is the latter of two moments: the time
-   at which the style is resolved that specifies the animation, or the time
-   the document's load event is fired. Therefore, an animation specified in
-   the document stylesheet will begin at the document load. An animation
-   specified on an element by modifying the style after the document has
-   loaded will start when the style is resolved. That may be immediately in
-   the case of a pseudo style rule such as hover, or may be when the
-   scripting engine returns control to the browser (in the case of style
-   applied by script).
-
-  <p> An animation applies to an element if the element has a value for <span
-   class=prop-name>&lsquo;<code class=property><a
-   href="#animation-name">animation-name</a></code>&rsquo;</span> that
-   references a valid keyframes rule. Once an animation has started it
-   continues until it ends or the <span class=prop-name>&lsquo;<code
-   class=property><a
-   href="#animation-name">animation-name</a></code>&rsquo;</span> is removed.
-   The values used for the keyframes and animation properties are snapshotted
-   at the time the animation starts. Changing them during the execution of
-   the animation has no effect. Note also, that changing the value of <span
-   class=prop-name>&lsquo;<code class=property><a
-   href="#animation-name">animation-name</a></code>&rsquo;</span> does not
-   necessarily restart an animation (e.g. if a list of animations are applied
-   and one is removed from the list, only that animation will stop; The other
-   animations will continue). In order to restart an animation, it must be
-   removed then reapplied.</p>
   <!-- ======================================================================================================= -->
 
   <h3 id=the-animation-name-property-><span class=secno>3.2. </span> The