enja-oss/stylus out dated files(2013-1-9)

bifs.diff

diff --git a/docs/bifs.md b/docs/bifs.md
index 57a6c5c..9f420ad 100644
--- a/docs/bifs.md
+++ b/docs/bifs.md
@@ -19,7 +19,7 @@ Return the green component of the given `color`.
 
 Return the blue component of the given `color`.
 
-     red(#00c)
+     blue(#00c)
      // => 204
 
 ### alpha(color)
@@ -28,7 +28,7 @@ Return the alpha component of the given `color`.
 
       alpha(#fff)
       // => 1
-      
+
       alpha(rgba(0,0,0,0.3))
       // => 0.3
 
@@ -55,7 +55,7 @@ Check if `color` is light:
 
     light(white)
     // => true
-    
+
     light(#00FF40)
     // => true
 
@@ -89,7 +89,7 @@ Return the lightness of the given `color`.
 
      nums
      // => 1 2 3 4 5
- 
+
  Aliased as `append()`
 
 ### unshift(expr, args...)
@@ -101,13 +101,13 @@ Return the lightness of the given `color`.
 
      nums
      // => 1 2 3 4 5
- 
+
  Aliased as `prepend()`
 
 ### keys(pairs)
 
   Return keys in the given `pairs`:
-  
+
      pairs = (one 1) (two 2) (three 3)
      keys(pairs)
      // => one two three
@@ -115,7 +115,7 @@ Return the lightness of the given `color`.
 ### values(pairs)
 
   Return values in the given `pairs`:
-  
+
      pairs = (one 1) (two 2) (three 3)
      values(pairs)
      // => 1 2 3
@@ -129,7 +129,7 @@ Return type of `node` as a string.
 
       typeof(12)
       // => 'unit'
-      
+
       typeof(#fff)
       // => 'rgba'
 
@@ -145,10 +145,10 @@ or assign the given `type` without unit conversion.
 
     unit(10)
     // => ''
-    
+
     unit(15in)
     // => 'in'
-    
+
     unit(15%, 'px')
     // => 15px
 
@@ -166,7 +166,7 @@ Test if `string` matches the given `pattern`.
     match('^foo(bar)?', 'foo')
     match('^foo(bar)?', 'foobar')
     // => true
-    
+
     match('^foo(bar)?', 'bar')
     // => false
 
@@ -196,6 +196,33 @@ Test if `string` matches the given `pattern`.
       round(5.4px)
       // => 5px
 
+### sin(angle)
+
+Returns the value of sine for the given `angle`. If the angle is given as a degree unit, like `45deg`, it is treated as a degree, otherwise it is treated as radians.
+
+    sin(30deg)
+    // => 0.5
+
+    sin(3*PI/4)
+    // => 0.707106781
+
+### cos(angle)
+
+Returns the value of cosine for the given `angle`. If the angle is given as a degree unit, like `45deg`, it is treated as a degree, otherwise it is treated as radians.
+
+    cos(180deg)
+    // => -1
+
+### tan(angle)
+
+Returns the value of tangent for the given `angle`. If the angle is given as a degree unit, like `45deg`, it is treated as a degree, otherwise it is treated as radians.
+
+    tan(45deg)
+    // => 1
+
+    tan(90deg)
+    // => Infinity
+
 ### min(a, b)
 
       min(1, 5)
@@ -226,16 +253,30 @@ Test if `string` matches the given `pattern`.
      avg(1 2 3)
      // => 2
 
+### base-convert(num, base, width)
+
+Returns a `Literal` `num` converted to the provided `base`, padded to `width` with zeroes (default width is 2)
+
+    base-convert(1, 10, 3)
+    // => 001
+
+    base-convert(14, 16, 1)
+    // => e
+
+    base-convert(42, 1)
+    // => 101010
+
+
 ### join(delim, vals...)
 
   Join the given `vals` with `delim`.
 
       join(' ', 1 2 3)
       // => "1 2 3"
-      
+
       join(',', 1 2 3)
       // => "1,2,3"
-      
+
       join(', ', foo bar baz)
       // => "foo, bar, baz"
 
@@ -273,15 +314,15 @@ Return `RGBA` from the r,g,b,a channels or provide a `color` to tweak the alpha.
 
       rgba(255,0,0,0.5)
       // => rgba(255,0,0,0.5)
-  
+
       rgba(255,0,0,1)
       // => #ff0000
-  
+
       rgba(#ffcc00, 0.5)
       // rgba(255,204,0,0.5)
 
  Alternatively stylus supports the `#rgba` and `#rrggbbaa` notations as well:
- 
+
     #fc08
     // => rgba(255,204,0,0.5)
 
@@ -291,10 +332,10 @@ Return `RGBA` from the r,g,b,a channels or provide a `color` to tweak the alpha.
 ### rgb(color | r,g,b)
 
 Return a `RGBA` from the r,g,b channels or cast to an `RGBA` node.
-    
+
     rgb(255,204,0)
     // => #ffcc00
-    
+
     rgb(#fff)
     // => #fff
 
@@ -336,13 +377,48 @@ Saturate the given `color` by `amount`.
     saturate(#c33, 40%)
     // => #f00
 
+### complement(color)
+
+Gives the complementary color. Equals to spinning hue to 180deg.
+
+    complement(#fd0cc7)
+    // => #0cfd42
+
+### invert(color)
+
+Inverts the color. The red, green, and blue values are inverted, while the opacity is left alone.
+
+    invert(#d62828)
+    // => #29d7d7
+
+### grayscale(color)
+
+Gives the grayscale equivalent of the given color. Equals to desaturate by 100%.
+
+    grayscale(#fd0cc7)
+    // => #0cfd42
+
+### tint(color, amount)
+
+Mix the given color with white.
+
+    tint(#fd0cc7,66%)
+    // => #feaceb
+
+### shade(color, amount)
+
+Mix the given color with black.
+
+    shade(#fd0cc7,66%)
+    // => #560443
+
 ### unquote(str | ident)
 
   Unquote the given `str` and returned as a `Literal` node.
- 
+
        unquote("sans-serif")
        // => sans-serif
- 
+
        unquote(sans-serif)
        // => sans-serif
 
@@ -362,25 +438,25 @@ Saturate the given `color` by `amount`.
 
         s('bar(%s)', baz);
         // => bar(baz)
-        
+
         s('bar(%s)', 15px);
         // => bar(15px)
-        
+
         s('rgba(%s, %s, %s, 0.5)', 255, 100, 50);
         // => rgba(255, 100, 50, 0.5)
-        
+
         s('bar(%Z)', 15px);
         // => bar(%Z)
-        
+
         s('bar(%s, %s)', 15px);
         // => bar(15px, null)
-        
+
 Check out the `%` string operator for equivalent behaviour.
 
 ### operate(op, left, right)
 
   Perform the given `op` on the `left` and `right` operands:
-  
+
       op = '+'
       operate(op, 15, 5)
       // => 20
@@ -394,13 +470,13 @@ Check out the `%` string operator for equivalent behaviour.
 
     length((1 2))
     // => 2
-  
+
     length((1))
     // => 1
-  
+
     length(())
     // => 0
-  
+
     length(1 2 3)
     // => 3
 
@@ -410,6 +486,19 @@ Check out the `%` string operator for equivalent behaviour.
     length()
     // => 0
 
+### selector()
+
+Returns the compiled current selector or `&` if called at root level.
+
+    .foo
+      selector()
+    // => '.foo'
+
+    .foo
+      &:hover
+        selector()
+    // '.foo:hover'
+
 ### warn(msg)
 
   Warn with the given error `msg`, does not exit.
@@ -428,12 +517,12 @@ Check out the `%` string operator for equivalent behaviour.
 ### last(expr)
 
  Return the _last_ value in the given `expr`:
- 
+
       nums = 1 2 3
       last(nums)
       last(1 2 3)
       // => 3
-      
+
       list = (one 1) (two 2) (three 3)
       last(list)
       // => (three 3)
@@ -441,7 +530,7 @@ Check out the `%` string operator for equivalent behaviour.
 ### p(expr)
 
  Inspect the given `expr`:
- 
+
      fonts = Arial, sans-serif
      p('test')
      p(123)
@@ -449,10 +538,10 @@ Check out the `%` string operator for equivalent behaviour.
      p(fonts)
      p(#fff)
      p(rgba(0,0,0,0.2))
-     
+
      add(a, b)
        a + b
-    
+
      p(add)
 
 stdout:
@@ -468,7 +557,7 @@ stdout:
 ### opposite-position(positions)
 
  Return the opposites of the given `positions`.
-  
+
      opposite-position(right)
      // => left
 
@@ -518,7 +607,7 @@ yields:
 
   For example if we were to inspect this local variable using `p()`, we
   get the following:
-  
+
         p(current-property)
         // => "foo" (foo __CALL__ bar baz)
 
@@ -551,7 +640,7 @@ yields:
         }
 
   If you noticed in the example above, `bar` is only present for the initial call, since we returned `something(15px)`, it remained in-place within the expression, however the others do not take the rest of the expression into account.
-  
+
   Our more robust solution below, defines a function named `replace()` which clones the expression to prevent mutation, replaces the string value of an expression with another, and returns the cloned expression. We then move on to replace `__CALL__` within the expressions, which represents the cyclic call to `something()`.
 
         replace(expr, str, val)
@@ -582,17 +671,53 @@ yields:
 
 Our implementation is now fully transparent both in regards to the property it is called within, and the position of the call. This powerful concept aids in transparent vendor support for function calls, such as gradients.
 
+### use(path)
+
+You can use any given js-plugin at given `path` with `use()` function right inside your '.styl' files, like this:
+
+    use("plugins/add.js")
+
+    width add(10, 100)
+    // => width: 110
+
+And the `add.js` plugin in this case looks this way:
+
+    var plugin = function(){
+      return function(style){
+        style.define('add', function(a, b) {
+          return a.operate('+', b);
+        });
+      };
+    };
+    module.exports = plugin;
+
+If you'd like to return any Stylus objects like `RGBA`, `Ident` or `Unit`, you could use the provided Stylus nodes like this:
+
+    var plugin = function(){
+      return function(style){
+        var nodes = this.nodes;
+        style.define('something', function() {
+          return new nodes.Ident('foobar');
+        });
+      };
+    };
+    module.exports = plugin;
+
+You can pass any options as an optional second argument, using the [hash object](hashes.html):
+
+    use("plugins/add.js", { foo: bar })
+
 ### Undefined Functions
 
   Undefined functions will output as literals, so for example
   we may call `rgba-stop(50%, #fff)` within our css, and it will
   output as you would expect. We can use this within helpers as well.
-  
-  In the example below we simply define the function `stop()` which 
+
+  In the example below we simply define the function `stop()` which
   returns the literal `rgba-stop()` call.
-  
+
     stop(pos, rgba)
       rgba-stop(pos, rgba)
 
     stop(50%, orange)
-    // => rgba-stop(50%, #ffa500)
\ No newline at end of file
+    // => rgba-stop(50%, #ffa500)

extend.diff

diff --git a/docs/extend.md b/docs/extend.md
index fa09d43..464d551 100644
--- a/docs/extend.md
+++ b/docs/extend.md
@@ -21,9 +21,9 @@
       }
 
 
-### Using `__@extend__`
+### Using __`@extend`__
 
-  To produce this same output with `__@extend__`, simply pass it the desired selector.  Stylus will then append the `.warning` selector to the existing `.message` ruleset.  The `.warning` class then inherits properties from `.message`.
+  To produce this same output with __`@extend`__, simply pass it the desired selector (note that `@extend` and `@extends` are equal, one is just an alias of another).  Stylus will then append the `.warning` selector to the existing `.message` ruleset.  The `.warning` class then inherits properties from `.message`.
 
       .message {
         padding: 10px;
@@ -36,7 +36,7 @@
       }
 
 
-  Here's a more complex example, demonstrating how `__@extend__` cascades:
+  Here's a more complex example, demonstrating how __`@extend`__ cascades:
   
       red = #E33E1E
       yellow = #E2E21E
@@ -85,7 +85,7 @@
         color: #e33e1e;
       }
 
-  Where Stylus currently differs from SASS is, SASS won't allow  `__@extend__` nested selectors:
+  Where Stylus currently differs from SASS is, SASS won't allow  __`@extend`__ nested selectors:
   
      form
        button
@@ -121,3 +121,34 @@
           padding: 10px;
         }
       
+### Extending placeholder selectors
+
+Stylus have the feature similar to the one in [Sass](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#placeholders) — placeholder selectors.
+
+Those selectors should start `$` symbol (for example, `$foo`), and are not yielded in the resulting CSS. But you still can extend them:
+
+    $foo
+      color: #FFF
+
+    $foo2
+      color: red
+
+    .bar
+      background: #000
+      @extends $foo
+
+    .baz
+      @extends $foo
+
+
+Yielding:
+
+    .bar,
+    .baz {
+      color: #fff;
+    }
+    .bar {
+      background: #000;
+    }
+
+Note that if the selector is not extended, it won't be in the resulting CSS, so it's a powerful way to create a library of extendable code. While you can insert code through mixins, they would insert the same code every time you use them, while extending placeholders would give you compact output.

functions.diff

diff --git a/docs/functions.md b/docs/functions.md
index 897c649..4073843 100644
--- a/docs/functions.md
+++ b/docs/functions.md
@@ -42,6 +42,17 @@
      add(a, b = unit(a, px))
        a + b
 
+### Named Parameters
+
+Functions accept named parameters. This frees you from remembering the order of parameters, or simply improves the readability of your code.
+
+For example:
+
+    subtract(a, b)
+      a - b
+
+    subtract(b: 10, a: 25)
+
 ### Function Bodies
 
  We can take our simple `add()` function further. Let's casting all units passed as `px` via the `unit()` built-in. It reassigns each argument, and provides a unit-type string (or identifier), which ignores unit conversion.

media.diff

diff --git a/docs/media.md b/docs/media.md
index 52a893a..736480d 100644
--- a/docs/media.md
+++ b/docs/media.md
@@ -1,4 +1,3 @@
-
 ## @media
 
  The `@media` works just as it does within regular CSS, but with Stylus's block notation:
@@ -16,3 +15,25 @@ Yielding:
           display: none;
         }
       }
+      
+### Media Query Nesting
+
+Media queries can be nested, too, and they will be expanded to wrap the context in which they are used. For example:
+
+    .widget
+      padding 10px
+      
+      @media screen and (min-width: 600px)
+        padding 20px
+
+Yielding:
+
+    .widget {
+      padding: 10px;
+    }
+    
+    @media screen and (min-width: 600px) {
+      .widget {
+        padding: 20px;
+      }
+    }

middleware.diff

diff --git a/docs/middleware.md b/docs/middleware.md
index f2e3c94..2297df8 100644
--- a/docs/middleware.md
+++ b/docs/middleware.md
@@ -1,73 +1,66 @@
 
 ## Connect Middleware
 
- Stylus ships with Connect middleware for auto-compiling Stylus sheets whenever they're modified.
+ Stylus ships with [Connect](http://www.senchalabs.org/connect/) middleware for auto-compiling Stylus sheets whenever they're modified.
 
 ## stylus.middleware(options)
 
- Return Connect middleware with the given `options`.
-
 #### Options
 
-      `force`     When __true__ styles will always re-compile
+Return Connect middleware with the given `options`.
+
+      `serve`     Serve the stylus files from `dest` [true]
+      `force`     Always re-compile
       `src`       Source directory used to find .styl files
       `dest`      Destination directory used to output .css files
                   when undefined defaults to `src`.
-      `compress`  Whether the output .css files should be compressed
       `compile`   Custom compile function, accepting the arguments
-                  `(str, path)` returning the renderer.
+                  `(str, path)`.
+      `compress`  Whether the output .css files should be compressed
       `firebug`   Emits debug infos in the generated css that can
                   be used by the FireStylus Firebug plugin
-      `linenos`   Emits comments in the generated css indicating
+      `linenos`   Emits comments in the generated css indicating 
                   the corresponding stylus line
 
 #### Examples
- 
+
+ Serve .styl files from ./public:
+
+    var app = connect();
+    
+    app.middleware(__dirname + '/public');
+
+ Change the `src` and `dest` options to alter where .styl files
+ are loaded and where they're saved:
+
+     var app = connect();
+     
+     app.middleware({
+       src: __dirname + '/stylesheets',
+       dest: __dirname + '/public'
+     });
+
  Here we set up the custom compile function so that we may
- alter the renderer by providing additional settings.
+ set the `compress` option, or define additional functions.
  
- By default, the compile function simply sets the `filename`
- and renders the CSS.
- 
-        function compile(str, path) {
-          return stylus(str)
-            .import(__dirname + '/css/mixins/blueprint')
-            .import(__dirname + '/css/mixins/css3')
-            .set('filename', path)
-            .set('warn', true)
-            .set('compress', true);
-        }
- 
- Pass the middleware to Connect, grabbing `.styl` files from this directory
- and saving `.css` files to _./public_. Also supplying our custom `compile` function.
- 
- Following that, we have a `static` layer setup to serve the `.css`
- files generated by Stylus.
- 
-        var stylus = require('stylus');
- 
-        var app = connect();
-
-        app.use(stylus.middleware({
-            src: __dirname
-          , dest: __dirname + '/public'
-          , compile: compile
-        }));
-
-        app.use(connect.static(__dirname + '/public'));
-
- When `force` is used, the styles will unconditionally be re-compiled. But even without this option, the Stylus middleware is smart enough to detect changes in `@import`ed files.
-
- For development purposes, you can enable the `firebug` option if you want to
- use the [FireStylus extension for Firebug](//github.com/LearnBoost/stylus/blob/master/docs/firebug.md) 
- and/or the `linenos` option to emit debug info in the generated CSS.
-
-        function compile(str, path) {
-          return stylus(str)
-            .import(__dirname + '/css/mixins/blueprint')
-            .import(__dirname + '/css/mixins/css3')
-            .set('filename', path)
-            .set('warn', true)
-            .set('firebug', true)
-            .set('linenos', true);
-        }
+ By default the compile function simply sets the `filename`
+ and renders the CSS. In the following case we're compressing
+ the output, using the "nib" library plugin, and auto-importing it.
+
+     function compile(str, path) {
+       return stylus(str)
+         .set('filename', path)
+         .set('compress', true)
+         .use(nib())
+         .import('nib');
+     }
+
+ Pass it as an option like so:
+
+     var app = connect();
+
+     app.middleware({
+         src: __dirname
+       , dest: __dirname + '/public'
+       , compile: compile
+     })

operators.diff

diff --git a/docs/operators.md b/docs/operators.md
index 94f28ad..1f86207 100644
--- a/docs/operators.md
+++ b/docs/operators.md
@@ -133,7 +133,7 @@ Multiplicative and additive binary operators work as expected. Type conversion i
 ### Multiplicative: / * %
 
     2000ms + (1s * 2)
-    // => 4ms
+    // => 4000ms
 
     5s / 2
     // => 2.5s