[css-values-4] Add some of the necessary details for new math functions. More coming.

Author: tabatkins

css-values-4/Overview.bs

@@ -357,21 +357,21 @@ Combining Values: Interpolation, Addition, and Accumulation</h2>
 	and <a href="https://www.w3.org/TR/css-animations/">animations</a>,
 	<dfn export>combine</dfn> two CSS property values.
 	The following combining operations--
-	on the two <a>computed values</a> <var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>
+	on the two <a>computed values</a> <var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>
 	yielding the <a>computed value</a> <var>V<sub>result</sub></var>--
 	are defined:
 
 	<dl export>
 		<dt><dfn id="interpolation" lt="interpolation | interpolate | value interpolation | interpolation procedure">interpolation</dfn>
 		<dd>
 			Given two property values
-			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>,
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>,
 			produces an intermediate value
 			<var>V<sub>result</sub></var>
 			at a distance of <var>p</var>
 			along the interval between
-			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>
-			such that <var>p</var> = 0 produces <var>V<sub>A</sub></var>
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>
+			such that <var>p</var> = 0 produces <var>V<sub>a</sub></var>
 			and <var>p</var> = 1 produces <var>V</var><sub>B</sub>.
 
 			The range of <var>p</var> is (&minus;&infin;, &infin;)
@@ -382,12 +382,12 @@ Combining Values: Interpolation, Addition, and Accumulation</h2>
 		<dt><dfn id="addition" lt="value addition | addition procedure" local-lt="add | addition">addition</dfn>
 		<dd>
 			Given two property values
-			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>,
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>,
 			returns the sum of the two properties,
 			<var>V</var><sub>result</sub>.
 			For addition that is not commutative
 			(for example, matrix multiplication)
-			<var>V<sub>A</sub></var> represents
+			<var>V<sub>a</sub></var> represents
 			the first term of the operation and
 			<var>V<sub>B</sub></var> represents
 			the second.
@@ -404,14 +404,14 @@ Combining Values: Interpolation, Addition, and Accumulation</h2>
 		<dt><dfn id="accumulation" lt="value accumulation | accumulation procedure" local-lt="accumulate | accumulation">accumulation</dfn>
 		<dd>
 			Given two property values
-			<var>V<sub>A</sub></var> and <var>V<sub>B</sub></var>,
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>,
 			returns the result, <var>V<sub>result</sub></var>,
 			of combining the two operands
 			such that <var>V<sub>B</sub></var>
-			is treated as a <em>delta</em> from <var>V<sub>A</sub></var>.
+			is treated as a <em>delta</em> from <var>V<sub>a</sub></var>.
 			For accumulation that is not commutative
 			(for example, accumulation of mismatched transform lists)
-			<var>V<sub>A</sub></var> represents the first term of the operation
+			<var>V<sub>a</sub></var> represents the first term of the operation
 			and <var>V<sub>B</sub></var> represents the second.
 
 			<div class="note">
@@ -439,7 +439,7 @@ Combining Values: Interpolation, Addition, and Accumulation</h2>
 	If a value type does not define a specific procedure for <a>addition</a>
 	or is defined as <dfn export>not additive</dfn>,
 	its <a>addition</a> operation is simply
-	<var>V<sub>result</sub></var> = <var>V<sub>B</sub></var>.
+	<var>V<sub>result</sub></var> = <var>V<sub>a</sub></var>.
 
 	If a value types does not define a specific procedure for <a>accumulation</a>,
 	its <a>accumulation</a> operation is identical to <a>addition</a>.
@@ -711,7 +711,7 @@ Relative URLs</h4>
 <h5 id='local-urls'>
 Fragment URLs</h5>
 
-	To work around some common eccentricities in browser URL handling,
+	To work around some common eccentriticites in browser URL handling,
 	CSS has special behavior for fragment-only urls.
 
 	If a ''url()''’s value starts with a U+0023 NUMBER SIGN (<code>#</code>) character,
@@ -758,7 +758,7 @@ Empty URLs</h4>
 
 	Note: This matches the behavior of empty urls for embedded resources elsewhere in the web platform,
 	and avoids excess traffic re-requesting the stylesheet or host document
-	due to editing mistakes leaving the ''url()'' value empty,
+	due to editting mistakes leaving the ''url()'' value empty,
 	which are almost certain to be invalid resources for whatever the ''url()'' shows up in.
 	Linking on the web platform <em>does</em> allow empty urls,
 	so if/when CSS gains some functionality to control hyperlinks,
@@ -1087,7 +1087,7 @@ Mixing Percentages and Dimensions</h3>
 <h4 id="combine-mixed">
 Combination of Percentage and Dimension Mixes</h4>
 
-	<a>Interpolation</a> of percentage-dimension value combinations
+	<a>Interpolation</a> of percengage-dimension value combinations
 	(e.g. <<length-percentage>>, <<frequency-percentage>>, <<angle-percentage>>, <<time-percentage>>
 	or equivalent notations)
 	is defined as
@@ -1220,7 +1220,7 @@ Font-relative Lengths: the ''em'', ''ex'', ''cap'', ''ch'', ''ic'', ''rem'', ''l
 	or, in the case of ''rem'' and ''rlh'', the metrics of the root element.
 
 	<figure>
-		<img src="images/Typography_Line_Terms.svg" alt="The word 'Sphinx' annotated with various font metrics: ascender height, to the top of the h's serif; cap height, to the visually approximate top of the S; the x height, to the visually approximate top of the x; the baseline, along the bottom of S, h, i, n, and x; and the descender height, to the bottom of the p.">
+		<img src="images/Typography_Line_Terms.svg" alt="The word 'Sphinx' annotated with various font metrics: ascender height, to the top of the h's serif; cap height, to the visually approximate top of the S; the x height, to the visually approximate top of the x; the baseline, along the bottom of S, h, i, n, and x; and the descender height, to the bottom fo the p.">
 		<figcaption>
 			Common typographic metrics
 		</figcaption>
@@ -2472,7 +2472,7 @@ Basic Arithmetic: ''calc()''</h3>
 		}
 		</pre>
 
-		Although '--ar' <em>could</em> have been written as simply
+		Altho '--ar' <em>could</em> have been written as simply
 		''--ar: (16 / 9);'',
 		'--w' is used both on its own (in 'width')
 		and as a ''calc()'' component (in '--h'),
@@ -3035,7 +3035,7 @@ Syntax</h3>
 
 	In addition, [=whitespace=]
 	is required on both sides of the <css>+</css> and <css>-</css> operators.
-	(The <css>*</css> and <css>/</css> operators can be used without white space around them.)
+	(The <css>*</css> and <css>/</css> operaters can be used without white space around them.)
 
 	Several of the math functions above have additional constraints
 	on what their <<calc-sum>> arguments can contain.
@@ -3273,12 +3273,202 @@ Type Checking</h3>
 	and ''width: 5px;''
 	are valid.
 
-	Note: Although there are a few properties in which a bare <<number>>
+	Note: Altho there are a few properties in which a bare <<number>>
 	becomes a <<length>> at used-value time
 	(specifically, 'line-height' and 'tab-size'),
 	<<number>>s never become "length-like" in ''calc()''.
 	They always stay as <<number>>s.
 
+<h3 id='calc-internal'>
+Internal Representation</h3>
+
+	The [=internal representation=] of a [=math function=]
+	is a <dfn export>calculation tree</dfn>:
+	a tree of operator nodes,
+	such as Sum, Product, Min, or Cos,
+	with plain values
+	(numeric values, such as numbers, dimensions, and percentages,
+	and non-math functions that resolve to a numeric type) at the leaves.
+	[=Math functions=] are turned into [=calculation trees=]
+	depending on the function:
+
+	<dl class=switch>
+		: calc()
+		:: The [=internal representation=] of a ''calc()'' function
+			is the result of [=parsing a calculation=] from its argument.
+		: any other [=math function=]
+		:: The [=internal representation=]
+			is an operator node with the same name as the function,
+			whose children are the result of [=parsing a calculation=]
+			from each of the function's arguments,
+			in the order they appear.
+	</dl>
+
+	<div algorithm>
+		To <dfn export lt="parse a calculation|parsing a calculation">parse a calculation</dfn>,
+		given a [=calculation=] |values|
+		represented as a list of [=component values=],
+		and returning a tree of operator nodes:
+
+		1. Discard any <<whitespace-token>>s from |values|.
+
+		2. An item in |values| is an “operator”
+			if it's a <<delim-token>> with the value "+", "-", "*", or "/".
+			Otherwise, it's a “value”.
+
+		3. Collect children into Product and Invert nodes.
+
+			For every consecutive run of value items in |values|
+			separated by "*" or "/" operators:
+
+			1. For each "/" operator in the run,
+				replace its right-hand value item |rhs|
+				with an Invert node containing |rhs| as its child.
+
+			2. Replace the entire run with a Product node
+				containing the value items of the run as its children.
+
+		4. Collect children into Sum and Negate nodes.
+
+			1. For each "-" operator item in |values|,
+				replace its right-hand value item |rhs|
+				with a Negate node containing |rhs| as its child.
+
+			2. If |values| has only one item,
+				and it is a Product node
+				or a parenthesized [=simple block=],
+				replace |values| with that item.
+
+				Otherwise,
+				replace |values| with a Sum node
+				containing the value items of |values| as its children.
+
+
+		5. At this point |values| is
+			a tree of Sum, Product, Negate, and Invert nodes,
+			with other types of values at the leaf nodes.
+			Process the leaf nodes.
+
+			For every leaf node |leaf| in |values|:
+
+			1. If |leaf| is a parenthesized [=simple block=],
+				replace |leaf|
+				with the result of [=parsing a calculation=] from |leaf|’s contents.
+
+			2. If |leaf| is a [=math function=],
+				replace |leaf| with the [=internal representation=] of that math function.
+
+		6. Return the result of [=simplifying a calculation tree=] from |values|.
+	</div>
+
+<h4 id='calc-simplification'>
+Simplification</h4>
+
+	[=Internal representations=] of [=math functions=] are eagerly simplified to the extent possible,
+	using standard algebraic simplifications
+	(distributing multiplication over sums,
+	combining similar units,
+	etc.).
+
+	<div algorithm>
+		To <dfn export local-lt="simplify" lt="simplify a calculation tree|simplifying a calculation tree">simplify a calculation tree</dfn> |root|:
+
+		1. If |root| is a numeric value:
+			1. If |root| is a percentage that will be resolved against another value,
+				and there is enough information available to resolve it,
+				do so,
+				and express the resulting numeric value
+				in the appropriate [=canonical unit=].
+				Return the value.
+
+			2. If |root| is a dimension
+				that is not expressed in its [=canonical unit=],
+				and there is enough information available to convert it to the [=canonical unit=],
+				do so,
+				and return the value.
+
+			3. Otherwise, return |root|.
+
+		2. If |root| is any other leaf node
+			(not an operator node):
+
+			1. If there is enough information available to determine its numeric value,
+				return its value,
+				expressed in the value's [=canonical unit=].
+			2. Otherwise, return |root|.
+
+		2. At this point, |root| is an operator node.
+			[=Simplify=] all the children of |root|.
+
+		3. If |root| is a
+			Min, Max, Clamp,
+			Sin, Cos, Tan,
+			Asin, Acos, Atan, Atan2,
+			Pow, Sqrt, or Hypot node,
+			and all of its children are numeric values
+			with enough information to computed the operation |root| represents,
+			return the result of running |root|'s operation
+			using its children,
+			expressed in the result's [=canonical unit=].
+
+		4. If |root| is a Negate node:
+
+			1. If |root|'s child is a numeric value,
+				return an equivalent numeric value,
+				but with the value negated
+				(0 - value).
+			2. If |root|'s child is a Negate node,
+				return the child's child.
+			3. Return |root|.
+
+		5. If |root| is an Invert node:
+
+			1. If |root|'s child is a number
+				(not a percentage or dimension)
+				return the reciprocal of the child's value.
+			2. If |root|'s child is an Invert node,
+				return the child's child.
+			3. Return |root|.
+
+		6. If |root| is a Sum node:
+
+			1. For each set of |root|'s children
+				that are numeric values with identical units,
+				remove those children
+				and replace them with a single numeric value
+				containing the sum of the removed nodes,
+				and with the same unit.
+
+				(E.g. combine numbers, combine percentages,
+				combine px values, etc.)
+
+			2. If |root| has only a single child at this point,
+				return the child.
+				Otherwise, return |root|.
+
+		7. If |root| is a Product node:
+
+			1. If |root| has multiple children that are numbers
+				(not percentages or dimensions),
+				remove them and replace them with a single number
+				containing the product of the removed nodes.
+
+			2. If |root| contains only numeric values
+				and/or Invert nodes containing numeric values,
+				and [=multiply two types|multiplying the types=]
+				of all the children
+				(noting that the type of an Invert node
+				is the [=invert a type|inverse=] of its child's type)
+				results in a type that [=CSSNumericValue/matches=]
+				any of the types that a [=math function=] can resolve to,
+				return the result of multiplying all the values of the children
+				(noting that the value of an Invert node
+				is the reciprocal of its child's value),
+				expressed in the result's [=canonical unit=].
+
+			3. Return |root|.
+	</div>
+
 <h3 id='calc-computed-value'>
 Computed Value</h3>
 
@@ -3591,7 +3781,7 @@ Registration for the <code>about:invalid</code> URL scheme</h3>
 			<th>Intended Usage
 			<td>
 				The <code>about:invalid</code> URL references a non-existent document with a generic error condition.
-				It can be used when a URL is necessary, but the default value shouldn't be resolvable as any type of document.
+				It can be used when a URL is necessary, but the default value shouldn't be resolveable as any type of document.
 		<tr>
 			<th>Contact/Change controller
 			<td>CSS WG &lt;<a href="mailto:www-style@w3.org">www-style@w3.org</a>> (on behalf of W3C)
@@ -3663,4 +3853,4 @@ Security and Privacy Considerations</h2>
 	This specification defines units that expose the user's screen size
 	and default font size,
 	but both are trivially observable from JS,
-	so they do not constitute a new privacy risk.
+	so they do not constitutate a new privacy risk.