radiantcms-couchrest_model 0.1.3 → 0.1.4

data/vendor/plugins/haml/doc-src/SASS_REFERENCE.md

@@ -3,56 +3,20 @@
 * Table of contents
 {:toc}
 
-Sass is an extension of CSS
-that adds power and elegance to the basic language.
-It allows you to use [variables](#variables_), [nested rules](#nested_rules),
-[mixins](#mixins), [inline imports](#import), and more,
-all with a fully CSS-compatible syntax.
-Sass helps keep large stylesheets well-organized,
-and get small stylesheets up and running quickly,
-particularly with the help of
-[the Compass style library](http://compass-style.org).
+Sass is a meta-language on top of CSS
+that's used to describe the style of a document
+cleanly and structurally,
+with more power than flat CSS allows.
+Sass both provides a simpler, more elegant syntax for CSS
+and implements various features that are useful
+for creating manageable stylesheets.
 
 ## Features
 
-* Fully CSS3-compatible
-* Language extensions such as variables, nesting, and mixins
-* Many {Sass::Script::Functions useful functions} for manipulating colors and other values
-* Advanced features like [control directives](#control_directives) for libraries
-* Well-formatted, customizable output
-* [Firebug integration](https://addons.mozilla.org/en-US/firefox/addon/103988)
-
-## Syntax
-
-There are two syntaxes available for Sass.
-The first, known as SCSS (Sassy CSS) and used throughout this reference,
-is an extension of the syntax of CSS3.
-This means that every valid CSS3 stylesheet
-is a valid SCSS file with the same meaning.
-In addition, SCSS understands most CSS hacks
-and vendor-specific syntax, such as [IE's old `filter` syntax](http://msdn.microsoft.com/en-us/library/ms533754%28VS.85%29.aspx).
-This syntax is enhanced with the Sass features described below.
-Files using this syntax have the `.scss` extension.
-
-The second and older syntax, known as the indented syntax (or sometimes just "Sass"),
-provides a more concise way of writing CSS.
-It uses indentation rather than brackets to indicate nesting of selectors,
-and newlines rather than semicolons to separate properties.
-Some people find this to be easier to read and quicker to write than SCSS.
-The indented syntax has all the same features,
-although some of them have slightly different syntax;
-this is described in {file:INDENTED_SYNTAX.md the indented syntax reference}.
-Files using this syntax have the `.sass` extension.
-
-Either syntax can [import](#import) files written in the other.
-Files can be automatically converted from one syntax to the other
-using the `sass-convert` command line tool:
-
-    # Convert Sass to SCSS
-    $ sass-convert style.sass style.scss
-
-    # Convert SCSS to Sass
-    $ sass-convert style.scss style.sass
+* Whitespace active
+* Well-formatted output
+* Elegant input
+* Feature-rich
 
 ## Using Sass
 
@@ -68,49 +32,37 @@ The first step for all of these is to install the Haml gem:
 
     gem install haml
 
-If you're using Windows,
-you may need to [install Ruby](http://rubyinstaller.org/download.html) first.
-
 To run Sass from the command line, just use
 
-    sass input.scss output.css
-
-You can also tell Sass to watch the file and update the CSS
-every time the Sass file changes:
-
-    sass --watch input.scss:output.css
-
-If you have a directory with many Sass files,
-you can also tell Sass to watch the entire directory:
-
-    sass --watch app/sass:public/stylesheets
+    sass input.sass output.css
 
 Use `sass --help` for full documentation.
+At the moment, the command-line tool doesn't support
+updating everything in a directory
+or automatically updating the CSS file when the Sass file changes.
+To do that, check out the [Compass](http://compass-style.org/) Sass framework.
 
 Using Sass in Ruby code is very simple.
 After installing the Haml gem,
 you can use it by running `require "sass"`
-and using {Sass::Engine} like so:
+and using Sass::Engine like so:
 
-    engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss)
+    engine = Sass::Engine.new("#main\n  background-color: #0000ff")
     engine.render #=> "#main { background-color: #0000ff; }\n"
 
 ### Rack/Rails/Merb Plugin
 
-To enable Sass in Rails versions before Rails 3,
-add the following line to `environment.rb`:
-
-    config.gem "haml"
+To enable Sass as a Rails plugin, run
 
-For Rails 3, instead add the following line to the Gemfile:
-
-    gem "haml"
+    haml --rails path/to/rails/app
 
 To enable Sass in Merb,
-add the following line to `config/dependencies.rb`:
+add
 
     dependency "merb-haml"
 
+to `config/dependencies.rb`.
+
 To enable Sass in a Rack application,
 add
 
@@ -122,10 +74,10 @@ to `config.ru`.
 Sass stylesheets don't work the same as views.
 They don't contain dynamic content,
 so the CSS only needs to be generated when the Sass file has been updated.
-By default, `.sass` and `.scss` files are placed in public/stylesheets/sass
+By default, ".sass" files are placed in public/stylesheets/sass
 (this can be customized with the [`:template_location`](#template_location-option) option).
 Then, whenever necessary, they're compiled into corresponding CSS files in public/stylesheets.
-For instance, public/stylesheets/sass/main.scss would be compiled to public/stylesheets/main.css.
+For instance, public/stylesheets/sass/main.sass would be compiled to public/stylesheets/main.css.
 
 ### Caching
 
@@ -152,44 +104,29 @@ in `environment.rb` in Rails or `config.ru` in Rack...
     Merb::Plugin.config[:sass][:style] = :compact
 
 ...or by passing an options hash to {Sass::Engine#initialize}.
-All relevant options are also available via flags
-to the `sass` command-line executable.
 Available options are:
 
 {#style-option} `:style`
 : Sets the style of the CSS output.
   See [Output Style](#output_style).
 
-{#syntax-option} `:syntax`
-: The syntax of the input file, `:sass` for the indented syntax
-  and `:scss` for the CSS-extension syntax.
-  This is only useful when you're constructing {Sass::Engine} instances yourself;
-  it's automatically set properly when using {Sass::Plugin}.
-  Defaults to `:sass`.
-
 {#property_syntax-option} `:property_syntax`
-: Forces indented-syntax documents to use one syntax for properties.
+: Forces the document to use one syntax for properties.
   If the correct syntax isn't used, an error is thrown.
   `:new` forces the use of a colon or equals sign
   after the property name.
   For example: `color: #0f3`
-  or `width: $main_width`.
+  or `width = !main_width`.
   `:old` forces the use of a colon
   before the property name.
   For example: `:color #0f3`
-  or `:width $main_width`.
+  or `:width = !main_width`.
   By default, either syntax is valid.
-  This has no effect on SCSS documents.
 
 {#cache-option} `:cache`
 : Whether parsed Sass files should be cached,
   allowing greater speed. Defaults to true.
 
-{#read_cache-option} `:read_cache`
-: If this is set and `:cache` is not,
-  only read the Sass cache if it exists,
-  don't write to it if it doesn't.
-
 {#never_update-option} `:never_update`
 : Whether the CSS files should never be updated,
   even if the template file changes.
@@ -202,7 +139,7 @@ Available options are:
   time a controller is accessed,
   as opposed to only when the template has been modified.
   Defaults to false.
-  Only has meaning within Rack, Ruby on Rails, or Merb.
+  Only has meaning within Rack, Ruby on Rails,x or Merb.
 
 {#always_check-option} `:always_check`
 : Whether a Sass template should be checked for updates every
@@ -235,11 +172,6 @@ Available options are:
   Note that if multiple template locations are specified, all
   of them are placed in the import path, allowing you to import
   between them.
-  **Note that due to the many possible formats it can take,
-  this option should only be set directly, not accessed or modified.
-  Use the {Sass::Plugin#template_location_array},
-  {Sass::Plugin#add_template_location},
-  and {Sass::Plugin#remove_template_location} methods instead**.
 
 {#css_location-option} `:css_location`
 : The path where CSS output should be written to.
@@ -255,8 +187,7 @@ Available options are:
 {#unix_newlines-option} `:unix_newlines`
 : If true, use Unix-style newlines when writing files.
   Only has meaning on Windows, and only when Sass is writing the files
-  (in Rack, Rails, or Merb, when using {Sass::Plugin} directly,
-  or when using the command-line executable).
+  (in Rack, Rails, or Merb, or when using {Sass::Plugin} directly).
 
 {#filename-option} `:filename`
 : The filename of the file being rendered.
@@ -277,92 +208,96 @@ Available options are:
 {#line_numbers-option} `:line_numbers`
 : When set to true, causes the line number and file
   where a selector is defined to be emitted into the compiled CSS
-  as a comment. Useful for debugging, especially when using imports
+  as a comment. Useful for debugging especially when using imports
   and mixins.
   This option may also be called `:line_comments`.
-  Automatically disabled when using the `:compressed` output style
-  or the `:debug_info` option.
-
-{#debug_info-option} `:debug_info`
-: When set to true, causes the line number and file
-  where a selector is defined to be emitted into the compiled CSS
-  in a format that can be understood by the browser.
-  Useful in conjunction with [the FireSass Firebug extension](https://addons.mozilla.org/en-US/firefox/addon/103988)
-  for displaying the Sass filename and line number.
-  Automatically disabled when using the `:compressed` output style.
 
 {#custom-option} `:custom`
 : An option that's available for individual applications to set
   to make data available to {Sass::Script::Functions custom Sass functions}.
 
-{#sass2-option} `:sass2`
-: Parses the document using semantics closer to that of Sass v2.
-  Currently, this just means that strings in mixin arguments
-  are treated as though they were in [an `=` context](#sass-script-strings).
-
-{#quiet-option} `:quiet`
-: When set to true, causes warnings to be disabled.
-
-### Encodings
-
-When running on Ruby 1.9 and later, Sass is aware of the character encoding of documents
-and will handle them the same way that CSS would.
-By default, Sass assumes that all stylesheets are encoded
-using whatever coding system your operating system defaults to.
-For many users this will be `UTF-8`, the de facto standard for the web.
-For some users, though, it may be a more local encoding.
-
-If you want to use a different encoding for your stylesheet
-than your operating system default,
-you can use the `@charset` declaration just like in CSS.
-Add `@charset "encoding-name";` at the beginning of the stylesheet
-(before any whitespace or comments)
-and Sass will interpret it as the given encoding.
-Note that whatever encoding you use, it must be convertible to Unicode.
-
-Sass will also respect any Unicode BOMs and non-ASCII-compatible Unicode encodings
-[as specified by the CSS spec](http://www.w3.org/TR/CSS2/syndata.html#charset),
-although this is *not* the recommended way
-to specify the character set for a document.
-Note that Sass does not support the obscure `UTF-32-2143`,
-`UTF-32-3412`, `EBCDIC`, `IBM1026`, and `GSM 03.38` encodings,
-since Ruby does not have support for them
-and they're highly unlikely to ever be used in practice.
-
-#### Output Encoding
-
-In general, Sass will try to encode the output stylesheet
-using the same encoding as the input stylesheet.
-In order for it to do this, though, the input stylesheet must have a `@charset` declaration;
-otherwise, Sass will default to encoding the output stylesheet as UTF-8.
-In addition, it will add a `@charset` declaration to the output
-if it's not plain ASCII.
-
-When other stylesheets with `@charset` declarations are `@import`ed,
-Sass will convert them to the same encoding as the main stylesheet.
-
-Note that Ruby 1.8 does not have good support for character encodings,
-and so Sass behaves somewhat differently when running under it than under Ruby 1.9 and later.
-In Ruby 1.8, Sass simply uses the first `@charset` declaration in the stylesheet
-or any of the other stylesheets it `@import`s.
-
-## CSS Extensions
+## CSS Rules
 
-### Nested Rules
+Rules in flat CSS have two elements:
+the selector (e.g. `#main`, `div p`, `li a:hover`)
+and the properties (e.g. `color: #00ff00;`, `width: 5em;`).
+Sass has both of these,
+as well as one additional element: nested rules.
 
-Sass allows CSS rules to be nested within one another.
-The inner rule then only applies within the outer rule's selector.
+### Rules and Selectors
+
+However, some of the syntax is a little different.
+The syntax for selectors is the same,
+but instead of using brackets to delineate the properties that belong to a particular rule,
+Sass uses indentation.
+For example:
+
+    #main p
+      <property>
+      <property>
+      ...
+
+Like CSS, you can stretch selectors over multiple lines.
+However, unlike CSS, you can only do this if each line but the last
+ends with a comma.
+For example:
+
+    .users #userTab,
+    .posts #postsTab
+      <property>
+
+### Properties
+
+There are two different ways to write CSS properties.
+The first is very similar to the how you're used to writing them:
+with a colon between the name and the value.
+However, Sass properties don't have semicolons at the end;
+each property is on its own line, so they aren't necessary.
 For example:
 
+    #main p
+      color: #00ff00
+      width: 97%
+
+is compiled to:
+
     #main p {
       color: #00ff00;
-      width: 97%;
+      width: 97% }
 
-      .redbox {
-        background-color: #ff0000;
-        color: #000000;
-      }
-    }
+The second syntax for properties is slightly different.
+The colon is at the beginning of the property,
+rather than between the name and the value,
+so it's easier to tell what elements are properties just by glancing at them.
+For example:
+
+    #main p
+      :color #00ff00
+      :width 97%
+
+is compiled to:
+
+    #main p {
+      color: #00ff00;
+      width: 97% }
+
+By default, either property syntax may be used.
+If you want to force one or the other,
+see the [`:property_syntax`](#property_syntax-option) option.
+
+### Nested Rules
+
+Rules can also be nested within each other.
+This signifies that the inner rule's selector is a child of the outer selector.
+For example:
+
+    #main p
+      color: #00ff00
+      width: 97%
+
+      .redbox
+        background-color: #ff0000
+        color: #000000
 
 is compiled to:
 
@@ -373,20 +308,18 @@ is compiled to:
         background-color: #ff0000;
         color: #000000; }
 
-This helps avoid repetition of parent selectors,
-and makes complex CSS layouts with lots of nested selectors much simpler.
-For example:
+This makes insanely complicated CSS layouts with lots of nested selectors very simple:
 
-    #main {
-      width: 97%;
+    #main
+      width: 97%
 
-      p, div {
-        font-size: 2em;
-        a { font-weight: bold; }
-      }
+      p, div
+        font-size: 2em
+        a
+          font-weight: bold
 
-      pre { font-size: 3em; }
-    }
+      pre
+        font-size: 3em
 
 is compiled to:
 
@@ -401,74 +334,72 @@ is compiled to:
 
 ### Referencing Parent Selectors: `&`
 
-Sometimes it's useful to use a nested rule's parent selector
-in other ways than the default.
-For instance, you might want to have special styles
-for when that selector is hovered over
-or for when the body element has a certain class.
-In these cases, you can explicitly specify where the parent selector
-should be inserted using the `&` character.
-For example:
+In addition to the default behavior of inserting the parent selector
+as a CSS parent of the current selector
+(e.g. above, `#main` is the parent of `p`),
+you can have more fine-grained control over what's done with the parent selector
+by using the ampersand character `&` in your selectors.
 
-    a {
-      font-weight: bold;
-      text-decoration: none;
-      &:hover { text-decoration: underline; }
-      body.firefox & { font-weight: normal; }
-    }
+The ampersand is automatically replaced by the parent selector,
+instead of having it prepended.
+This allows you to cleanly create pseudo-classes:
 
-is compiled to:
+    a
+      font-weight: bold
+      text-decoration: none
+      &:hover
+        text-decoration: underline
+      &:visited
+        font-weight: normal
+
+Which would become:
 
     a {
       font-weight: bold;
       text-decoration: none; }
       a:hover {
         text-decoration: underline; }
-      body.firefox a {
+      a:visited {
         font-weight: normal; }
 
-`&` will be replaced with the parent selector as it appears in the CSS.
-This means that if you have a deeply nested rule,
-the parent selector will be fully resolved
-before the `&` is replaced.
-For example:
+It also allows you to add selectors at the base of the hierarchy,
+which can be useuful for targeting certain styles to certain browsers:
 
-    #main {
-      color: black;
-      a {
-        font-weight: bold;
-        &:hover { color: red; }
-      }
-    }
+    #main
+      width: 90%
+      #sidebar
+        float: left
+        margin-left: 20%
+        .ie6 &
+          margin-left: 40%
 
-is compiled to:
+Which would become:
 
     #main {
-      color: black; }
-      #main a {
-        font-weight: bold; }
-        #main a:hover {
-          color: red; }
+      width: 90%; }
+      #main #sidebar {
+        float: left;
+        margin-left: 20%; }
+        .ie6 #main #sidebar {
+          margin-left: 40%; }
 
-### Nested Properties
+### Property Namespaces
 
 CSS has quite a few properties that are in "namespaces;"
 for instance, `font-family`, `font-size`, and `font-weight`
 are all in the `font` namespace.
 In CSS, if you want to set a bunch of properties in the same namespace,
 you have to type it out each time.
-Sass provides a shortcut for this:
+Sass offers a shortcut for this:
 just write the namespace one,
-then nest each of the sub-properties within it.
+then indent each of the sub-properties within it.
 For example:
 
-    .funky {
-      font: {
-        family: fantasy;
-        size: 30em;
-        weight: bold;
-      }
-    }
+    .funky
+      font:
+        family: fantasy
+        size: 30em
+        weight: bold
 
 is compiled to:
 
@@ -477,67 +408,258 @@ is compiled to:
       font-size: 30em;
       font-weight: bold; }
 
-The property namespace itself can also have a value.
+### Selector Escaping: `\`
+
+In case, for whatever reason, you need to write a selector
+that begins with a Sass-meaningful character,
+you can escape it with a backslash (`\`).
 For example:
 
-    .funky {
-      font: 2px/3px {
-        family: fantasy;
-        size: 30em;
-        weight: bold;
-      }
-    }
+    #main
+      \+div
+        clear: both
 
 is compiled to:
 
-    .funky {
-      font: 2px/3px;
-        font-family: fantasy;
-        font-size: 30em;
-        font-weight: bold; }
+    #main +div {
+      clear: both; }
+
+## Directives
+
+Directives allow the author to directly issue instructions to the Sass compiler.
+They're prefixed with an at sign, `@`,
+followed by the name of the directive,
+a space, and any arguments to it -
+just like CSS directives.
+For example:
+
+    @import red.sass
+
+Some directives can also control whether or how many times
+a chunk of Sass is output.
+Those are documented under Control Directives.
+
+### `@import` {#import}
+
+The `@import` directive works in a very similar way to the CSS import directive.
+It can either compile to a literal CSS `@import` directive for a CSS file,
+or it can import a Sass file.
+If it imports a Sass file,
+not only are the rules from that file included,
+but all variables in that file are made available in the current file.
+
+Sass looks for other Sass files in the working directory,
+and the Sass file directory under Rack, Rails, or Merb.
+Additional search directories may be specified
+using the [`:load_paths`](#load_paths-option) option.
+
+`@import` takes a filename with or without an extension.
+If an extension isn't provided,
+Sass will try to find a Sass file with the given basename in the load paths.
+
+For example,
+
+    @import foo.sass
+
+or
+
+    @import foo
+
+would compile to
+
+    .foo {
+      color: #f00; }
+
+whereas
+
+    @import foo.css
+
+would compile to
+
+    @import "foo.css";
+
+#### Partials {#partials}
+
+If you have a Sass file that you want to import
+but don't want to compile to a CSS file,
+you can add an underscore to the beginning of the filename.
+This will tell Sass not to compile it to a normal CSS file.
+You can then refer to these files without using the underscore.
+
+For example, you might have `_colors.sass`.
+Then no `_colors.css` file would be created,
+and you can do
+
+    @import colors.sass
+
+### `@debug`
+
+The `@debug` directive prints the value of a SassScript expression
+to standard error.
+It's useful for debugging Sass files
+that have complicated SassScript going on.
+For example:
+
+    @debug 10em + 12em
+
+outputs:
 
-## Comments: `/* */` and `//` {#comments}
+    Line 1 DEBUG: 22em
+
+### `@font-face`, `@media`, etc.
 
-Sass supports standard multiline CSS comments with `/* */`,
-as well as single-line comments with `//`.
-The multiline comments are preserved in the CSS output where possible,
-while the single-line comments are removed.
+Sass behaves as you'd expect for normal CSS @-directives.
 For example:
 
-    /* This comment is
-     * several lines long.
-     * since it uses the CSS comment syntax,
-     * it will appear in the CSS output. */
-    body { color: black; }
+    @font-face
+      font-family: "Bitstream Vera Sans"
+      src: url(http://foo.bar/bvs)
+
+compiles to:
+
+    @font-face {
+      font-family: "Bitstream Vera Sans";
+      src: url(http://foo.bar/bvs); }
 
-    // These comments are only one line long each.
-    // They won't appear in the CSS output,
-    // since they use the single-line comment syntax.
-    a { color: green; }
+and
+
+    @media print
+      #sidebar
+        display: none
+
+      #main
+        background-color: white
+
+compiles to:
+
+    @media print {
+      #sidebar {
+        display: none; }
+
+      #main {
+        background-color: white; } }
+
+## Control Directives
+
+SassScript supports basic control directives for looping and conditional evaluation.
+
+### `@if`
+
+The `@if` statement takes a SassScript expression
+and prints the code nested beneath it if the expression returns
+anything other than `false`:
+
+    p
+      @if 1 + 1 == 2
+        border: 1px solid
+      @if 5 < 3
+        border: 2px dotted
 
 is compiled to:
 
-    /* This comment is
-     * several lines long.
-     * since it uses the CSS comment syntax,
-     * it will appear in the CSS output. */
-    body {
-      color: black; }
+    p {
+      border: 1px solid; }
 
-    a {
+The `@if` statement can be followed by several `@else if` statements
+and one `@else` statement.
+If the `@if` statement fails,
+the `@else if` statements are tried in order
+until one succeeds or the `@else` is reached.
+For example:
+
+    !type = "monster"
+    p
+      @if !type == "ocean"
+        color: blue
+      @else if !type == "matador"
+        color: red
+      @else if !type == "monster"
+        color: green
+      @else
+        color: black
+
+is compiled to:
+
+    p {
       color: green; }
 
-## SassScript {#sassscript}
+### `@for`
+
+The `@for` statement has two forms:
+`@for <var> from <start> to <end>` or
+`@for <var> from <start> through <end>`.
+`<var>` is a variable name, like `!i`,
+and `<start>` and `<end>` are SassScript expressions
+that should return integers.
+
+The `@for` statement sets `<var>` to each number
+from `<start>` to `<end>`,
+including `<end>` if `through` is used.
+For example:
+
+    @for !i from 1 through 3
+      .item-#{!i}
+        width = 2em * !i
+
+is compiled to:
+
+    .item-1 {
+      width: 2em; }
+    .item-2 {
+      width: 4em; }
+    .item-3 {
+      width: 6em; }
+
+### `@while`
+
+The `@while` statement repeatedly loops over the nested
+block until the statement evaluates to `false`. This can
+be used to achieve more complex looping than the `@for`
+statement is capable of.
+For example:
+
+    !i = 6
+    @while !i > 0
+      .item-#{!i}
+        width = 2em * !i
+      !i = !i - 2
+
+is compiled to:
+
+    .item-6 {
+      width: 12em; }
+
+    .item-4 {
+      width: 8em; }
+
+    .item-2 {
+      width: 4em; }
+
+## SassScript
+
+In addition to the declarative templating system,
+Sass supports a simple language known as SassScript
+for dynamically computing CSS values and controlling
+the styles and selectors that get emitted.
+
+SassScript can be used as the value for a property
+by using `=` instead of `:`.
+For example:
+
+    color = #123 + #234
+
+is compiled to:
+
+    color: #357;
+
+For old-style properties, the `=` is added but the `:` is retained.
+For example:
+
+    :color = #123 + #234
 
-In addition to the plain CSS property syntax,
-Sass supports a small set of extensions called SassScript.
-SassScript allows properties to use
-variables, arithmetic, and extra functions.
-SassScript can be used in any property value.
+is compiled to:
 
-SassScript can also be used to generate selectors and property names,
-which is useful when writing [mixins](#mixins).
-This is done via [interpolation](#interpolation_).
+    color: #357;
 
 ### Interactive Shell
 
@@ -556,93 +678,58 @@ and the result printed out for you:
     >> #777 + #888
     white
 
-### Variables: `$` {#variables_}
+### Variables: `!`
 
 The most straightforward way to use SassScript
-is to use variables.
-Variables begin with dollar signs,
-and are set like CSS properties:
-
-    $width: 5em;
+is to set and reference variables.
+Variables begin with exclamation marks,
+and are set like so:
 
-You can then refer to them in properties:
-
-    #main {
-      width: $width;
-    }
+    !width = 5em
 
-Variables are only available within the level of nested selectors
-where they're defined.
-If they're defined outside of any nested selectors,
-they're available everywhere.
+You can then refer to them by putting an equals sign
+after your properties:
 
-Variables used to use the prefix character `!`;
-this still works, but it's deprecated and prints a warning.
-`$` is the recommended syntax.
+    #main
+      width = !width
 
-Variables also used to be defined with `=` rather than `:`;
-this still works, but it's deprecated and prints a warning.
-`:` is the recommended syntax.
+Variables that are first defined in a scoped context are only
+available in that context.
 
 ### Data Types
 
-SassScript supports four main data types:
-
+SassScript supports four data types:
 * numbers (e.g. `1.2`, `13`, `10px`)
-* strings of text, with and without quotes (e.g. `"foo"`, `'bar'`, `baz`)
-* colors (e.g. `blue`, `#04a3f9`, `rgba(255, 0, 0, 0.5)`)
+* strings of text (e.g. `"foo"`, `"bar"`)
+* colors (e.g. `blue`, `#04a3f9`)
 * booleans (e.g. `true`, `false`)
 
-SassScript also supports all other types of CSS property value,
-such as Unicode ranges and `!important` declarations.
-However, it has no special handling for these types.
-They're treated just like unquoted strings.
-
-#### Strings {#sass-script-strings}
-
-CSS specifies two kinds of strings: those with quotes,
-such as `"Lucida Grande"` or `'http://sass-lang.com'`,
-and those without quotes, such as `sans-serif` or `bold`.
-SassScript recognizes both kinds,
-and in general if one kind of string is used in the Sass document,
-that kind of string will be used in the resulting CSS.
+Any text that doesn't fit into one of those types
+in a SassScript context will cause an error:
 
-There is one exception to this, though:
-when using [`#{}` interpolation](#interpolation_),
-quoted strings are unquoted.
-This makes it easier to use e.g. selector names in [mixins](#mixins).
-For example:
-
-    @mixin firefox-message($selector) {
-      body.firefox #{$selector}:before {
-        content: "Hi, Firefox users!"; } }
-
-    @include firefox-message(".header");
+    p
+      !width = 5em
+      // This will cause an error
+        border = !width solid blue
+      // Use one of the following forms instead:
+      border = "#{!width} solid blue"
+      border = !width "solid" "blue"
 
 is compiled to:
 
-    body.firefox .header:before {
-      content: "Hi, Firefox users!"; }
+    p {
+      border: 5em solid blue;
+      border: 5em solid blue; }
 
-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 `!=`).
-In addition, each type has its own operations
-that it has special support for.
-
-#### Number Operations
-
 SassScript supports the standard arithmetic operations on numbers
 (`+`, `-`, `*`, `/`, `%`),
 and will automatically convert between units if it can:
 
-    p {
-      width: 1in + 8pt;
-    }
+    p
+      width = 1in + 8pt
 
 is compiled to:
 
@@ -656,69 +743,14 @@ and equality operators
 (`==`, `!=`)
 are supported for all types.
 
-##### Division and `/`
-{#division-and-slash}
-
-CSS allows `/` to appear in property values
-as a way of separating numbers.
-Since SassScript is an extension of the CSS property syntax,
-it must support this, while also allowing `/` to be used for division.
-This means that by default, if two numbers are separated by `/` in SassScript,
-then they will appear that way in the resulting CSS.
-
-However, there are three situations where the `/` will be interpreted as division.
-These cover the vast majority of cases where division is actually used.
-They are:
-
-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;             // Plain CSS, no division
-      $width: 1000px;
-      width: $width/2;            // Uses a variable, does division
-      height: (500px/2);          // Uses parentheses, does division
-      margin-left: 5px + 8px/2px; // Uses +, does division
-    }
-
-is compiled to:
-
-    p {
-      font: 10px/8px;
-      width: 500px;
-      height: 250px;
-      margin-left: 9px; }
-
-If you want to use variables along with a plain CSS `/`,
-you can use `#{}` to insert them.
-For example:
-
-    p {
-      $font-size: 12px;
-      $line-height: 30px;
-      font: #{$font-size}/#{$line-height};
-    }
-
-is compiled to:
-
-    p {
-      font: 12px/30px;
-    }
-
-#### Color Operations
-
 All arithmetic operations are supported for color values,
 where they work piecewise.
 This means that the operation is performed
 on the red, green, and blue components in turn.
 For example:
 
-    p {
-      color: #010203 + #040506;
-    }
+    p
+      color = #010203 + #040506
 
 computes `01 + 04 = 05`, `02 + 05 = 07`, and `03 + 06 = 09`,
 and is compiled to:
@@ -726,16 +758,12 @@ and is compiled to:
     p {
       color: #050709; }
 
-Often it's more useful to use {Sass::Script::Functions color functions}
-than to try to use color arithmetic to achieve the same effect.
-
-Arithmetic operations also work between numbers and colors,
+Arithmetic operations even work between numbers and colors,
 also piecewise.
 For example:
 
-    p {
-      color: #010203 * 2;
-    }
+    p
+      color = #010203 * 2
 
 computes `01 * 2 = 02`, `02 * 2 = 04`, and `03 * 2 = 06`,
 and is compiled to:
@@ -743,873 +771,315 @@ and is compiled to:
     p {
       color: #020406; }
 
-Note that colors with an alpha channel
-(those created with the {Sass::Script::Functions#rgba rgba}
-or {Sass::Script::Functions#hsla hsla} functions)
-must have the same alpha value in order for color arithmetic
-to be done with them.
-The arithmetic doesn't affect the alpha value.
-For example:
+The `+` operation can be used to concatenate strings:
 
-    p {
-      color: rgba(255, 0, 0, 0.75) + rgba(0, 255, 0, 0.75);
-    }
+    p
+      cursor = "e" + "-resize"
 
 is compiled to:
 
     p {
-      color: rgba(255, 255, 0, 0.75); }
+      cursor: e-resize; }
 
-The alpha channel of a color can be adjusted using the
-{Sass::Script::Functions#opacify opacify} and
-{Sass::Script::Functions#transparentize transparentize} functions.
-For example:
+By default, if two values are placed next to one another,
+they are concatenated with a space:
 
-    $translucent-red: rgba(255, 0, 0, 0.5);
-    p {
-      color: opacify($translucent-red, 0.8);
-      background-color: transparentize($translucent-red, 50%);
-    }
+    p
+      margin = 3px + 4px "auto"
 
 is compiled to:
 
     p {
-      color: rgba(255, 0, 0, 0.9);
-      background-color: rgba(255, 0, 0, 0.25); }
-
-#### String Operations
+      margin: 7px auto; }
 
-The `+` operation can be used to concatenate strings:
+Within a string of text, #{} style interpolation can be used to
+place dynamic values within the string:
 
-    p {
-      cursor: e + -resize;
-    }
+    p
+      border = "#{5px + 10px} solid #ccc"
 
-is compiled to:
+Finally, SassScript supports `and`, `or`, and `not` operators
+for boolean values.
 
-    p {
-      cursor: e-resize; }
+### Parentheses
 
-Note that if a quoted string is added to an unquoted string
-(that is, the quoted string is to the left of the `+`),
-the result is a quoted string.
-Likewise, if an unquoted string is added to a quoted string
-(the unquoted string is to the left of the `+`),
-the result is an unquoted string.
-For example:
+Parentheses can be used to affect the order of operations:
 
-    p:before {
-      content: "Foo " + Bar;
-      font-family: sans- + "serif"; }
+    p
+      width = 1em + (2em * 3)
 
 is compiled to:
 
-    p:before {
-      content: "Foo Bar";
-      font-family: sans-serif; }
-
-By default, if two values are placed next to one another,
-they are concatenated with a space:
-
-    p {
-      margin: 3px + 4px auto;
-    }
-
-is compiled to:
-
-    p {
-      margin: 7px auto; }
-
-Within a string of text, #{} style interpolation can be used to
-place dynamic values within the string:
-
-    p:before {
-      content: "I ate #{5 + 10} pies!"; }
-
-is compiled to:
-
-    p:before {
-      content: "I ate 15 pies!"; }
-
-#### Boolean Operations
-
-SassScript supports `and`, `or`, and `not` operators
-for boolean values.
-
-### Parentheses
-
-Parentheses can be used to affect the order of operations:
-
-    p {
-      width: 1em + (2em * 3);
-    }
-
-is compiled to:
-
-    p {
-      width: 7em; }
+    p {
+      width: 7em; }
 
 ### Functions
 
 SassScript defines some useful functions
 that are called using the normal CSS function syntax:
 
-    p {
-      color: hsl(0, 100%, 0.5);
-    }
+    p
+      color = hsl(0, 100%, 50%)
 
 is compiled to:
 
-    p {
+    #main {
       color: #ff0000; }
 
-See {Sass::Script::Functions} for a full listing of Sass functions,
-as well as instructions on defining your own in Ruby.
+The following functions are provided: `hsl`, `percentage`, `round`, `ceil`, `floor`, and `abs`.
+You can define additional functions in ruby.
 
-### Interpolation: `#{}` {#interpolation_}
+See {Sass::Script::Functions} for more information.
+
+### Interpolation: `#{}`
 
 You can also use SassScript variables in selectors
 and property names using #{} interpolation syntax:
 
-    $name: foo;
-    $attr: border;
-    p.#{$name} { #{$attr}-color: blue }
+    !name = foo
+    !attr = border
+    p.#{!name}
+      #{!attr}-color: blue
 
 is compiled to:
 
     p.foo {
       border-color: blue; }
 
-It's also possible to use `#{}` to put SassScript into property values.
-In most cases this isn't any better than using a variable,
-but using `#{}` does mean that any operations near it
-will be treated as plain CSS.
-For example:
-
-    p {
-      $font-size: 12px;
-      $line-height: 30px;
-      font: #{$font-size}/#{$line-height};
-    }
-
-is compiled to:
-
-    p {
-      font: 12px/30px;
-    }
-
-### Variable Defaults: `!default`
+### Optional Assignment: `||=`
 
 You can assign to variables if they aren't already assigned
-by adding the `!default` flag to the end of the value.
-This means that if the variable has already been assigned to,
-it won't be re-assigned,
+using the `||=` assignment operator. This means that if the
+variable has already been assigned to, it won't be re-assigned,
 but if it doesn't have a value yet, it will be given one.
 
 For example:
 
-    $content: "First content";
-    $content: "Second content?" !default;
-    $new_content: "First time reference" !default;
+    !content = "First content"
+    !content ||= "Second content?"
+    !new_content ||= "First time reference"
 
-    #main {
-      content: $content;
-      new-content: $new_content;
-    }
+    #main
+      content = !content
+      new-content = !new_content
 
 is compiled to:
 
     #main {
-      content: "First content";
-      new-content: "First time reference"; }
-
-## `@`-Rules and Directives {#directives}
-
-Sass supports all CSS3 `@`-rules,
-as well as some additional Sass-specific ones
-known as "directives."
-These have various effects in Sass, detailed below.
-See also [control directives](#control-directives)
-and [mixin directives](#mixins).
-
-### `@import` {#import}
-
-Sass extends the CSS `@import` rule
-to allow it to import SCSS and Sass files.
-All imported SCSS and Sass files will be merged together
-into a single CSS output file.
-In addition, any variables or [mixins](#mixins)
-defined in imported files can be used in the main file.
-
-Sass looks for other Sass files in the current directory,
-and the Sass file directory under Rack, Rails, or Merb.
-Additional search directories may be specified
-using the [`:load_paths`](#load_paths-option) option,
-or the `--load-path` option on the command line.
-
-`@import` takes a filename to import.
-By default, it looks for a Sass file to import directly,
-but there are a few circumstances under which it will compile to a CSS `@import` rule:
-
-* If the file's extension is `.css`.
-* If the filename begins with `http://`.
-* If the filename is a `url()`.
-* If the `@import` has any media queries.
-
-If none of the above conditions are met
-and the extension is `.scss` or `.sass`,
-then the named Sass or SCSS file will be imported.
-If there is no extension,
-Sass will try to find a file with that name and the `.scss` or `.sass` extension
-and import it.
-
-For example,
-
-    @import "foo.scss";
-
-or
-
-    @import "foo";
-
-would both import the file `foo.scss`,
-whereas
-
-    @import "foo.css";
-    @import "foo" screen;
-    @import "http://foo.com/bar";
-    @import url(foo);
-
-would all compile to
-
-    @import "foo.css";
-    @import "foo" screen;
-    @import "http://foo.com/bar";
-    @import url(foo);
-
-It's also possible to import multiple files in one `@import`. For example:
-
-    @import "rounded-corners", "text-shadow";
-
-would import both the `rounded-corners` and the `text-shadow` files.
-
-#### Partials {#partials}
-
-If you have a SCSS or Sass file that you want to import
-but don't want to compile to a CSS file,
-you can add an underscore to the beginning of the filename.
-This will tell Sass not to compile it to a normal CSS file.
-You can then import these files without using the underscore.
-
-For example, you might have `_colors.scss`.
-Then no `_colors.css` file would be created,
-and you can do
-
-    @import "colors";
-
-and `_colors.scss` would be imported.
-
-### `@extend` {#extend}
-
-There are often cases when designing a page
-when one class should have all the styles of another class,
-as well as its own specific styles.
-The most common way of handling this is to use both the more general class
-and the more specific class in the HTML.
-For example, suppose we have a design for a normal error
-and also for a serious error. We might write our markup like so:
-
-    <div class="error seriousError">
-      Oh no! You've been hacked!
-    </div>
-
-And our styles like so:
-
-    .error {
-      border: 1px #f00;
-      background-color: #fdd;
-    }
-    .seriousError {
-      border-width: 3px;
-    }
-
-Unfortunately, this means that we have to always remember
-to use `.error` with `.seriousError`.
-This is a maintenance burden, leads to tricky bugs,
-and can bring non-semantic style concerns into the markup.
-
-The `@extend` directive avoids these problems
-by telling Sass that one selector should inherit the styles of another selector.
-For example:
-
-    .error {
-      border: 1px #f00;
-      background-color: #fdd;
-    }
-    .seriousError {
-      @extend .error;
-      border-width: 3px;
-    }
-
-This means that all styles defined for `.error`
-are also applied to `.seriousError`,
-in addition to the styles specific to `.seriousError`.
-In effect, everything with class `.seriousError` also has class `.error`.
-
-Other rules that use `.error` will work for `.seriousError` as well.
-For example, if we have special styles for errors caused by hackers:
-
-    .error.intrusion {
-      background-image: url("/image/hacked.png");
-    }
-
-Then `<div class="seriousError intrusion">`
-will have the `hacked.png` background image as well.
-
-#### How it Works
-
-`@extend` works by inserting the extending selector (e.g. `.seriousError`)
-anywhere in the stylesheet that the extended selector (.e.g `.error`) appears.
-Thus the example above:
-
-    .error {
-      border: 1px #f00;
-      background-color: #fdd;
-    }
-    .error.intrusion {
-      background-image: url("/image/hacked.png");
-    }
-    .seriousError {
-      @extend .error;
-      border-width: 3px;
-    }
-
-is compiled to:
-
-    .error, .seriousError {
-      border: 1px #f00;
-      background-color: #fdd; }
-
-    .error.intrusion, .seriousError.intrusion {
-      background-image: url("/image/hacked.png"); }
-
-    .seriousError {
-      border-width: 3px; }
-
-When merging selectors, `@extend` is smart enough
-to avoid unnecessary duplication,
-so something like `.seriousError.seriousError` gets translated to `.seriousError`.
-In addition, it won't produce selectors that can't match anything, like `#main#footer`.
-
-#### Extending Complex Selectors
-
-Class selectors aren't the only things that can be extended.
-It's possible to extend any selector involving only a single element,
-such as `.special.cool`, `a:hover`, or `a.user[href^="http://"]`.
-For example:
-
-    .hoverlink {@extend a:hover}
-
-Just like with classes, this means that all styles defined for `a:hover`
-are also applied to `.hoverlink`.
-For example:
-
-    .hoverlink {@extend a:hover}
-    a:hover {text-decoration: underline}
-
-is compiled to:
-
-    a:hover, .hoverlink {text-decoration: underline}
-
-Just like with `.error.intrusion` above,
-any rule that uses `a:hover` will also work for `.hoverlink`,
-even if they have other selectors as well.
-For example:
-
-    .hoverlink {@extend a:hover}
-    .comment a.user:hover {font-weight: bold}
-
-is compiled to:
-
-    .comment a.user:hover, .comment .hoverlink.user {font-weight: bold}
-
-#### Multiple Extends
-
-A single selector can extend more than one selector.
-This means that it inherits the styles of all the extended selectors.
-For example:
-
-    .error {
-      border: 1px #f00;
-      background-color: #fdd;
-    }
-    .attention {
-      font-size: 3em;
-      background-color: #ff0;
-    }
-    .seriousError {
-      @extend .error;
-      @extend .attention;
-      border-width: 3px;
-    }
-
-is compiled to:
-
-    .error, .seriousError {
-      border: 1px #f00;
-      background-color: #fdd; }
-
-    .attention, .seriousError {
-      font-size: 3em;
-      background-color: #ff0; }
-
-    .seriousError {
-      border-width: 3px; }
-
-In effect, everything with class `.seriousError`
-also has class `.error` *and* class `.attention`.
-Thus, the styles defined later in the document take precedence:
-`.seriousError` has background color `#ff0` rather than `#fdd`,
-since `.attention` is defined later than `.error`.
-
-#### Chaining Extends
-
-It's possible for one selector to extend another selector
-that in turn extends a third.
-For example:
+      content: First content;
+      new-content: First time reference; }
 
-    .error {
-      border: 1px #f00;
-      background-color: #fdd;
-    }
-    .seriousError {
-      @extend .error;
-      border-width: 3px;
-    }
-    .criticalError {
-      @extend .seriousError;
-      position: fixed;
-      top: 10%;
-      bottom: 10%;
-      left: 10%;
-      right: 10%;
-    }
+## Mixins
 
-Now everything with class `.seriousError` also has class `.error`,
-and everything with class `.criticalError` has class `.seriousError`
-*and* class `.error`.
-It's compiled to:
+Mixins enable you to define groups of CSS properties and
+then include them inline in any number of selectors
+throughout the document. This allows you to keep your
+stylesheets DRY and also avoid placing presentation
+classes in your markup.
 
-    .error, .seriousError, .criticalError {
-      border: 1px #f00;
-      background-color: #fdd; }
+### Defining a Mixin: `=`
 
-    .seriousError, .criticalError {
-      border-width: 3px; }
+To define a mixin you use a slightly modified form of selector syntax.
+For example the `large-text` mixin is defined as follows:
 
-    .criticalError {
-      position: fixed;
-      top: 10%;
-      bottom: 10%;
-      left: 10%;
-      right: 10%; }
+    =large-text
+      font:
+        family: Arial
+        size: 20px
+        weight: bold
+      color: #ff0000
 
-#### Selector Sequences
-
-Selector sequences, such as `.foo .bar` or `.foo + .bar`, currently can't be extended.
-However, it is possible for nested selectors themselves to use `@extend`.
+The initial `=` marks this as a mixin rather than a standard selector.
+The CSS rules that follow won't be included until the mixin is referenced later on.
+Anything you can put into a standard selector,
+you can put into a mixin definition.
 For example:
 
-    #fake-links .link {@extend a}
-
-    a {
-      color: blue;
-      &:hover {text-decoration: underline}
-    }
-
-is compiled to
-
-    a, #fake-links .link {
-      color: blue; }
-      a:hover, #fake-links .link:hover {
-        text-decoration: underline; }
-
-##### Merging Selector Sequences
-
-Sometimes a selector sequence extends another selector that appears in another sequence.
-In this case, the two sequences need to be merged.
-For example:
-
-    #admin .tabbar a {font-weight: bold}
-    #demo .overview .fakelink {@extend a}
-
-While it would technically be possible
-to generate all selectors that could possibly match either sequence,
-this would make the stylesheet far too large.
-The simple example above, for instance, would require ten selectors.
-Instead, Sass generates only selectors that are likely to be useful.
-
-When the two sequences being merged have no selectors in common,
-then two new selectors are generated:
-one with the first sequence before the second,
-and one with the second sequence before the first.
-For example:
-
-    #admin .tabbar a {font-weight: bold}
-    #demo .overview .fakelink {@extend a}
-
-is compiled to:
+    =clearfix
+      display: inline-block
+      &:after
+        content: "."
+        display: block
+        height: 0
+        clear: both
+        visibility: hidden
+      * html &
+        height: 1px
 
-    #admin .tabbar a,
-    #admin .tabbar #demo .overview .fakelink,
-    #demo .overview #admin .tabbar .fakelink {
-      font-weight: bold; }
+### Mixing It In: `+`
 
-If the two sequences do share some selectors,
-then those selectors will be merged together
-and only the differences (if any still exist) will alternate.
-In this example, both sequences contain the id `#admin`,
-so the resulting selectors will merge those two ids:
+Inlining a defined mixin is simple,
+just prepend a `+` symbol to the name of a mixin defined earlier in the document.
+So to inline the `large-text` defined earlier,
+we include the statment `+large-text` in our selector definition thus:
 
-    #admin .tabbar a {font-weight: bold}
-    #admin .overview .fakelink {@extend a}
+    .page-title
+      +large-text
+      padding: 4px
+      margin:
+        top: 10px
 
-This is compiled to:
+This will produce the following CSS output:
 
-    #admin .tabbar a,
-    #admin .tabbar .overview .fakelink,
-    #admin .overview .tabbar .fakelink {
-      font-weight: bold; }
+    .page-title {
+      font-family: Arial;
+      font-size: 20px;
+      font-weight: bold;
+      color: #ff0000;
+      padding: 4px;
+      margin-top: 10px; }
 
-### `@debug`
+Any number of mixins may be defined and there is no limit on
+the number that can be included in a particular selector.
 
-The `@debug` directive prints the value of a SassScript expression
-to the standard error output stream.
-It's useful for debugging Sass files
-that have complicated SassScript going on.
+Mixin definitions can also include references to other mixins.
 For example:
 
-    @debug 10em + 12em;
+    =compound
+      +highlighted-background
+      +header-text
 
-outputs:
-
-    Line 1 DEBUG: 22em
-
-### `@warn`
-
-The `@warn` directive prints the value of a SassScript expression
-to the standard error output stream.
-It's useful for libraries that need to warn users of deprecations
-or recovering from minor mixin usage mistakes.
-There are two major distinctions between `@warn` and `@debug`:
-
-1. You can turn warnings off with the `--quiet` command-line option
-   or the `:quiet` Sass option.
-2. A stylesheet trace will be printed out along with the message
-   so that the user being warned can see where their styles caused the warning.
-
-Usage Example:
-
-    @mixin adjust-location($x, $y) {
-      @if unitless($x) {
-        @warn "Assuming #{$x} to be in pixels";
-        $x: 1px * $x;
-      }
-      @if unitless($y) {
-        @warn "Assuming #{$y} to be in pixels";
-        $y: 1px * $y;
-      }
-      position: relative; left: $x; top: $y;
-    }
+    =highlighted-background
+      background:
+        color: #fc0
+    =header-text
+      font:
+        size: 20px
 
-## Control Directives
-
-SassScript supports basic control directives
-for including styles only under some conditions
-or including the same style several times with variations.
-
-**Note that control directives are an advanced feature,
-and are not recommended in the course of day-to-day styling**.
-They exist mainly for use in [mixins](#mixins),
-particularly those that are part of libraries like [Compass](http://compass-style.org),
-and so require substantial flexibility.
+Mixins that only define descendent selectors, can be safely mixed
+into the top most level of a document.
 
-### `@if`
+### Arguments
 
-The `@if` directive takes a SassScript expression
-and uses the styles nested beneath it if the expression returns
-anything other than `false`:
+Mixins can take arguments which can be used with SassScript:
 
-    p {
-      @if 1 + 1 == 2 { border: 1px solid; }
-      @if 5 < 3 { border: 2px dotted; }
-    }
+    =sexy-border(!color)
+      border:
+        color = !color
+        width: 1in
+        style: dashed
+    p
+      +sexy-border("blue")
 
 is compiled to:
 
     p {
-      border: 1px solid; }
+      border-color: #0000ff;
+      border-width: 1in;
+      border-style: dashed; }
 
-The `@if` statement can be followed by several `@else if` statements
-and one `@else` statement.
-If the `@if` statement fails,
-the `@else if` statements are tried in order
-until one succeeds or the `@else` is reached.
-For example:
+Mixins can also specify default values for their arguments:
 
-    $type: monster;
-    p {
-      @if $type == ocean {
-        color: blue;
-      } @else if $type == matador {
-        color: red;
-      } @else if $type == monster {
-        color: green;
-      } @else {
-        color: black;
-      }
-    }
+    =sexy-border(!color, !width = 1in)
+      border:
+        color = !color
+        width = !width
+        style: dashed
+    p
+      +sexy-border("blue")
 
 is compiled to:
 
     p {
-      color: green; }
-
-### `@for`
-
-The `@for` directive has two forms:
-`@for $var from <start> to <end>` or
-`@for $var from <start> through <end>`.
-`$var` can be any variable name, like `$i`,
-and `<start>` and `<end>` are SassScript expressions
-that should return integers.
-
-The `@for` statement sets `$var` to each number
-from `<start>` to `<end>`,
-including `<end>` if `through` is used.
-Then it outputs the nested styles
-using that value of `$var`.
-For example:
-
-    @for $i from 1 through 3 {
-      .item-#{$i} { width: 2em * $i; }
-    }
-
-is compiled to:
-
-    .item-1 {
-      width: 2em; }
-    .item-2 {
-      width: 4em; }
-    .item-3 {
-      width: 6em; }
-
-### `@while`
-
-The `@while` directive takes a SassScript expression
-and repeatedly outputs the nested styles
-until the statement evaluates to `false`.
-This can be used to achieve more complex looping
-than the `@for` statement is capable of,
-although this is rarely necessary.
-For example:
-
-    $i: 6;
-    @while $i > 0 {
-      .item-#{$i} { width: 2em * $i; }
-      $i: $i - 2;
-    }
-
-is compiled to:
-
-    .item-6 {
-      width: 12em; }
-
-    .item-4 {
-      width: 8em; }
-
-    .item-2 {
-      width: 4em; }
-
-## Mixin Directives {#mixins}
-
-Mixins allow you to define styles
-that can be re-used throughout the stylesheet
-without needing to resort to non-semantic classes like `.float-left`.
-Mixins can also contain full CSS rules,
-and anything else allowed elsewhere in a Sass document.
-They can even take [arguments](#mixin-arguments)
-which allows you to produce a wide variety of styles
-with very few mixins.
-
-### Defining a Mixin: `@mixin` {#defining_a_mixin}
-
-Mixins are defined with the `@mixin` directive.
-It's followed by the name of the mixin
-and optionally the [arguments](#mixin-arguments),
-and a block containing the contents of the mixin.
-For example, the `large-text` mixin is defined as follows:
-
-    @mixin large-text {
-      font: {
-        family: Arial;
-        size: 20px;
-        weight: bold;
-      }
-      color: #ff0000;
-    }
-
-Mixins may also contain selectors,
-possibly mixed with properties.
-The selectors can even contain [parent references](#referencing_parent_selectors_).
-For example:
-
-    @mixin clearfix {
-      display: inline-block;
-      &:after {
-        content: ".";
-        display: block;
-        height: 0;
-        clear: both;
-        visibility: hidden;
-      }
-      * html & { height: 1px }
-    }
-
-### Including a Mixin: `@include` {#including_a_mixin}
-
-Mixins are included in the document
-with the `@include` directive.
-This takes the name of a mixin
-and optionally [arguments to pass to it](#mixin-arguments),
-and includes the styles defined by that mixin
-into the current rule.
-For example:
-
-    .page-title {
-      @include large-text;
-      padding: 4px;
-      margin-top: 10px;
-    }
-
-is compiled to:
-
-    .page-title {
-      font-family: Arial;
-      font-size: 20px;
-      font-weight: bold;
-      color: #ff0000;
-      padding: 4px;
-      margin-top: 10px; }
-
-Mixins may also be included outside of any rule
-(that is, at the root of the document)
-as long as they don't directly define any properties
-or use any parent references.
-For example:
+      border-color: #0000ff;
+      border-width: 1in;
+      border-style: dashed; }
 
-    @mixin silly-links {
-      a {
-        color: blue;
-        background-color: red;
-      }
-    }
+## Comments
 
-    @include silly-links;
+Sass supports two sorts of comments:
+those that show up in the CSS output
+and those that don't.
 
-is compiled to:
+### CSS Comments: `/*`
 
-    a {
-      color: blue;
-      background-color: red; }
-
-Mixin definitions can also include other mixins.
+"Loud" comments are just as easy as silent ones.
+These comments output to the document as CSS comments,
+and thus use the same opening sequence: `/*`.
 For example:
 
-    @mixin compound {
-      @include highlighted-background;
-      @include header-text;
-    }
-
-    @mixin highlighted-background { background-color: #fc0; }
-    @mixin header-text { font-size: 20px; }
-
-Mixins that only define descendent selectors, can be safely mixed
-into the top most level of a document.
-
-### Arguments {#mixin-arguments}
-
-Mixins can take arguments SassScript values as arguments,
-which are given when the mixin is included
-and made available within the mixin as variables.
-
-When defining a mixin,
-the arguments are written as variable names separated by commas,
-all in parentheses after the name.
-Then when including the mixin,
-values can be passed in in the same manner.
+    /* A very awesome rule.
+    #awesome.rule
+      /* An equally awesome property.
+      awesomeness: very
+
+becomes
+
+    /* A very awesome rule. */
+    #awesome.rule {
+      /* An equally awesome property. */
+      awesomeness: very; }
+
+You can also nest content beneath loud comments. For example:
+
+    #pbj
+      /* This rule describes
+        the styling of the element
+        that represents
+        a peanut butter and jelly sandwich.
+      background-image: url(/images/pbj.png)
+      color: red
+
+becomes
+
+    #pbj {
+      /* This rule describes
+       * the styling of the element
+       * that represents
+       * a peanut butter and jelly sandwich. */
+      background-image: url(/images/pbj.png);
+      color: red; }
+
+### Sass Comments: `//`
+
+It's simple to add "silent" comments,
+which don't output anything to the CSS document,
+to a Sass document.
+Simply use the familiar C-style notation for a one-line comment, `//`,
+at the normal indentation level and all text following it won't be output.
 For example:
 
-    @mixin sexy-border($color, $width) {
-      border: {
-        color: $color;
-        width: $width;
-        style: dashed;
-      }
-    }
-
-    p { @include sexy-border(blue, 1in); }
+    // A very awesome rule.
+    #awesome.rule
+      // An equally awesome property.
+      awesomeness: very
 
-is compiled to:
+becomes
 
-    p {
-      border-color: blue;
-      border-width: 1in;
-      border-style: dashed; }
+    #awesome.rule {
+      awesomeness: very; }
 
-Mixins can also specify default values for their arguments
-using the normal variable-setting syntax.
-Then when the mixin is included,
-if it doesn't pass in that argument,
-the default value will be used instead.
+You can also nest text beneath a comment to comment out a whole block.
 For example:
 
-    @mixin sexy-border($color, $width: 1in) {
-      border: {
-        color: $color;
-        width: $width;
-        style: dashed;
-      }
-    }
-    p { @include sexy-border(blue); }
-    h1 { @include sexy-border(blue, 2in); }
+    // A very awesome rule
+    #awesome.rule
+      // Don't use these properties
+        color: green
+        font-size: 10em
+      color: red
 
-is compiled to:
+becomes
 
-    p {
-      border-color: blue;
-      border-width: 1in;
-      border-style: dashed; }
-
-    h1 {
-      border-color: blue;
-      border-width: 2in;
-      border-style: dashed; }
+    #awesome.rule {
+      color: red; }
 
 ## Output Style
 
-Although the default CSS style that Sass outputs is very nice
-and reflects the structure of the document,
-tastes and needs vary and so Sass supports several other styles.
+Although the default CSS style that Sass outputs is very nice,
+and reflects the structure of the document in a similar way that Sass does,
+sometimes it's good to have other formats available.
 
 Sass allows you to choose between four different output styles
-by setting the [`:style` option](#style-option)
-or using the `--style` command-line flag.
+by setting the `:style` option.
+In Rack, Rails, and Merb, this is done by setting `Sass::Plugin.options[:style]`;
+otherwise, it's done by passing an options hash with `:style` set.
 
 ### `:nested`
 
 Nested style is the default Sass style,
-because it reflects the structure of the CSS styles
-and the HTML document they're styling.
+because it reflects the structure of the document
+in much the same way Sass does.
 Each property has its own line,
 but the indentation isn't constant.
 Each rule is indented based on how deeply it's nested.
@@ -1626,13 +1096,14 @@ For example:
       font-weight: bold;
       text-decoration: underline; }
 
-Nested style is very useful when looking at large CSS files:
-it allows you to easily grasp the structure of the file
+Nested style is very useful when looking at large CSS files
+for the same reason Sass is useful for making them:
+it allows you to very easily grasp the structure of the file
 without actually reading anything.
 
 ### `:expanded`
 
-Expanded is a more typical human-made CSS style,
+Expanded is the typical human-made CSS style,
 with each property and rule taking up one line.
 Properties are indented within the rules,
 but the rules aren't indented in any special way.
@@ -1654,12 +1125,13 @@ For example:
 
 ### `:compact`
 
-Compact style takes up less space than Nested or Expanded.
-It also draws the focus more to the selectors than to their properties.
+Compact style, as the name would imply,
+takes up less space than Nested or Expanded.
+However, it's also harder to read.
 Each CSS rule takes up only one line,
 with every property defined on that line.
 Nested rules are placed next to each other with no newline,
-while separate groups of rules have newlines between them.
+while groups of rules have newlines between them.
 For example:
 
     #main { color: #fff; background-color: #000; }
@@ -1672,8 +1144,6 @@ For example:
 Compressed style takes up the minimum amount of space possible,
 having no whitespace except that necessary to separate selectors
 and a newline at the end of the file.
-It also includes some other minor compressions,
-such as choosing the smallest representation for colors.
 It's not meant to be human-readable.
 For example: