Merge pull request sass#61 from oddbird/port-docs-values

Porting Documentation - Values and Operators

source/_includes/doc_snippets/number-units.liquid

@@ -0,0 +1,157 @@
+{% markdown %}
+  ## Units
+
+  Sass has powerful support for manipulating units based on how [real-world unit
+  calculations][] work. When two numbers are multiplied, their units are
+  multiplied as well. When one number is divided by another, the result takes
+  its numerator units from the first number and its denominator units from the
+  second. A number can have any number of units in the numerator and/or
+  denominator.
+
+  [real-world unit calculations]: https://en.wikipedia.org/wiki/Unit_of_measurement#Calculations_with_units_of_measurement
+{% endmarkdown %}
+
+{% codeExample 'number-units', false %}
+  @debug 4px * 6px; // 24px*px (read "square pixels")
+  @debug math.div(5px, 2s); // 2.5px/s (read "pixels per second")
+
+  // 3.125px*deg/s*em (read "pixel-degrees per second-em")
+  @debug 5px * math.div(math.div(30deg, 2s), 24em);
+
+  $degrees-per-second: math.div(20deg, 1s);
+  @debug $degrees-per-second; // 20deg/s
+  @debug math.div(1, $degrees-per-second); // 0.05s/deg
+  ===
+  @debug 4px * 6px  // 24px*px (read "square pixels")
+  @debug math.div(5px, 2s)  // 2.5px/s (read "pixels per second")
+
+  // 3.125px*deg/s*em (read "pixel-degrees per second-em")
+  @debug 5px * math.div(math.div(30deg, 2s), 24em)
+
+  $degrees-per-second: math.div(20deg, 1s)
+  @debug $degrees-per-second  // 20deg/s
+  @debug math.div(1, $degrees-per-second)  // 0.05s/deg
+{% endcodeExample %}
+
+{% headsUp %}
+  Because CSS doesn't support complex units like square pixels, using a number
+  with complex units as a [property value][] will produce an error. This is a
+  feature in disguise, though; if you aren't ending up with the right unit, it
+  usually means that something's wrong with your calculations! And remember, you
+  can always use the [`@debug` rule][] to check out the units of any variable or
+  [expression][].
+
+  [property value]: /documentation/style-rules/declarations
+  [`@debug` rule]: /documentation/at-rules/debug
+  [expression]: /documentation/syntax/structure#expressions
+{% endheadsUp %}
+
+{% markdown %}
+  Sass will automatically convert between compatible units, although which unit
+  it will choose for the result depends on which implementation of Sass you're
+  using.If you try to combine incompatible units, like `1in + 1em`, Sass will
+  throw an error.
+{% endmarkdown %}
+
+{% codeExample 'compatible-units', false %}
+  // CSS defines one inch as 96 pixels.
+  @debug 1in + 6px; // 102px or 1.0625in
+
+  @debug 1in + 1s;
+  //     ^^^^^^^^
+  // Error: Incompatible units s and in.
+  ===
+  // CSS defines one inch as 96 pixels.
+  @debug 1in + 6px  // 102px or 1.0625in
+
+  @debug 1in + 1s
+  //     ^^^^^^^^
+  // Error: Incompatible units s and in.
+{% endcodeExample %}
+
+{% markdown %}
+  As in real-world unit calculations, if the numerator contains units that are
+  compatible with units in the denominator (like `math.div(96px, 1in)`), they'll
+  cancel out. This makes it easy to define a ratio that you can use for
+  converting between units. In the example below, we set the desired speed to
+  one second per 50 pixels, and then multiply that by the number of pixels the
+  transition covers to get the time it should take.
+{% endmarkdown %}
+
+{% comment -%}
+  TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass
+{%- endcomment -%}
+
+{% codeExample 'transition' %}
+  $transition-speed: math.div(1s, 50px);
+
+  @mixin move($left-start, $left-stop) {
+    position: absolute;
+    left: $left-start;
+    transition: left ($left-stop - $left-start) * $transition-speed;
+
+    &:hover {
+      left: $left-stop;
+    }
+  }
+
+  .slider {
+    @include move(10px, 120px);
+  }
+  ===
+  $transition-speed: math.div(1s, 50px)
+
+  @mixin move($left-start, $left-stop)
+    position: absolute
+    left: $left-start
+    transition: left ($left-stop - $left-start) * $transition-speed
+
+    &:hover
+      left: $left-stop
+
+
+
+  .slider
+    @include move(10px, 120px)
+  ===
+  .slider {
+    position: absolute;
+    left: 10px;
+    transition: left 2.2s;
+  }
+  .slider:hover {
+    left: 120px;
+  }
+{% endcodeExample %}
+
+{% headsUp %}
+  If your arithmetic gives you the wrong unit, you probably need to check your
+  math. You may be leaving off units for a quantity that should have them!
+  Staying unit-clean allows Sass to give you helpful errors when something isn't
+  right.
+
+  You should especially avoid using interpolation like `#{$number}px`. This
+  doesn't actually create a number! It creates an [unquoted string][] that
+  *looks* like a number, but won't work with any [number operations][] or
+  [functions][]. Try to make your math unit-clean so that `$number` already has
+  the unit `px`, or write `$number * 1px`.
+
+  [unquoted string]: /documentation/values/strings#unquoted
+  [number operations]: /documentation/operators/numeric
+  [functions]: /documentation/modules/math
+{% endheadsUp %}
+
+{% headsUp %}
+  Percentages in Sass work just like every other unit. They are *not*
+  interchangeable with decimals, because in CSS decimals and percentages mean
+  different things. For example, `50%` is a number with `%` as its unit, and
+  Sass considers it different than the number `0.5`.
+
+  You can convert between decimals and percentages using unit arithmetic.
+  `math.div($percentage, 100%)` will return the corresponding decimal, and
+  `$decimal * 100%` will return the corresponding percentage. You can also use
+  the [`math.percentage()` function][] as a more explicit way of writing
+  `$decimal * 100%`.
+
+  [`math.percentage()` function]: /documentation/modules/math#percentage
+{% endheadsUp %}

source/documentation/at-rules/import.liquid

@@ -386,7 +386,7 @@ introduction: >
   [plain CSS `@import`]: #plain-css-imports
 {% endmarkdown %}
 
-{% codeExample %}
+{% codeExample 'import-css' %}
   // code.css
   code {
     padding: .25em;

source/documentation/operators/boolean.liquid

@@ -0,0 +1,37 @@
+---
+title: Boolean Operators
+introduction: >
+  Unlike languages like JavaScript, Sass uses words rather than symbols for its
+  [boolean](/documentation/values/booleans) operators.
+---
+
+{% markdown %}
+  * `not <expression>` returns the opposite of the expression's value: it turns
+    `true` into `false` and `false` into `true`.
+  * `<expression> and <expression>` returns `true` if *both* expressions' values
+    are `true`, and `false` if either is `false`.
+  * `<expression> or <expression>` returns `true` if *either* expression's value
+    is `true`, and `false` if both are `false`.
+{% endmarkdown %}
+
+{% codeExample 'boolean', false %}
+  @debug not true; // false
+  @debug not false; // true
+
+  @debug true and true; // true
+  @debug true and false; // false
+
+  @debug true or false; // true
+  @debug false or false; // false
+  ===
+  @debug not true  // false
+  @debug not false  // true
+
+  @debug true and true  // true
+  @debug true and false  // false
+
+  @debug true or false  // true
+  @debug false or false  // false
+{% endcodeExample %}
+
+{% render 'doc_snippets/truthiness-and-falsiness' %}

source/documentation/operators/equality.liquid

@@ -0,0 +1,111 @@
+---
+title: Equality Operators
+---
+
+{% compatibility 'dart: true', 'libsass: false', 'ruby: "4.0.0 (unreleased)"', 'feature: "Unitless Equality"'%}
+  LibSass and older versions of Ruby Sass consider numbers without units to be
+  equal to the same numbers with any units. This behavior was deprecated and has
+  been removed from more recently releases because it violates [transitivity][].
+
+  [transitivity]: https://en.wikipedia.org/wiki/Transitive_relation
+{% endcompatibility %}
+
+{% markdown %}
+  The equality operators return whether or not two values are the same. They're
+  written `<expression> == <expression>`, which returns whether two
+  [expressions][] are equal, and `<expression> != <expression>`, which returns
+  whether two expressions are *not* equal. Two values are considered equal if
+  they're the same type *and* the same value, which means different things for
+  different types:
+
+  [expressions]: /documentation/syntax/structure#expressions
+
+  * [Numbers][] are equal if they have the same value *and* the same units, or
+    if their values are equal when their units are converted between one
+    another.
+  * [Strings][] are unusual in that [unquoted][] and [quoted][] strings with the
+    same contents are considered equal.
+  * [Colors][] are equal if they have the same red, green, blue, and alpha
+    values.
+  * [Lists][] are equal if their contents are equal. Comma-separated lists
+    aren't equal to space-separated lists, and bracketed lists aren't equal to
+    unbracketed lists.
+  * [Maps][] are equal if their keys and values are both equal.
+  * [Calculations] are equal if their names and arguments are all equal.
+    Operation arguments are compared textually.
+  * [`true`, `false`][], and [`null`][] are only equal to themselves.
+  * [Functions][] are equal to the same function. Functions are compared *by
+    reference*, so even if two functions have the same name and definition
+    they're considered different if they aren't defined in the same place.
+
+  [Numbers]: /documentation/values/numbers
+  [Strings]: /documentation/values/strings
+  [quoted]: /documentation/values/strings#quoted
+  [unquoted]: /documentation/values/strings#unquoted
+  [Colors]: /documentation/values/colors
+  [Lists]: /documentation/values/lists
+  [`true`, `false`]: /documentation/values/booleans
+  [`null`]: /documentation/values/null
+  [Maps]: /documentation/values/maps
+  [Calculations]: /documentation/values/calculations
+  [Functions]: /documentation/values/functions
+{% endmarkdown %}
+
+{% codeExample 'equality', false %}
+  @debug 1px == 1px; // true
+  @debug 1px != 1em; // true
+  @debug 1 != 1px; // true
+  @debug 96px == 1in; // true
+
+  @debug "Helvetica" == Helvetica; // true
+  @debug "Helvetica" != "Arial"; // true
+
+  @debug hsl(34, 35%, 92.1%) == #f2ece4; // true
+  @debug rgba(179, 115, 153, 0.5) != rgba(179, 115, 153, 0.8); // true
+
+  @debug (5px 7px 10px) == (5px 7px 10px); // true
+  @debug (5px 7px 10px) != (10px 14px 20px); // true
+  @debug (5px 7px 10px) != (5px, 7px, 10px); // true
+  @debug (5px 7px 10px) != [5px 7px 10px]; // true
+
+  $theme: ("venus": #998099, "nebula": #d2e1dd);
+  @debug $theme == ("venus": #998099, "nebula": #d2e1dd); // true
+  @debug $theme != ("venus": #998099, "iron": #dadbdf); // true
+
+  @debug true == true; // true
+  @debug true != false; // true
+  @debug null != false; // true
+
+  @debug get-function("rgba") == get-function("rgba"); // true
+  @debug get-function("rgba") != get-function("hsla"); // true
+  ===
+  @debug 1px == 1px  // true
+  @debug 1px != 1em  // true
+  @debug 1 != 1px  // true
+  @debug 96px == 1in  // true
+
+  @debug "Helvetica" == Helvetica  // true
+  @debug "Helvetica" != "Arial"  // true
+
+  @debug hsl(34, 35%, 92.1%) == #f2ece4  // true
+  @debug rgba(179, 115, 153, 0.5) != rgba(179, 115, 153, 0.8)  // true
+
+  @debug (5px 7px 10px) == (5px 7px 10px)  // true
+  @debug (5px 7px 10px) != (10px 14px 20px)  // true
+  @debug (5px 7px 10px) != (5px, 7px, 10px)  // true
+  @debug (5px 7px 10px) != [5px 7px 10px]  // true
+
+  $theme: ("venus": #998099, "nebula": #d2e1dd)
+  @debug $theme == ("venus": #998099, "nebula": #d2e1dd)  // true
+  @debug $theme != ("venus": #998099, "iron": #dadbdf)  // true
+
+  @debug calc(10px + 10%) == calc(10px + 10%)  // true
+  @debug calc(10% + 10px) == calc(10px + 10%)  // false
+
+  @debug true == true  // true
+  @debug true != false  // true
+  @debug null != false  // true
+
+  @debug get-function("rgba") == get-function("rgba")  // true
+  @debug get-function("rgba") != get-function("hsla")  // true
+{% endcodeExample %}