From fe806e33bc295d61a4ae0e8dd2e9d41fb0c2891e Mon Sep 17 00:00:00 2001
From: Pamela Lozano De La Garza <pamelalozano@google.com>
Date: Mon, 7 Aug 2023 14:09:32 -0700
Subject: [PATCH] Final review corrections

---
 .../breaking-changes/abs-percent.md           |   2 +-
 .../documentation/breaking-changes/index.md   |   4 +
 source/documentation/values/calculations.md   | 191 ++++++++++--------
 3 files changed, 113 insertions(+), 84 deletions(-)

diff --git a/source/documentation/breaking-changes/abs-percent.md b/source/documentation/breaking-changes/abs-percent.md
index eced0d0..d1aedde 100644
--- a/source/documentation/breaking-changes/abs-percent.md
+++ b/source/documentation/breaking-changes/abs-percent.md
@@ -17,5 +17,5 @@ function. Therefore if the value of `10%` represented `-50px`, `abs(10%)` would
 return `-10%` which in the browser would be `50px`.
 
 For this reason, we are deprecating the global abs() function with a percentage.
-To preserve the current behavior, use `math.abs()` or `abs(#{})` instead.
+To preserve the current behavior, use `math.abs()` instead.
 
diff --git a/source/documentation/breaking-changes/index.md b/source/documentation/breaking-changes/index.md
index 09985f3..3ab76a5 100644
--- a/source/documentation/breaking-changes/index.md
+++ b/source/documentation/breaking-changes/index.md
@@ -22,6 +22,10 @@ time-sensitive, so they may be released with new minor version numbers instead.
 
 These breaking changes are coming soon or have recently been released:
 
+* [Passing a percentage unit to the global `abs()` is
+  deprecated](/documentation/breaking-changes/abs-percent/) beginning in Dart
+  Sass 1.65.0.
+
 * [Passing `null` as an alpha channel to `new SassColor()` is changing
   behavior](/documentation/breaking-changes/null-alpha) beginning in Dart
   Sass 1.64.3.
diff --git a/source/documentation/values/calculations.md b/source/documentation/values/calculations.md
index 6f25143..bfe7c22 100644
--- a/source/documentation/values/calculations.md
+++ b/source/documentation/values/calculations.md
@@ -6,7 +6,7 @@ introduction: >
   much as possible, even if they're combined with one another.
 ---
 
-{% compatibility 'dart: "1.40.0"','libsass: false', 'ruby: false'%}
+{% compatibility 'dart: "1.40.0"', 'libsass: false', 'ruby: false' %}
   LibSass, Ruby Sass, and versions of Dart Sass prior to 1.40.0 parse `calc()`
   as a [special function] like `element()`.
 
@@ -158,24 +158,27 @@ CSS to unitless numbers:
 
 ## Calculation Functions
 
-{% compatibility 'dart: "1.64.0"', 'libsass: false', 'ruby: false', 'feature: "Special function syntax"' %}
-  LibSass, Ruby Sass, and versions of Dart Sass subsequent to 1.64.0 support the
-  following calculation functions, with the exception of `min()`, `max()`, and
-  `clamp()`.
+{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false', 'feature: "Additional functions"' %}
+  Versions of Dart Sass subsequent to 1.65.0 handle the execution of these
+  calculation functions: `round()`, `mod()`, `rem()`, `sin()`, `cos()`, `tan()`,
+  `asin()`, `acos()`, `atan()`, `atan2()`, `pow()`, `sqrt()`, `hypot()`,
+  `log()`, `exp()`, `abs()`, and `sign()`.
 {% endcompatibility %}
 
 Sass parses the following functions as [calculations]:
 * Comparison Functions: [`min()`], [`max()`], and [`clamp()`]
 * Stepped Value Functions: [`round()`], [`mod()`], and [`rem()`].
-* Trigonometric Functions: [`sin()`], [`cos()`], [`tan()`], [`asin()`], [`acos()`], [`atan()`], and [`atan2()`].
+* Trigonometric Functions: [`sin()`], [`cos()`], [`tan()`], [`asin()`], [`acos()`],
+  [`atan()`], and [`atan2()`].
 * Exponential Functions: [`pow()`], [`sqrt()`], [`hypot()`], [`log()`], and [`exp()`].
 * Sign-Related Functions: [`abs()`] and [`sign()`].
 
 [calculations]: https://www.w3.org/TR/css-values-4/#math
-[`min()`]: #min-and-max
-[`max()`]: #min-and-max
-[`clamp()`]: /documentation/modules/math/#clamp
-[`round()`]: #round
+[`min()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/min
+[`max()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/max
+[`clamp()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/clamp
+[`round()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/round
+[`abs()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs
 [`sin()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/sin
 [`cos()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/cos
 [`tan()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/tan
@@ -187,7 +190,6 @@ Sass parses the following functions as [calculations]:
 [`sqrt()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/sqrt
 [`hypot()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/hypot
 [`log()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/log
-[`abs()`]: #abs
 [`exp()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/exp
 [`mod()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/mod
 [`rem()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/rem
@@ -201,18 +203,17 @@ CSS added support for [mathematical expressions] in Values and Units Level
 those existing stylesheets. This led to the need for extra-special syntactic
 cleverness.
 
-[`min()` and `max()` functions]: https://www.w3.org/TR/css-values-4/#math
-[to support the iPhoneX]: https://webkit.org/blog/7929/designing-websites-for-iphone-x/
+[mathematical expressions]: https://www.w3.org/TR/css-values-4/#math
 [`round()`]: ../modules/math#round
 [`abs()`]: ../modules/math#abs
 [`min()`]: ../modules/math#min
 [`max()`]: ../modules/math#max
 
-If a calculation function call is a valid calculation expression, it will
-be parsed as a calculation. But as soon as any part of the call contains a
-SassScript feature that isn't supported in a calculation, like the [modulo
-operator], it's parsed as a call to the appropriate Sass math function
-instead.
+If a call to `round()`, `abs()`, `min()`, or `max()` is a valid calculation
+expression, it will be parsed as a calculation. But as soon as any part of the
+call contains a SassScript feature that isn't supported in a calculation, like
+the [modulo operator], it's parsed as a call to the appropriate Sass math
+function instead.
 
 Since calculations are simplified to numbers when possible anyway, the only
 substantive difference is that the Sass functions only support units that can be
@@ -220,7 +221,27 @@ combined at build time, so `min(12px % 10, 10%)` will throw an error.
 
 [modulo operator]: /documentation/operators/numeric/
 
+{% headsUp %}
+  Other calculations don't allow unitless numbers to be added to, subtracted
+  from, or compared to numbers with units. [`min()`], [`max()`], [`abs()`] and
+  [single-argument `round()`] are different, though: for backwards-compatibility
+  with the global Sass legacy functions which allow unit/unitless mixing for
+  historical reasons, these units can be mixed as long as they're contained
+  directly within a `min()`, `max()`, `abs()`, or single-argument `round()`
+  calculation.
+
+  For instance, `min(5 + 10px, 20px)` will result in `15px`. However
+  `sqrt(5 + 10px)` will throw an error, as `sqrt(5 + 10px)` was never a global
+  Sass function, and these are incompatible units.
+
+[single-argument `round()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/round
+[`abs()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs
+[`min()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/min
+[`max()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/max
+{% endheadsUp %}
+
 #### `min()` and `max()`
+
 {% compatibility 'dart: ">=1.11.0 <1.42.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
   LibSass, Ruby Sass, and versions of Dart Sass prior to 1.11.0 *always* parse
   `min()` and `max()` as Sass functions. To create a plain CSS `min()` or
@@ -243,32 +264,13 @@ combined at build time, so `min(12px % 10, 10%)` will throw an error.
   was backwards-incompatible with the global `min()` and `max()` functions, so
   that behavior was reverted.
 
+  [`min()` and `max()` functions]: https://www.w3.org/TR/css-values-4/#math
+  [to support the iPhoneX]: https://webkit.org/blog/7929/designing-websites-for-iphone-x/
   [special functions]: /documentation/syntax/special-functions/
 {% endcompatibility %}
 
-{% headsUp %}
-  Other calculations don't allow unitless numbers to be added to, subtracted
-  from, or compared to numbers with units. [`min()`] and [`max()`] are different,
-  though: for backwards-compatibility with the global Sass `min()` and `max()`
-  functions which allow unit/unitless mixing for historical reasons, these units
-  can be mixed as long as they're contained directly within a `min()` or `max()`
-  calculation.
-
-  For instance, `min(5 + 10px, 20px)` will result in `15px`. However
-  `sqrt(5 + 10px)` will throw an error, as `sqrt(5 + 10px)` was never a global
-  Sass function, and these are incompatible units.
-{% endheadsUp %}
-
-[`min()`] and [`max()`] functions take one or more comma-separated expressions
-as parameters.
-
-[`min()`]: https://sass-lang.com/documentation/modules/math#min
-[`max()`]: https://sass-lang.com/documentation/modules/math#max
-
 {% codeExample 'min-max' %}
   $padding: 12px;
-  $number: 12.5px;
-  $step: 15px;
 
   .post {
     // Since these max() calls are valid calculation expressions, they're
@@ -284,22 +286,8 @@ as parameters.
     padding-right: max($padding % 10, 20px);
   }
 
-  .post-image {
-    // Since these round() calls are valid calculation expressions, they're
-    // parsed as calculations.
-    padding-left: round(nearest, $number, $step);
-    padding-right: round($number + 10px);
-    padding-bottom: round($number + 10px, $step + 10%);
-  }
-
-  .card {
-    padding-left: abs(-10px);
-    padding-right: math.abs(-7.5%);
-  }
   ===
   $padding: 12px
-  $number: 12.5px
-  $step: 15px
 
   .post
     // Since these max() calls are valid calculation expressions, they're
@@ -314,16 +302,6 @@ as parameters.
     padding-left: max($padding % 10, 20px)
     padding-right: max($padding % 10, 20px)
 
-  .post-image
-    // Since these round() calls are valid calculation expressions, they're
-    // parsed as calculations.
-    padding-left: round(nearest, $number, $step)
-    padding-right: round($number + 10px)
-    padding-bottom: round($number + 10px, $step + 10%)
-
-  .card
-    padding-left: abs(-10px)
-    padding-right: math.abs(-7.5%)
   ===
   .post {
     padding-left: max(12px, env(safe-area-inset-left));
@@ -334,23 +312,12 @@ as parameters.
     padding-left: 20px;
     padding-right: 20px;
   }
-
-  .post-image {
-    padding-left: 15px;
-    padding-right: 23px;
-    padding-bottom: round(22.5px, 15px + 10%);
-  }
-
-  .card {
-    padding-left: 10px;
-    padding-right: 7.5%;
-  }
 {% endcodeExample %}
 
 #### `round()`
 
-{% compatibility 'dart: "1.64.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
-  LibSass, Ruby Sass, and versions of Dart Sass prior to 1.64.0 *always* parse
+{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
+  LibSass, Ruby Sass, and versions of Dart Sass prior to 1.65.0 *always* parse
   `round()` as a Sass function. To create a plain CSS calculation for those
   implementations, you can write something like
   `round(#{$strategy, $number, $step})` instead.
@@ -362,22 +329,80 @@ should be `nearest`, `up`, `down`, or `to-zero`.
 
 [`round(<strategy>, number, step)`]: https://developer.mozilla.org/en-US/docs/Web/CSS/round#parameter
 
+{% codeExample 'round' %}
+  $number: 12.5px;
+  $step: 15px;
+
+  .post-image {
+    // Since these round() calls are valid calculation expressions, they're
+    // parsed as calculations.
+    padding-left: round(nearest, $number, $step);
+    padding-right: round($number + 10px);
+    padding-bottom: round($number + 10px, $step + 10%);
+  }
+
+  ===
+  $number: 12.5px
+  $step: 15px
+
+  .post-image
+    // Since these round() calls are valid calculation expressions, they're
+    // parsed as calculations.
+    padding-left: round(nearest, $number, $step)
+    padding-right: round($number + 10px)
+    padding-bottom: round($number + 10px, $step + 10%)
+
+  ===
+  .post-image {
+    padding-left: 15px;
+    padding-right: 23px;
+    padding-bottom: round(22.5px, 15px + 10%);
+  }
+{% endcodeExample %}
+
 #### `abs()`
 
-{% compatibility 'dart: "1.64.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
-  LibSass, Ruby Sass, and versions of Dart Sass prior to 1.64.0 *always* parse
+{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
+  LibSass, Ruby Sass, and versions of Dart Sass prior to 1.65.0 *always* parse
   `abs()` as a Sass function. To create a plain CSS calculation for those
   implementations, you can write something like `abs(#{$number})` instead.
 {% endcompatibility %}
 
-{% headsUp %},
-The global `abs(value)` function compatibiliy with [% unit parameters is deprecated].
+{% headsUp %}
+The global `abs()` function compatibiliy with [% unit parameters is deprecated].
 In the future, this will emit a CSS abs() function to be resolved by the browser.
+
+[% unit parameters is deprecated]: /documentation/breaking-changes/abs-percent/
 {% endheadsUp %}
 
 The [`abs(value)`] takes in a single expressiona as a parameter and returns the
-absolute value of $value. If $value is negative, this returns -$value, and if
-$value is positive, it returns $value as-is.
+absolute value of `$value`. If `$value` is negative, this returns `-$value`, and if
+`$value` is positive, it returns `$value` as-is.
 
 [`abs(value)`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs
-[% unit parameters is deprecated]: /documentation/breaking-changes/abs-percent/
\ No newline at end of file
+
+{% codeExample 'abs' %}
+  .post-image {
+    // Since these abs() calls are valid calculation expressions, they're
+    // parsed as calculations.
+    padding-left: abs(10px);
+    padding-right: math.abs(-7.5%);
+    padding-top: abs(1 + 1px);
+  }
+
+  ===
+  .post-image
+    // Since these abs() calls are valid calculation expressions, they're
+    // parsed as calculations.
+    padding-left: abs(-10px)
+    padding-right: math.abs(-7.5%)
+    padding-top: abs(1 + 1px)
+
+  ===
+  .post-image {
+    padding-left: 10px;
+    padding-right: 7.5%;
+    padding-top: 2px;
+  }
+
+{% endcodeExample %}
\ No newline at end of file