stylus-source 0.22.6 → 0.23.0

data/vendor/docs/gedit.md

@@ -12,7 +12,7 @@
  
     mkdir -p ~/.local/share/gtksourceview-2.0/language-specs/ && wget https://raw.github.com/LearnBoost/stylus/master/editors/gedit/styl.lang -O ~/.local/share/gtksourceview-2.0/language-specs/styl.lang
 
- Update the mime database and enjoy Stylus syntax in gedit!
+ Update the MIME database and enjoy Stylus syntax in gedit!
  
     cd ~/.local/share
     update-mime-database mime

data/vendor/docs/import.md

@@ -4,21 +4,23 @@
 
 ### Literal CSS
 
-  Any filename with the extension `.css` will become a literal, for example:
+  Any filename with the extension `.css` will become a literal. For example:
   
      @import "reset.css"
 
-will render to the literal css __@import__ shown below:
+Render the literal CSS __@import__ shown below:
 
      @import "reset.css"
 
 ### Stylus Import
 
- When using __@import__ without the `.css` extension, it is assumed to be a Stylus sheet, for example `@import "mixins/border-radius"`.
+ When using __@import__ without the `.css` extension, it's assumed to be a Stylus sheet (e.g., `@import "mixins/border-radius"`).
 
- __@import__ works by iterating an array of directories, and seeing if this file lives in any of them, similar to node's `require.paths`. This array defaults to a single path which is derived from the `filename` option's dirname. So if your filename is `/tmp/testing/stylus/main.styl`, then import will look in `/tmp/testing/stylus/`.
+ __@import__ works by iterating an array of directories, and checking if this file lives in any of them (similar to node's `require.paths`). This array defaults to a single path, which is derived from the `filename` option's `dirname`. So, if your filename is `/tmp/testing/stylus/main.styl`, then import will look in `/tmp/testing/stylus/`.
  
- __@import__ also supports index styles, meaning if you `@import blueprint`, it will resolve either `blueprint.styl` or `blueprint/index.styl`, useful for libraries to expose all of their features, but still allow a subset of the library to be imported. For example a common lib structure might be:
+ __@import__ also supports index styles. This means when you `@import blueprint`, it will resolve **either** `blueprint.styl` **or** `blueprint/index.styl`.  This is really useful for libraries that want to expose all their features, while still allowing feature subsets to be imported. 
+ 
+ For example, a common lib structure might be:
 
     ./tablet
       |-- index.styl 
@@ -26,7 +28,7 @@ will render to the literal css __@import__ shown below:
       |-- buttons.styl 
       |-- images.styl 
 
- In the example below we set the `paths` options to provide additional paths to Stylus. Within `./test.styl` we could then `@import "mixins/border-radius"` or `@import "border-radius"` since `./mixins` is exposed to Stylus.
+ In the example below, we set the `paths` options to provide additional paths to Stylus. Within `./test.styl`, we could then `@import "mixins/border-radius"`, or `@import "border-radius"` (since `./mixins` is exposed to Stylus).
 
       /**
        * Module dependencies.
@@ -63,11 +65,11 @@ will render to the literal css __@import__ shown below:
          console.log(css);
        });
 
- The following are essentially equivalent:
+ The following statement...
  
      @import 'mixins/vendor'
 
-and
+...is equivalent to...
 
      .import('mixins/vendor') 
  

data/vendor/docs/interpolation.md

@@ -1,7 +1,7 @@
 
 ## Interpolation
 
-  Stylus supports interpolation by using the `{}` characters to surround an expression, which then becomes part of the identifier. For example `-webkit-{'border' + '-radius'}` would evaluate to `-webkit-border-radius`.
+  Stylus supports interpolation by using the `{}` characters to surround an expression, which then becomes part of the identifier. For example, `-webkit-{'border' + '-radius'}` evaluates to `-webkit-border-radius`.
 
  A great example use-case for this is expanding properties with vendor prefixes.
 
@@ -19,7 +19,7 @@
       button
         border-radius 1px 2px / 3px 4px
 
-yielding:
+Yields:
 
       button {
         -webkit-border-radius: 1px 2px / 3px 4px;
@@ -29,14 +29,14 @@ yielding:
 
 ## Selector Interpolation
 
- Interpolation works with selectors as well, for example we may iterate while assigning the `height` property for the first 5 rows in a table as shown below.
+ Interpolation works with selectors as well. For example, we may iterate to assign the `height` property for the first 5 rows in a table, as shown below:
 
     table
       for row in 1 2 3 4 5
         tr:nth-child({row})
           height: 10px * row
 
-yielding:
+Yields:
 
     table tr:nth-child(1) {
       height: 10px;

data/vendor/docs/introspection.md

@@ -1,17 +1,16 @@
 
 ## Introspection API
 
- Stylus supports an introspection API, allowing mixins and functions to reflect relative to the caller etc.
+ Stylus supports an introspection API. This allows mixins and functions to reflect relative to the caller, etc.
 
 
 ## mixin
 
-  The `mixin` local variable is automatically assigned within function bodies,
-  containing the string "root" indicating the function is called at the root
-  level, or "block" indicating otherwise, and finally `false` if the function
-  is invoked expecting a return value.
+  The `mixin` local variable is automatically assigned within function bodies.
+  It contains the string `root` if the function was called at the root
+  level, or `block` indicating otherwise, and finally `false` if the invoked function expects a return value.
 
-  In the following example we define `reset()` altering its behaviour when mixed in to root, another block, or a return value as used in the `foo` property below. 
+  In the following example, we define `reset()` to alter its behaviour depending on whether it's mixed into root, into another block, or into a return value, as used in the `foo` property below:
 
       reset()
         if mixin == 'root'
@@ -28,7 +27,7 @@
         reset()
         foo reset()
 
-compiles to:
+Compiles to:
 
         got {
           root: true;

data/vendor/docs/iteration.md

@@ -11,7 +11,7 @@ For example:
       for num in 1 2 3
         foo num
 
-yields:
+Yields:
 
       body {
         foo: 1;
@@ -26,7 +26,7 @@ The example below shows how to use the `<key-name>`:
         for font, i in fonts
           foo i font
 
-yielding:
+Yielding:
 
         body {
           foo: 0 Impact;
@@ -36,7 +36,9 @@ yielding:
 
 ### Mixins
 
- We may utilize iteration within mixins to produce powerful functionality, for example we can apply expression pairs as properties using interpolation and iteration. Below we define `apply()`, conditionally utilizing all the `arguments` so that comma-delimited _and_ expression lists are supported:
+ We can use iteration within mixins to produce powerful functionality. For example, we can apply expression pairs as properties using interpolation and iteration. 
+ 
+ Below we define `apply()`, conditionally utilizing all the `arguments` so that comma-delimited _and_ expression lists are supported:
  
      apply(props)
        props = arguments if length(arguments) > 1
@@ -52,9 +54,9 @@ yielding:
 
 ### Functions
 
- Stylus functions may also contain for-loops, below are some example use-cases:
+ Stylus functions may also contain for-loops. Below are some example use-cases:
 
-sum:
+Sum:
 
       sum(nums)
         sum = 0

data/vendor/docs/js.md

@@ -1,6 +1,8 @@
 ## JavaScript API
 
-Simply require the module, and call `render()` with the given string of stylus code, and (optional) options object. Frameworks utilizing stylus should pass the `filename` option to provide better error reporting.
+Simply `require` the module, and call `render()` with the given string of Stylus code, and (optional) `options` object. 
+
+Frameworks utilizing Stylus should pass the `filename` option to provide better error reporting.
 
     var stylus = require('stylus');
 
@@ -28,7 +30,7 @@ We can also do the same thing in a more progressive manner:
 
 ### .include(path)
 
-  A progressive alternative to setting `paths` via `.set()`, which is ideal when exposing external stylus libraries which expose a path.
+  A progressive alternative to `.set('paths',...)` is `.include()`.  This is ideal when exposing external Stylus libraries which expose a path.
   
     stylus(str)
       .include(require('nib').path)
@@ -52,12 +54,14 @@ Defer importing of the given `path` until evaluation is performed. The example b
 
 ### .define(name, node)
 
- By passing a `Node`, we may define a global variable. This is useful when exposing conditional features within your library depending on the availability of another. For example the "Nib" extensions library conditionally supports node-canvas, providing image generation, however this is not always available, so Nib may define:
+ By passing a `Node`, we may define a global variable. This is useful when exposing conditional features within your library depending on the availability of another. For example the **Nib** extension library conditionally supports node-canvas, providing image generation. 
+ 
+ However, this is not always available, so Nib may define:
  
      .define('has-canvas', stylus.nodes.false);
      .define('some-setting', new stylus.nodes.String('some value'));
 
- Stylus also casts JavaScript values to their Stylus equivalents when possible, the following are a few examples:
+ Stylus also casts JavaScript values to their Stylus equivalents when possible. Here are a few examples:
 
      .define('string', 'some string')
      .define('number', 15.5)
@@ -67,11 +71,17 @@ Defer importing of the given `path` until evaluation is performed. The example b
      .define('list', { foo: 'bar', bar: 'baz' })
      .define('families', ['Helvetica Neue', 'Helvetica', 'sans-serif'])
 
+  These same rules apply to return values in js functions as well:
+
+     .define('get-list', function(){
+       return ['foo', 'bar', 'baz'];
+     })
+
 ### .define(name, fn)
 
- This method allows you to provide a JavaScript-defined function to Stylus, think of these as you would JavaScript to C++ bindings. When you have something you cannot do within Stylus, you define it in JavaScript.
+ This method allows you to provide a JavaScript-defined function to Stylus. Think of these as you would JavaScript-to-C++ bindings. When there's something you cannot do in Stylus, define it in JavaScript!
 
-In our example we define four functions `add()`, `sub()`, `image-width()`, and `image-height()`. These functions must return a `Node`, this constructor and the other nodes are available via `stylus.nodes`.
+In this example, we define four functions: `add()`, `sub()`, `image-width()`, and `image-height()`. These functions must return a `Node`, this constructor and the other nodes are available via `stylus.nodes`.
 
       var stylus = require('../')
         , nodes = stylus.nodes
@@ -128,10 +138,10 @@ In our example we define four functions `add()`, `sub()`, `image-width()`, and `
           console.log(css);
         });
 
- For further reference until documentation is complete please reference the following files:
+ For further reference (until documentation is complete) please see the following files:
  
-   - lib/nodes/*
-   - lib/utils.js
+   - `lib/nodes/*`
+   - `lib/utils.js`
 
 ### .use(fn)
 

data/vendor/docs/keyframes.md

@@ -53,7 +53,9 @@ yielding:
 
 ## Expansion
 
- By utilizing `@keyframes` your rules are automatically expanded to the vendor prefixes defined by the `vendors` variable, defaulting to `webkit moz official`. This means we can alter it at any time for the expansion to take effect immediately. For example consider the following
+ By using `@keyframes`, your rules are automatically expanded to the vendor prefixes defined by the `vendors` variable (default: `webkit moz official`). This means we can alter it at any time for the expansion to take effect immediately. 
+ 
+ For example, consider the following:
 
     @keyframes foo {
       from {
@@ -64,7 +66,7 @@ yielding:
       }
     }
 
-expands to our two default vendors and the official syntax:
+This expands to our two default vendors, and the official syntax:
 
     @-moz-keyframes foo {
       0% {
@@ -94,7 +96,7 @@ expands to our two default vendors and the official syntax:
       }
     }
 
-if we wanted to limit to the official syntax only, simply alter `vendors`:
+If we wanted to limit to the official syntax only, simply alter `vendors`:
 
     vendors = official
 
@@ -107,7 +109,7 @@ if we wanted to limit to the official syntax only, simply alter `vendors`:
       }
     }
 
-yielding:
+Yielding:
 
     @keyframes foo {
       0% {

data/vendor/docs/kwargs.md

@@ -1,10 +1,9 @@
 
 ## Keyword Arguments
 
- Stylus supports keyword arguments, or "kwargs", allowing you to key
- arguments by their associated parameter name.
+ Stylus supports keyword arguments, or "kwargs". These allow you to reference arguents by their associated parameter name.
 
- The examples shown below are functionally equivalent, however we can
+ The examples shown below are functionally equivalent. However, we can
  place keyword arguments anywhere within the list. The remaining arguments
  that are _not_ keyed will be applied to the parameters that have not
  been satisfied.
@@ -16,7 +15,7 @@
         color: rgba(alpha: 0.5, blue: 100, 255, 200);
       }
 
- yielding:
+ Yielding:
  
        body {
          color: rgba(255,200,100,0.5);
@@ -30,6 +29,6 @@
  
     p(rgba)
 
- yielding:
+ Yielding:
 
     inspect: rgba(red, green, blue, alpha)

data/vendor/docs/literal.md

@@ -1,6 +1,6 @@
 ## Literal CSS
 
- If for any reason Stylus cannot accommodate a specific need, you can always resort to literal css via `@css`:
+ If for any reason Stylus cannot accommodate a specific need, you can always resort to literal CSS with `@css`:
  
      
      @css {
@@ -9,7 +9,7 @@
        }
      }
 
-compiling to:
+Compiling to:
 
     body {
       font: 14px;

data/vendor/docs/media.md

@@ -1,14 +1,14 @@
 
 ## @media
 
- The `@media` works just as it does within regular css, however with Stylus block notation:
+ The `@media` works just as it does within regular CSS, but with Stylus's block notation:
 
      @media print
        #header
        #footer
          display none
 
-yielding:
+Yielding:
 
       @media print {
         #header,

data/vendor/docs/middleware.md

@@ -1,7 +1,7 @@
 
 ## Connect Middleware
 
- Stylus ships with Connect middleware for auto-compiling Stylus sheets when modified.
+ Stylus ships with Connect middleware for auto-compiling Stylus sheets whenever they're modified.
 
 ## stylus.middleware(options)
 
@@ -26,7 +26,7 @@
  Here we set up the custom compile function so that we may
  alter the renderer by providing additional settings.
  
- By default the compile function simply sets the `filename`
+ By default, the compile function simply sets the `filename`
  and renders the CSS.
  
         function compile(str, path) {
@@ -38,10 +38,10 @@
             .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.
+ 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 `staticProvider` layer setup to serve the .css
+ Following that, we have a `staticProvider` layer setup to serve the `.css`
  files generated by Stylus.
  
         var stylus = require('stylus');
@@ -55,12 +55,11 @@
           , connect.staticProvider(__dirname + '/public')
         );
 
- When `force` is used, the styles will be unconditionally re-compiled, however
- even without this option the Stylus middleware is smart enough to detect changes in `@import`ed files.
+ 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 purpose, you can enable the `firebug` option if you want to
+ 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 infos in the generated css.
+ and/or the `linenos` option to emit debug info in the generated CSS.
 
         function compile(str, path) {
           return stylus(str)

data/vendor/docs/mixins.md

@@ -1,7 +1,9 @@
 
 ## Mixins
 
-Both mixins and functions are defined in the same manor, however they are applied in different ways. For example we have a `border-radius(n)` function defined below, which is invoked as a _mixin_, aka a statement rather than part of an expression.
+Both mixins and functions are defined in the same manner, but they are applied in different ways. 
+
+For example, we have a `border-radius(n)` function defined below, which is invoked as a _mixin_ (i.e., invoked as a statement, rather than part of an expression).
 
 When `border-radius()` is invoked within a selector, the properties are expanded and copied into the selector.
 
@@ -13,7 +15,7 @@ When `border-radius()` is invoked within a selector, the properties are expanded
     form input[type=button]
       border-radius(5px)
 
-compiles to:
+Compiles to:
 
     form input[type=button] {
       -webkit-border-radius: 5px;
@@ -21,7 +23,7 @@ compiles to:
       border-radius: 5px;
     }
 
-When utilizing mixins, we can omit the parens all together, providing is with fantastic transparent vendor property support:
+When using mixins you can omit the parentheses altogether, providing fantastic transparent vendor property support!
 
     border-radius(n)
       -webkit-border-radius n
@@ -31,16 +33,18 @@ When utilizing mixins, we can omit the parens all together, providing is with fa
     form input[type=button]
       border-radius 5px
 
-Note that the `border-radius` within our mixin is treated as a property, and not a recursive function invocation. To take this further we we may utilize the automatic `arguments` local variable, containing the expression passed, allowing more than one value to be passed:
+Note that the `border-radius` within our mixin is treated as a property, and not a recursive function invocation. 
+
+To take this further, we can utilize the automatic `arguments` local variable, containing the expression passed, allowing multiple values to be passed:
 
     border-radius()
       -webkit-border-radius arguments
       -moz-border-radius arguments
       border-radius arguments
 
-now allowing us to pass values such as `border-radius 1px 2px / 3px 4px`.
+Now we can pass values like `border-radius 1px 2px / 3px 4px`!
 
-Another great example of this, is adding transparent support for vendor specifics such as `opacity` support for IE:
+Another great use of this is the addition of transparent support for vendor-specifics—such as `opacity` support for IE:
 
         support-for-ie ?= true
 
@@ -53,7 +57,7 @@ Another great example of this, is adding transparent support for vendor specific
           &:hover
             opacity 0.5
 
-rendering:
+Rendering:
 
         #logo:hover {
           opacity: 0.5;
@@ -62,7 +66,9 @@ rendering:
 
 ### Parent References
 
- Mixins may utilize the parent reference character `&`, acting on the parent instead of further nesting. For example lets say we wish to create a `stripe(even, odd)` mixin for striping table row, we provide both `even` and `odd` with default color values, and assign the `background-color` property on the row. Nested within the `tr` we use `&` to reference the `tr`, providing the `even` color.
+ Mixins may utilize the parent reference character `&`, acting on the parent instead of further nesting. 
+ 
+ For example, let's say we want to create a `stripe(even, odd)` mixin for striping table rows. We provide both `even` and `odd` with default color values, and assign the `background-color` property on the row. Nested within the `tr` we use `&` to reference the `tr`, providing the `even` color.
  
      stripe(even = #fff, odd = #eee)
        tr
@@ -83,7 +89,7 @@ We may then utilize the mixin as shown below:
        td
          color white
 
-Another way to define the `stripe()` mixin without parent reference:
+Alternatively, `stripe()` could be defined without parent references:
 
     stripe(even = #fff, odd = #eee)
       tr
@@ -98,7 +104,9 @@ If we wished, we could invoke `stripe()` as if it were a property:
 
 ### Mixing Mixins in Mixins
 
- Mixins can of course utilize other mixins, to build up their own selector's and properties. For example, below we create `comma-list()` to inline (via `inline-list()`) and comma-separate an un-ordered list.
+ Mixins can (of course!) utilize other mixins, building upon their own selectors and properties. 
+ 
+ For example, below we create `comma-list()` to inline (via `inline-list()`) and comma-separate an unordered list.
  
  
      inline-list()
@@ -116,7 +124,7 @@ If we wished, we could invoke `stripe()` as if it were a property:
      ul
        comma-list()
 
-rendering:
+Rendering:
 
     ul li:after {
       content: ", ";