[css-animations] Added marked-up definitions of property values to every property. Added a few issues.

Author: tabatkins

css-animations/Overview.bs

@@ -75,7 +75,7 @@ Animations</h2>
 
 	If at one point in time there are multiple animations specifying behavior
 	for the same property, the animation whose name occurs last in the value
-	of ‘animation-name’ will override the other animations at that point.
+	of 'animation-name' will override the other animations at that point.
 
 	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
@@ -86,12 +86,12 @@ Animations</h2>
 		<figcaption>Computation of animated property values</figcaption>
 	</figure>
 
-	 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.
+	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.
 
 	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
@@ -322,13 +322,28 @@ The 'animation-name' property</h3>
 	Canonical order: per grammar
 	</pre>
 
-	<dfn>&lt;single-animation-name></dfn> = none | <<IDENT>>
+	<dfn>&lt;single-animation-name></dfn> = none | <<custom-ident>>
+
+	The values of 'animation-name' have the following meanings:
+
+	<dl dfn-type=value dfn-for=animation-name>
+		<dt><dfn>none</dfn>
+		<dd>
+			No keyframes are specified at all, so there will be no animation.
+			Any other animations properties specified for this animation have no effect.
+
+		<dt><dfn><<custom-ident>></dfn>
+		<dd>
+			The animation will use the keyframes with the name specified by the <<custom-ident>>,
+			if they exist.
+			If no such keyframes exist,
+			there is no animation.
+	</dl>
 
 <h3 id="animation-duration">
 The 'animation-duration' property</h3>
 
-	The 'animation-duration' property defines the length of time that an animation takes to
-	complete one cycle.
+	The 'animation-duration' property defines duration of a single animation cycle.
 
 	<pre class='propdef'>
 	Name: animation-duration
@@ -343,11 +358,19 @@ The 'animation-duration' property</h3>
 	Canonical order: per grammar
 	</pre>
 
-	The initial value is ''0s'', meaning that the animation takes no time. When the duration is ''0s''
-	'animation-fill-mode' still applies, so an animation that fills backwards will show the value of
-	the ''0%'' keyframe during any delay period, and an animation that fills forwards will retain the
-	value specified at the ''100%'' keyframe, even if the animation was instantaneous. Also, animation
-	events are still fired. A negative 'animation-duration' value renders the declaration invalid.
+	<dl>
+		<dt><dfn value for=animation-duration><<time>></dfn>
+		<dd>
+			The <<time>> specifies the length of time that an animation takes to complete one cycle.
+			A negative <<time>> is invalid.
+
+			If the <<time>> is ''0s'', like the initial value,
+			the keyframes of the animation have no effect,
+			but the animation itself still occurs instantaneously.
+			That is, 'animation-fill-mode' applies as normal,
+			filling backwards or forwards as appropriate,
+			and animation events still fire.
+	</dl>
 
 <h3 id="animation-timing-function">
 The 'animation-timing-function' property</h3>
@@ -369,24 +392,27 @@ The 'animation-timing-function' property</h3>
 	Canonical order: per grammar
 	</pre>
 
-	All the valid values of <dfn>&lt;single-timing-function></dfn> are defined by the 'transition-timing-function'
-	property [[!CSS3-TRANSITIONS]].
+	The values and meaning of <dfn>&lt;single-timing-function></dfn>
+	are identical to those of <<single-transition-timing-function>> [[!CSS3-TRANSITIONS]].
 
-	For a keyframed animation, the 'animation-timing-function' applies between keyframes, not over the
-	entire animation. For example, in the case of an ''ease-in-out'' timing function, an animation will
-	ease in at the start of the keyframe and ease out at the end of the keyframe. An 'animation-timing-function'
-	defined within a keyframe block applies to that keyframe, otherwise the timing function specified for
-	the animation is used. In addition, only the first value of the property applies when it is used in
-	a keyframe block.
+	The timing function specified applies to each iteration of the animation,
+	not the entire animation in full.
+	For example, if an animation has ''animation-timing-function: ease-in-out; animation-iteration-count: 2;'',
+	it will ease in at the start,
+	ease out as it approaches the end of its first iteration,
+	ease in at the start of its second iteration,
+	and ease out again as it approaches the end of the animation.
+
+	Note: Unlike other animation properties,
+	'animation-timing-function' has an effect when specified on an individual keyframe.
+	See <a section href="#timing-functions"></a> for more detail on this.
 
 <h3 id="animation-iteration-count">
 The 'animation-iteration-count' property</h3>
 
 	The 'animation-iteration-count' property specifies the number of times an animation cycle
 	is played. The initial value is ''1'', meaning the animation will play from beginning to end
-	once. A value of ''infinite'' will cause the animation to repeat forever. Non-integer numbers
-	will cause the animation to end part-way through a cycle. Negative values of
-	'animation-iteration-count' are invalid. This property is often used in conjunction an
+	once.  This property is often used in conjunction with an
 	'animation-direction' value of ''alternate'', which will cause the animation to play in
 	reverse on alternate cycles.
 
@@ -405,6 +431,24 @@ The 'animation-iteration-count' property</h3>
 
 	<dfn>&lt;single-animation-iteration-count></dfn> = infinite | <<number>>
 
+	<dl dfn-type=value dfn-for=animation-iteration-count>
+		<dt><dfn>infinite</dfn>
+		<dd>
+			The animation will repeat forever.
+
+		<dt><dfn><<number>></dfn>
+		<dd>
+			The animation will repeat the specified number of times.
+			If the number is not an integer,
+			the animation will end partway through its last cycle.
+			Negative numbers are invalid.
+
+			A value of ''0'' is valid and,
+			similar to an 'animation-duration' of ''0s'',
+			causes the animation to occur instantaneously.
+	</dl>
+
+
 <h3 id="animation-direction">
 The 'animation-direction' property</h3>
 
@@ -459,11 +503,6 @@ The 'animation-direction' property</h3>
 The 'animation-play-state' property</h3>
 
 	The 'animation-play-state' property defines whether the animation is running or paused.
-	A running animation can be paused by setting this property to ''paused''. To continue
-	running a paused animation this property can be set to ''running''. A paused animation will
-	continue to display the current value of the animation in a static state, as if the time
-	of the animation is constant. When a paused animation is resumed, it restarts from the
-	current value, not necessarily from the beginning of the animation.
 
 	<pre class='propdef'>
 	Name: animation-play-state
@@ -480,19 +519,28 @@ The 'animation-play-state' property</h3>
 
 	<dfn>&lt;single-animation-play-state></dfn> = running | paused
 
+	<dl dfn-type=value dfn-for=animation-play-state>
+		<dt><dfn>running</dfn>
+		<dd>
+			While this property is set to ''running'',
+			the animation proceeds as normal.
+
+		<dt><dfn>paused</dfn>
+		<dd>
+			While this property is set to ''paused'',
+			the animation is paused.
+			The animation continues to apply to the element with the progress it had made before being paused.
+			When unpaused (set back to ''running''),
+			it restarts from where it left off,
+			as if the "clock" that controls the animation had stopped and started again.
+	</dl>
+
 <h3 id="animation-delay">
 The 'animation-delay' property</h3>
 
 	The 'animation-delay' property defines when the animation will start. It allows an animation
-	to begin execution some time after it is applied. An 'animation-delay' value of ''0s'' means
-	the animation will execute as soon as it is applied. Otherwise, the value specifies an offset
-	from the moment the animation is applied, and the animation will delay execution by that offset.
-
-	If the value for 'animation-delay' is a negative time offset then the animation will execute the
-	moment it is applied, but will appear to have begun execution at the specified offset. That is,
-	the animation will appear to begin part-way through its play cycle. In the case where an animation
-	has implied starting values and a negative 'animation-delay', the starting values are taken from
-	the moment the animation is applied.
+	to begin execution some time after it is applied,
+	or to appear to have begun execution some time <em>before</em> it is applied.
 
 	<pre class='propdef'>
 	Name: animation-delay
@@ -507,6 +555,24 @@ The 'animation-delay' property</h3>
 	Canonical order: per grammar
 	</pre>
 
+	<dl>
+		<dt><dfn value for=animation-delay><<time>></dfn>
+		<dd>
+			The <<time>> defines how long of a delay there is between the start of the animation
+			(when the animation is applied to the element via these properties)
+			and when it begins executing.
+			A delay of ''0s'' (the initial value) means that the animation will execute as soon as it is applied.
+
+			A negative delay is <strong>valid</strong>.
+			Similar to a delay of ''0s'', it means that the animation executes immediately,
+			but is automatically progressed by the absolute value of the delay,
+			as if the animation had started the specified time in the past,
+			and so it appears to start partway through its play-cycle already.
+			If an animation's keyframes have an implied starting value,
+			the values are taken from the time the animation starts,
+			not some time in the past.
+	</dl>
+
 <h3 id="animation-fill-mode">
 The 'animation-fill-mode' property</h3>
 
@@ -515,26 +581,8 @@ The 'animation-fill-mode' property</h3>
 	values between the time it is applied (the ‘animation-name’ property is set on an
 	element) and the time it begins execution (which is determined by the 'animation-delay'
 	property). Also, by default an animation does not affect property values after the
-	animation ends (determined by the 'animation-duration' property). The 'animation-fill-mode'
-	property can override this behavior.
-
-	If the value for 'animation-fill-mode' is ''backwards'', then the animation will apply
-	the property values defined in the keyframe that will start the first iteration of the
-	animation, during the period defined by 'animation-delay'. These are either the values
-	of the ''from'' keyframe (when 'animation-direction' is ''normal'' or ''alternate'') or
-	those of the ''to'' keyframe (when 'animation-direction' is ''reverse'' or
-	''alternate-reverse'').
-
-	If the value for 'animation-fill-mode' is ''forwards'', then after the animation ends (as
-	determined by its 'animation-iteration-count'), the animation will apply the property values
-	for the time the animation ended. When 'animation-iteration-count' is an integer greater than
-	zero, the values applied will be those for the end of the last completed iteration of the
-	animation (rather than the values for the start of the iteration that would be next). When
-	'animation-iteration-count' is zero, the values applied will be those that would start the
-	first iteration (just as when 'animation-fill-mode' is ''backwards'').
-
-	If the value for 'animation-fill-mode' is ''both'', then the animation will follow the rules
-	for both ''forwards'' and ''backwards''. That is, it will extend the animation in both directions.
+	animation ends (determined by the 'animation-duration' and 'animation-iteration-count' properties).
+	The 'animation-fill-mode'property can override this behavior.
 
 	<pre class='propdef'>
 	Name: animation-fill-mode
@@ -551,6 +599,50 @@ The 'animation-fill-mode' property</h3>
 
 	<dfn>&lt;single-animation-fill-mode></dfn> = none | forwards | backwards | both
 
+	<dl dfn-type=value dfn-for=animation-fill-mode>
+		<dt><dfn>none</dfn>
+		<dd>
+			The animation has no effect when it is applied but not executing.
+
+		<dt><dfn>forwards</dfn>
+		<dd>
+			After the animation is done executing
+			(has played the number of times specified by its 'animation-iteration-count' value)
+			it continues to apply the values that it ended its last complete iteration with.
+			This will be the values specified or implied for either its ''100%'' or ''0%'' keyframe,
+			depending on the direction that the last complete iteration was executing in
+			(per 'animation-direction').
+			If the animation didn't complete an entire iteration
+			(if the iteration count was ''0'' or a value less than 1)
+			the values specified or implied for its ''0%'' keyframe are used.
+
+			Note: If 'animation-iteration-count' is a non-integer value,
+			the animation will stop executing partway through its animation cycle,
+			but a forwards fill will still apply the values of the ''100%'' keyframe,
+			not whatever values were being applied at the time the animation stopped executing.
+
+			Issue: Why does it ignore the progress made by a non-integer iteration count?
+
+			Issue: What happens with ''animation-duration: 0; animation-iteration-count: infinite;''?
+			The animation is instantaneous,
+			but there is no "last complete iteration".
+			In particular, you can't tell whether to use the 0% or 100% keyframe.
+
+		<dt><dfn>backwards</dfn>
+		<dd>
+			Before the animation has begun executing
+			(during the period specified by 'animation-delay'),
+			the animation applies the values that it will start the first iteration with.
+			If the 'animation-direction' is ''normal'' or ''alternate'',
+			the values specified or implied for its ''0%'' keyframe are used;
+			if the 'animation-direction' is ''reverse'' or ''alternate-reverse'',
+			the values specified or implied for its ''100%'' keyframe are used.
+
+		<dt><dfn>both</dfn>
+		<dd>
+			The effects of both ''forwards'' and ''backwards'' fill apply.
+	</dl>
+
 <h3 id="animation">
 The 'animation' shorthand property</h3>
 
@@ -560,7 +652,6 @@ The 'animation' shorthand property</h3>
 	properties have lists of different lengths, a problem that cannot occur when they are defined using
 	only the 'animation' shorthand.)
 
-
 	<pre class='propdef'>
 	Name: animation
 	Value: 	<<single-animation>>#
@@ -611,6 +702,9 @@ Animation Events</h2>
 	Any animation for which both a valid keyframe rule and a non-zero duration are defined will run
 	and generate events; this includes animations with empty keyframe rules.
 
+	Issue: This contradicts the 'animation-delay' section,
+	which says that a ''0s'' duration animation still fires events.
+
 	The time the animation has been running is sent with each event generated. This allows the event
 	handler to determine the current iteration of a looping animation or the current position of an
 	alternating animation. This time does not include any time the animation was in the ''paused''
@@ -791,8 +885,8 @@ Attributes</h4>
 <h4 id="interface-csskeyframesrule-appendrule">
 The <code>appendRule</code> method</h4>
 
-	 The <dfn method for="CSSKeyFramesRule">appendRule()</dfn> method appends the passed
-	 <a idl>CSSKeyframeRule</a> into the list at the passed key.
+	The <dfn method for="CSSKeyFramesRule">appendRule()</dfn> method appends the passed
+	<a idl>CSSKeyframeRule</a> into the list at the passed key.
 
 	Parameters: