From f44961c73b1b9ed916842935cefd0bd8073419c1 Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 29 Mar 2010 13:22:02 -0700 Subject: [PATCH] [Sass] More docs, including a changelog entry. --- doc-src/SASS_CHANGELOG.md | 108 +++++++++++++++++++++++++++++++++++--- doc-src/SASS_REFERENCE.md | 10 +++- 2 files changed, 111 insertions(+), 7 deletions(-) diff --git a/doc-src/SASS_CHANGELOG.md b/doc-src/SASS_CHANGELOG.md index 9bf30e75..87091078 100644 --- a/doc-src/SASS_CHANGELOG.md +++ b/doc-src/SASS_CHANGELOG.md @@ -8,6 +8,18 @@ ### Deprecations -- Must Read! {#3-0-0-deprecations} +* Using `=` for SassScript properties and variables is deprecated, + and will be removed in Sass 3.2. + Use `:` instead. + See also [this changelog entry](#3-0-0-sass-script-context) + +* Because of the above, property values using `:` + will be parsed more thoroughly than they were before. + Although all valid CSS3 properties + as well as most hacks and proprietary syntax should be supported, + it's possible that some properties will break. + If this happens, please report it to [the Sass mailing list](http://groups.google.com/group/haml). + * The `!` prefix for variables is deprecated, and will be removed in Sass 3.2. Use `$` as a prefix instead. @@ -15,6 +27,90 @@ ### Syntax Changes +#### SassScript Context +{#3-0-0-sass-script-context} + +The `=` character is no longer required for properties that use SassScript +(that is, variables and operations). +All properties now use SassScript automatically; +this means that `:` should be used instead. +Variables should also be set with `:`. +For example, what used to be + + .page + color = 5px + 9px + +should now be + + .page + color: 5px + 9px + +This means that SassScript is now an extension of the CSS3 property syntax. +All valid CSS3 properties are valid SassScript, +and will compile without modification +(some invalid properties work as well, such as Microsoft's proprietary `filter` syntax). +This entails a few changes to SassScript to make it fully CSS3-compatible, +which are detailed below. + +This also means that Sass will now be fully parsing all property values, +rather than passing them through unchanged to the CSS. +Although care has been taken to support all valid CSS3, +as well as hacks and proprietary syntax, +it's possible that a property that worked in Sass 2 won't work in Sass 3. +If this happens, please report it to [the Sass mailing list](http://groups.google.com/group/haml). + +Note that if `=` is used, +SassScript will be interpreted as backwards-compatibly as posssible. +In particular, the changes listed below don't apply in an `=` context. + +##### Quoted Strings + +Quoted strings (e.g. `"foo"`) in SassScript now render with quotes. +In addition, unquoted strings are no longer deprecated, +and render without quotes. +This means that almost all strings that had quotes in Sass 2 +should not have quotes in Sass 3. + +Although quoted strings render with quotes when used with `:`, +they do not render with quotes when used with `#{}`. +This allows quoted strings to be used for e.g. selectors +that are passed to mixins. + +##### Division and `/` + +Two numbers separated by a `/` character +are allowed as property syntax in CSS, +e.g. for the `font` property. +SassScript also uses `/` for division, however, +which means it must decide what to do +when it encounters numbers separated by `/`. + +For CSS compatibility, SassScript does not perform division by default. +However, division will be done in almost all cases where division is intended. +In particular, SassScript will perform division +in the following three situations: + +1. If the value, or any part of it, is stored in a variable. +2. If the value is surrounded by parentheses. +3. If the value is used as part of another arithmetic expression. + +For example: + + p + font: 10px/8px + $width: 1000px + width: $width/2 + height: (500px/2) + margin-left: 5px + 8px/2px + +is compiled to: + + p { + font: 10px/8px; + width: 500px; + height: 250px; + margin-left: 9px; } + #### Variable Prefix Character {#3-0-0-dollar-prefix} @@ -28,9 +124,9 @@ For example, what used to be should now be - $width = 13px + $width: 13px .icon - width = $width + width: $width The `sass-convert` command-line tool can be used to upgrade Sass files to the new syntax using the `--in-place` flag. @@ -51,9 +147,9 @@ SassScript variable and mixin names may now contain hyphens. In fact, they may be any valid CSS3 identifier. For example: - $prettiest-color = #542FA9 + $prettiest-color: #542FA9 =pretty-text - color = $prettiest-color + color: $prettiest-color In order to allow frameworks like [Compass](http://compass-style.org) to use hyphens in variable names @@ -62,10 +158,10 @@ variables and mixins using hyphens may be referred to with underscores, and vice versa. For example: - $prettiest-color = #542FA9 + $prettiest-color: #542FA9 .pretty // Using an underscore instead of a hyphen works - color = $prettiest_color + color: $prettiest_color #### Single-Quoted Strings diff --git a/doc-src/SASS_REFERENCE.md b/doc-src/SASS_REFERENCE.md index e154becc..5ea57324 100644 --- a/doc-src/SASS_REFERENCE.md +++ b/doc-src/SASS_REFERENCE.md @@ -811,7 +811,7 @@ is compiled to: .item-2 { width: 4em; } -## SassScript +## SassScript {#sassscript} In addition to the plain CSS property syntax, Sass supports a small set of extensions called SassScript. @@ -875,6 +875,10 @@ Variables used to use the prefix character `!`; this still works, but it's deprecated and prints a warning. `$` is the recommended syntax. +Variables also used to be defined with `=` rather than `:`; +this still works, but it's deprecated and prints a warning. +`:` is the recommended syntax. + ### Data Types SassScript supports four main data types: @@ -922,6 +926,10 @@ is compiled to: body.firefox .header:before { content: "Hi, Firefox users!"; } +It's also worth noting that when using the [deprecated `=` property syntax](#sassscript), +all strings are interpreted as unquoted, +regardless of whether or not they're written with quotes. + ### Operations All types support equality operations (`==` and `!=`).