stylus-source 0.22.6 → 0.23.0

data/VERSION

@@ -1 +1 @@
-0.22.6
+0.23.0

data/vendor/History.md

@@ -1,4 +1,10 @@
 
+0.23.0 / 2012-02-02 
+==================
+
+  * Added `Renderer` "end" event
+  * Cleaned up documentation grammar etc [Zearin]
+
 0.22.6 / 2012-01-20 
 ==================
 

data/vendor/docs/comments.md

@@ -1,7 +1,7 @@
 
 ## Comments
 
-  Stylus supports three kinds of comments, single-line, and multi-line comments, and multi-line buffered comments.
+  Stylus supports three kinds of comments: single-line, and multi-line comments, and multi-line buffered comments.
 
 ## Single-line
 
@@ -13,7 +13,7 @@
 
 ## Multi-line
 
-   Multi-line comments look identical to regular CSS comments, however they only output when the `compress` option is not enabled.
+   Multi-line comments look identical to regular CSS comments. However, they only output when the `compress` option is not enabled.
 
     /*
      * Adds the given numbers together.
@@ -24,7 +24,7 @@
 
 ## Multi-line buffered
 
-   Multi-line comments which are not suppressed start with `/*!`, signalling Stylus to output the comment regardless of compression.
+   Multi-line comments which are not suppressed start with `/*!`. This tells Stylus to output the comment regardless of compression.
 
     /*!
      * Adds the given numbers together.

data/vendor/docs/conditionals.md

@@ -7,7 +7,7 @@
 
  The `if` conditional works as you would expect, simply accepting an expression, evaluating the following block when `true`. Along with `if` are the typical `else if` and `else` tokens, acting as fallbacks.
  
- The example below would conditionally overload the `padding` property, swapping it for margin.
+ The example below would conditionally overload the `padding` property, swapping it for `margin`.
 
     overload-padding = true
 
@@ -38,9 +38,9 @@ Another `box()` helper:
 
 ### unless
 
- For users familiar with the ruby programming language, we have the `unless` conditional, which is essentially the opposite of `if`, essentially `if (!(expr))`.
+ For users familiar with the Ruby programming language, we have the `unless` conditional. It’s basically the opposite of `if`—essentially `if (!(expr))`.
 
-In the example below, if `disable-padding-override` is undefined or `false` padding will be overridden, displaying `margin` instead. However when `true` padding will remain outputting `padding 5px 10px` as expected.
+In the example below, if `disable-padding-override` is `undefined` or `false`, `padding` will be overridden, displaying `margin` instead. But if it’s `true`, `padding` will continue outputting `padding 5px 10px` as expected.
 
      disable-padding-override = true
 
@@ -53,10 +53,10 @@ In the example below, if `disable-padding-override` is undefined or `false` padd
 
 ### Postfix Conditionals
 
-  Stylus supports postfix conditionals, meaning the `if` and `unless` act as operators, evaluating the left-hand operand, when the right-hand expression is truthy.
+  Stylus supports postfix conditionals. This means that `if` and `unless` act as operators; they evaluate the left-hand operand when the right-hand expression is truthy.
   
   
-  For example let's define `negative()`, performing some basic type checking. Below we use block-style conditionals:
+  For example let's define `negative()` to perform some basic type checking. Below we use block-style conditionals:
   
       negative(n)
         unless n is a 'unit'
@@ -66,16 +66,16 @@ In the example below, if `disable-padding-override` is undefined or `false` padd
         else
           no
 
-  Next we utilize postfix conditionals to keep our function terse.
+  Next, we utilize postfix conditionals to keep our function terse.
 
       negative(n)
         error('invalid number') unless n is a 'unit'
         return yes if n < 0
         no
 
-  Of course we could take this further, and utilize `n < 0 ? yes : no`, or simply stick with booleans, and use only `n < 0`.
+  Of course, we could take this further.  For example, we could write `n < 0 ? yes : no`, or simply stick with booleans: `n < 0`.
 
-  Postfix conditionals may be applied to most single-line statements, for example `@import`, `@charset`, mixins, and of course properties as shown below:
+  Postfix conditionals may be applied to most single-line statements. For example, `@import`, `@charset`, mixins—and of course, properties as shown below:
   
   
       pad(types = margin padding, n = 5px)

data/vendor/docs/css-style.md

@@ -1,7 +1,7 @@
 
 ## CSS Style
 
- Stylus transparently supports a regular css-style syntax, meaning you do not need to use an alternative parser, or specify that a certain file is using a specific style.
+ Stylus transparently supports a regular CSS-style syntax. This means you don't need an alternative parser, or specify that a certain file uses a specific style.
 
 ### Example
 
@@ -22,7 +22,7 @@
        border 1px solid
        border-radius 5px
 
- Since braces, colons, and semi-colons are optional, we could write this example just as we would with normal css:
+ Since braces, colons, and semi-colons are optional, we could write this example just as we would with normal CSS:
  
      border-radius() {
        -webkit-border-radius: arguments;
@@ -60,7 +60,7 @@
        border: 1px solid;
        border-radius: 5px;
 
- Variables, functions, mixins, and all of the other features that Stylus provides still work as expected:
+ Variables, functions, mixins, and all the other features provided by Stylus still work as expected:
  
      main-color = white
      main-hover-color = black
@@ -72,6 +72,6 @@
 
      body a { color: main-color; &:hover { color: main-hover-color; }}
 
- There are currently a few exceptions to this rule, since the two styles may be mixed and matched some indentation rules still apply. So although not _every_ plain-css stylesheet will work without modification this feature still allows those who prefer css syntax may still utilize the other powerful features provided by Stylus.
+ There are a few caveats to this rule: since the two styles may be mixed and matched, some indentation rules still apply. So although not _every_ plain-CSS stylesheet will work with zero modification, this feature allows those who prefer CSS syntax to continue doing so while leveraging Stylus' other powerful features.
  
 

data/vendor/docs/error-reporting.md

@@ -1,7 +1,7 @@
 
 ## Error Reporting
 
- Stylus has fantastic error reporting built in for syntax, parse, and evaluation errors, complete with stack traces, line numbers, and filenames.
+ Stylus has fantastic error reporting built-in for syntax, parse, and evaluation errors—complete with stack traces, line numbers, and filenames.
 
 ### Parse Error
 
@@ -11,7 +11,7 @@ Parse error example:
        form input
          == padding 5px
 
-yielding:
+Yielding:
 
      Error: /Users/tj/Projects/stylus/testing/test.styl:4
        3: '  form input'
@@ -21,7 +21,7 @@ yielding:
 
 ### Evaluation Error
 
- This "runtime" or evaluation error is caused due to passing a string to `border-radius()` instead of the expected `Unit` by using our helper `ensure(n, 'unit')`.
+ This "runtime" or evaluation error is caused by passing a string to `border-radius()`, instead of the expected `Unit` (by using our helper `ensure(n, 'unit')`).
 
       ensure(val, type)
         unless val is a type
@@ -36,7 +36,7 @@ yielding:
       body
         border-radius '5px'
 
-yielding:
+Yielding:
 
       Error: /Users/tj/Projects/stylus/examples/error.styl:12
         11: ''

data/vendor/docs/escape.md

@@ -1,11 +1,13 @@
 ## Escaping
 
- Stylus allows you to escape characters, effectively turning them into identifiers, so that they can be rendered as literals. For example:
+ Stylus lets you escape characters. This effectively turns them into identifiers, allowing them to be rendered as literals. 
+ 
+ For example:
 
      body
        padding 1 \+ 2
 
-will compile to:
+Compiles to:
 
      body {
        padding: 1 + 2;

data/vendor/docs/executable.md

@@ -1,7 +1,7 @@
 
 ## Stylus Executable
 
-Stylus ships with the `stylus` executable for converting stylus to css.
+Stylus ships with the `stylus` executable for converting Stylus to CSS.
 
       Usage: stylus [options] [command] [< in [> out]]
                     [file|dir ...]
@@ -9,7 +9,7 @@ Stylus ships with the `stylus` executable for converting stylus to css.
       Commands:
 
         help <prop>     Opens help info for <prop> in
-                        your default browser. (osx only)
+                        your default browser. (OS X only)
 
       Options:
 
@@ -17,15 +17,15 @@ Stylus ships with the `stylus` executable for converting stylus to css.
         -i, --interactive       Start interactive REPL
         -w, --watch             Watch file(s) for changes and re-compile
         -o, --out <dir>         Output to <dir> when passing files
-        -C, --css <src> [dest]  Convert css input to stylus
+        -C, --css <src> [dest]  Convert CSS input to Stylus
         -I, --include <path>    Add <path> to lookup paths
-        -c, --compress          Compress css output
+        -c, --compress          Compress CSS output
         -d, --compare           Display input along with output
         -f, --firebug           Emits debug infos in the generated css that
                                 can be used by the FireStylus Firebug plugin
-        -l, --line-numbers      Emits comments in the generated css
-                                indicating the corresponding stylus line
-        -V, --version           Display the version of stylus
+        -l, --line-numbers      Emits comments in the generated CSS
+                                indicating the corresponding Stylus line
+        -V, --version           Display the version of Stylus
         -h, --help              Display help information
 
 ### STDIO Compilation Example
@@ -34,7 +34,7 @@ Stylus ships with the `stylus` executable for converting stylus to css.
 
       $ stylus --compress < some.styl > some.css
 
-Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
+Try Stylus some in the terminal!  Type below and press `CTRL-D` for `__EOF__`:
 
       $ stylus
       body
@@ -43,7 +43,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
 
 ### Compiling Files Example
 
- `stylus` also accepts files and directories, for example a directory named `css` will compile and output the `.css` files in the same directory.
+ `stylus` also accepts files and directories. For example, a directory named `css` will compile and output `.css` files in the same directory.
  
       $ stylus css
 
@@ -55,8 +55,8 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
 
       $ stylus one.styl two.styl
 
-  For development purpose, you can enable the `linenos` option to emit comments indicating 
-  the Stylus filename and line number in the generated css:
+  For development purposes, you can use the `linenos` option to emit comments indicating 
+  the Stylus filename and line number in the generated CSS:
 
       $ stylus --line-numbers <path>
 
@@ -67,7 +67,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
 
 ### Converting CSS
 
- If we wish to convert css to the terse Stylus syntax, we can utilize the `--css` flag.
+ If you wish to convert CSS to the terse Stylus syntax, use the `--css` flag.
 
  Via stdio:
  
@@ -83,14 +83,16 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
 
 ### CSS Property Help
 
-  On osx `stylus help <prop>` will open your default browser and display help documentation for the given `<prop>`.
+  On OS X, `stylus help <prop>` will open your default browser and display help documentation for the given `<prop>`.
 
     $ stylus help box-shadow
 
 ### Interactive Shell
 
  The Stylus REPL (Read-Eval-Print-Loop) or "interactive shell" allows you to
- play around with Stylus expressions directly from your terminal. Note that this works only for expressions, not selectors etc. To use simple add the `-i`, or `--interactive` flag:
+ play around with Stylus expressions directly from your terminal. 
+ 
+ **Note that this works only for expressions**—not selectors, etc. To use simple add the `-i`, or `--interactive` flag:
  
      $ stylus -i
      > color = white
@@ -108,7 +110,9 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
 
 ### Utilizing Plugins
 
- For our examples we will utilize the [nib](https://github.com/visionmedia/nib) Stylus plugin to illustrate it's CLI usage. Suppose we have the following stylus, importing nib and utilize it's `linear-gradient()` function.
+ For this example we'l use the [nib](https://github.com/visionmedia/nib) Stylus plugin to illustrate its CLI usage. 
+ 
+ Suppose we have the following Stylus, which imports nib to use its `linear-gradient()` function.
  
      @import 'nib'
 
@@ -119,7 +123,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
  
      $ stylus < test.styl
 
- Which would yield the following error because stylus does not know where to find nib in our machine.
+ Which would yield the following error (because Stylus doesn't know where to find nib).
 
        Error: stdin:3
           1| 
@@ -129,11 +133,11 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
           5| body
           6|   background: linear-gradient(20px top, white, black)
 
-  For plugins that simply supply stylus APIs we could add the path to the stylus lookup paths by using the `--include` or `-I` flag:
+  For plugins that simply supply Stylus APIs, we could add the path to the Stylus lookup paths.  We do so by using the `--include` or `-I` flag:
 
      $ stylus < test.styl --include ../nib/lib
 
-  Now yielding the following output. As you might notice the calls to `gradient-data-uri()` and `create-gradient-image()` output as literals, this is because exposing the library path is not enough when the plugin provides a JavaScript API, though if we wished to only utilize the pure-stylus nib functions we would be fine. 
+  Now yielding the output below. (As you might notice, calls to `gradient-data-uri()` and `create-gradient-image()` output as literals. This is because exposing the library path isn't enough when a plugin provides a JavaScript API.  However, if we only wanted to use pure-Stylus nib functions, we'd be fine.)
 
       body {
         background: url(gradient-data-uri(create-gradient-image(20px, top)));
@@ -143,7 +147,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
         background: linear-gradient(top, #fff 0%, #000 100%);
       }
 
-  So, what we need to do is utilize the `--use`, or `-u` flag which expects a path to a node module, with or without the ".js" extension. This `require()`s the module, expecting a function to be exported as `module.exports`, which then calls `style.use(fn())` to allow the plugin to expose itself, defining js functions etc.
+  So, what we need to do is use the `--use`, or `-u` flag.  It expects a path to a node module (with or without the `.js` extension). This `require()`s the module, expecting a function to be exported as `module.exports`, which then calls `style.use(fn())` to expose the plugin (defining its js functions, etc.).
   
     $ stylus < test.styl --use ../nib/lib/nib
 

data/vendor/docs/extend.md

@@ -1,9 +1,14 @@
 
 ## Extend
 
-  The Stylus __@extend__ directive is inspired by, and is essentially the same as the [SASS Implementation](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#extend), with few subtle differences. This feature makes maintaining semantic rulesets which inherit from others extremely simple.
+  The Stylus __@extend__ directive is inspired by (and essentially the same as) the [SASS Implementation](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#extend), with few subtle differences. This feature significantly simplifies maintenance of semantic rulesets that inherit from other semantic rulesets.
 
-  While the use of mixins can achieve a similar effect it can to duplicate CSS. A typical pattern is to define several classes as shown below, then combine them on the element such as "warning message". While this technique works just fine, it's difficult to maintain.
+
+### “Extending” with mixins
+
+  Although you can use mixins to achieve a similar effect, this can lead to duplicate CSS. A typical pattern is to define several classes as shown below, then combine them on the element such as "warning message". 
+  
+  While this technique works just fine, it's difficult to maintain.
 
       .message,
       .warning {
@@ -16,7 +21,9 @@
       }
 
 
-  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 so that it inherits its properties as well.
+### 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`.
 
       .message {
         padding: 10px;
@@ -29,7 +36,7 @@
       }
 
 
-  The following is a more complex example, showing how __@extend__ cascades:
+  Here's a more complex example, demonstrating how `__@extend__` cascades:
   
       red = #E33E1E
       yellow = #E2E21E
@@ -78,7 +85,7 @@
         color: #e33e1e;
       }
 
-  Where Stylus currently differs from SASS is that SASS will not allow you __@extend__ nested selectors:
+  Where Stylus currently differs from SASS is, SASS won't allow  `__@extend__` nested selectors:
   
      form
        button
@@ -90,7 +97,7 @@
              on line 6 of standard input
        Use --trace for backtrace.
 
-   With Stylus as long as the selectors match it'll work:
+   With Stylus, as long as the selectors match, it works!
    
        form
          input[type=text]
@@ -102,7 +109,7 @@
          @extends form input[type=text]
          padding: 10px
 
-   Would yield:
+   Yielding:
    
         form input[type=text],
         form textarea {

data/vendor/docs/firebug.md

@@ -12,14 +12,14 @@ the Stylus-generated CSS styles rather than those of the generated CSS.
 First, you need to install [Firebug](https://addons.mozilla.org/firefox/downloads/latest/1843/addon-1843-latest.xpi?src=addondetail)
 and the [FireStylus extension](//github.com/parallel/firestylus)
 
-Then, you need to enable the Stylus's `firebug` option when generating your CSS.
+Then simply enable the Stylus's `firebug` option when generating CSS.
 
-Command line
+Command line usage:
 
 	$ stylus -f <path>
 	$ stylus --firebug <path>
 	
-Javascript API
+Javascript usage:
 
 	var stylus = require('stylus');
 
@@ -29,7 +29,7 @@ Javascript API
 		// logic
 	  });
 
-Connect / Express
+Connect / Express:
 
     var stylus = require('stylus');
 
@@ -44,8 +44,7 @@ Connect / Express
 
 ### Compatibility
 
- FireStylus should work with all versions of Firefox after 
- and including 3.0, and all Firebug versions after and including 1.4
+ FireStylus should work with Firefox versions 3.0 and up, and with Firebug versions 1.4 and up.
 
  - Firefox 3+ (also works with version 5)
  - Firebug 1.4+
@@ -55,6 +54,6 @@ Connect / Express
 FireStylus and FireSass are incompatible. You cannot enable them
 simultaneously.
 
-FireStylus (like FireSass) only works in the html pane of firebug, the others,
-such as the css pane won't work due to firebug limitations.
+FireStylus (like FireSass) only works in the HTML pane of Firebug. The others
+(such as the CSS pane) won't work due to Firebug limitations.
 

data/vendor/docs/font-face.md

@@ -1,7 +1,7 @@
 
 ## @font-face
 
- The `@font-face` at-rule expects as you would expect, simply followed by a block of properties:
+ The `@font-face` at-rule expects as you would expect. Simply add a block of properties after it, like so:
  
  
      @font-face
@@ -12,7 +12,7 @@
      .ingeo
        font-family Geo
 
-yielding:
+Yielding:
 
 
       @font-face {

data/vendor/docs/functions.md

@@ -1,21 +1,21 @@
 
 ## Functions
 
- Stylus features powerful in-language function definition. Function definition appears identical to mixins, however functions may return a value.
+ Stylus features powerful in-language function definitions. Function definitions appear identical to mixins; however, functions may return a value.
 
 ### Return Values
 
- Let's try a trivial example, creating a function that adds two numbers.
+ Let's try a trivial example: creating a function that adds two numbers.
 
     add(a, b)
       a + b
 
- We may then utilize this function in conditions, as property values, etc.
+ We can then use this function in conditions, in property values, etc.
  
      body 
        padding add(10px, 5)
 
- Rendering
+ Rendering:
      
      body {
        padding: 15px;
@@ -23,7 +23,9 @@
 
 ### Argument Defaults
 
- Optional arguments may default to a given expression. With Stylus we may even default arguments to leading arguments! For example:
+ Optional arguments may default to a given expression. With Stylus we may even default arguments to earlier arguments! 
+ 
+ For example:
  
  
      add(a, b = a)
@@ -35,14 +37,14 @@
      add(10)
      // => 20
 
-note that since argument defaults are assignments, we can also utilize function calls for defaults:
+**Note:** Since argument defaults are assignments, we can also use function calls for defaults:
 
      add(a, b = unit(a, px))
        a + b
 
 ### Function Bodies
 
- We can take our simple `add()` function further, by casting all units passed as `px` via the `unit()` built-in. Re-assigning each argument and providing a unit type string (or identifier), which disregards unit conversion.
+ 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.
  
      add(a, b = a)
        a = unit(a, px)
@@ -54,14 +56,16 @@ note that since argument defaults are assignments, we can also utilize function
 
 ### Multiple Return Values
 
- Stylus functions can return several values, just as you can assign several values to a variable. For example the following is a valid assignment:
+ Stylus functions can return several values—just as you can assign several values to a variable. 
+ 
+ For example, the following is a valid assignment:
  
        sizes = 15px 10px
      
        sizes[0]
        // => 15px 
 
-Similarly we may return several values:
+Similarly, we may return several values:
 
        sizes()
          15px 10px
@@ -69,12 +73,12 @@ Similarly we may return several values:
        sizes()[0]
        // => 15px
 
-One slight exception is when return values are identifiers, for example the following looks like a property assignment to Stylus since no operators are present.
+One slight exception is when return values are identifiers. For example, the following looks like a property assignment to Stylus (since no operators are present):
 
      swap(a, b)
        b a
 
-To disambiguate we may either wrap in parens, or utilize the `return` keyword.
+To disambiguate, we can either wrap with parentheses, or use the `return` keyword:
 
       swap(a, b)
         (b a)
@@ -84,7 +88,7 @@ To disambiguate we may either wrap in parens, or utilize the `return` keyword.
 
 ### Conditionals
 
- Let's say we want to create a function named `stringish()` to see if the value given can be transformed to a string. We check if `val` is a string, or an ident which is string-like. Because undefined identifiers yield themselves as the value, we may compare them to them-selves as shown below, where `yes` and `no` are used in place of `true` and `false`.
+ Let's say we want to create a function named `stringish()` to determine whether the argument can be transformed to a string. We check if `val` is a string, or an ident (which is string-like). Because undefined identifiers yield themselves as the value, we may compare them to themselves as shown below (where `yes` and `no` are used in place of `true` and `false`):
  
  
      stringish(val)
@@ -93,7 +97,7 @@ To disambiguate we may either wrap in parens, or utilize the `return` keyword.
        else
          no
 
-usage:
+Usage:
 
      stringish('yay') == yes
      // => true
@@ -104,11 +108,10 @@ usage:
      stringish(0) == no
      // => true
 
-__note__: `yes` and `no` are not boolean literals, they are simply undefined identifiers in this case.
+__note__: `yes` and `no` are not boolean literals. They are simply undefined identifiers in this case.
 
 Another example:
 
-
     compare(a, b)
       if a > b
         higher
@@ -117,7 +120,7 @@ Another example:
       else
         equal
 
-usage:
+Usage:
 
     compare(5, 2)
     // => higher
@@ -130,7 +133,7 @@ usage:
 
 ### Aliasing
 
-  To alias a function we can simply assign a function's name to a new identifier. For example our previous `add()` function could be exposed as `plus()` as well, simply by:
+  To alias a function, simply assign a function's name to a new identifier. For example, our `add()` function could be aliased as `plus()`, like so:
   
       plus = add
       
@@ -139,7 +142,7 @@ usage:
 
 ### Variable Functions
 
-  In the same way that we can "alias" a function, we can pass a function as well, here our `invoke()` function accepts a function, so we can pass it `add()` or `sub()`.
+  In the same way that we can "alias" a function, we can pass a function as well. Here, our `invoke()` function accepts a function, so we can pass it `add()` or `sub()`.
 
     invoke(a, b, fn)
       fn(a, b)
@@ -151,7 +154,7 @@ usage:
       padding invoke(5, 10, add)
       padding invoke(5, 10, sub)
 
-yielding:
+Yielding:
 
     body {
       padding: 15;
@@ -160,7 +163,9 @@ yielding:
 
 ### arguments
 
- The `arguments` local is available to all function bodies, and contains all the arguments passed. For example:
+ The `arguments` local is available to all function bodies, and contains all the arguments passed. 
+ 
+ For example:
  
      sum()
        n = 0
@@ -172,13 +177,13 @@ yielding:
 
 ### Hash Example
 
- Below we define the `get(hash, key)` function, which will return the
- value of `key`, or `null`. We iterate each `pair` in `hash`, returning the pair's second node when the first (the `key`) matches. 
+ Below we define the `get(hash, key)` function, which returns the
+ value of `key` (or `null`). We iterate each `pair` in `hash`, returning the pair's second node when the first (the `key`) matches. 
 
       get(hash, key)
         return pair[1] if pair[0] == key for pair in hash
 
-As you can see below, in-language functions paired with robust stylus expressions can provide great flexibility. 
+As demonstrated below, in-language functions—paired with robust Stylus expressions—can provide great flexibility:
       
       hash = (one 1) (two 2) (three 3)
       

data/vendor/docs/functions.url.md

@@ -1,12 +1,12 @@
 ## Data URI Image Inlining
 
-Stylus is bundled with an optional function named `url()`, which replaces the literal `url()` calls, and conditionally inlines them using base64 [Data URIs](http://en.wikipedia.org/wiki/Data_URI_scheme).
+Stylus is bundled with an optional function named `url()`, which replaces the literal `url()` calls (and conditionally inlines them using base64 [Data URIs](http://en.wikipedia.org/wiki/Data_URI_scheme)).
 
 ### Example
 
-The function itself is available via `require('stylus').url`, and accepts an options object, returning a function that Stylus calls internally when it sees `url()`.
+The function itself is available via `require('stylus').url`. It accepts an `options` object, returning a function that Stylus calls internally when it sees `url()`.
 
-The `.define(name, callback)` method assigned a JavaScript function that can be called from stylus source. In this case we have our images in `./css/images` then we can ignore the `paths` option, since image lookups are performed relative to the file being rendered (by default), we may alter this with the option.
+The `.define(name, callback)` method assigned a JavaScript function that can be called from Stylus source. In this case, since our images are in `./css/images`,  we can ignore the `paths` option (by default image lookups are performed relative to the file being rendered).  But if desired, this behavior can be altered:
 
       stylus(str)
         .set('filename', __dirname + '/css/test.styl')
@@ -15,7 +15,9 @@ The `.define(name, callback)` method assigned a JavaScript function that can be
     
         });
 
-For example if our images live in `./public/images` and we wish to use `url(images/tobi.png)`, we can pass `paths` with our public directory, which will become part of the lookup process. Like-wise if we wanted `url(tobi.png)` instead, we would pass `paths: [__dirname + '/public/images']`.
+For example, imagine our images live in `./public/images`.  We want to use `url(images/tobi.png)`.  We could pass `paths` our public directory, so that it becomes part of the lookup process. 
+
+Likewise, if instead we wanted `url(tobi.png)`, we could pass `paths: [__dirname + '/public/images']`.
 
       stylus(str)
         .set('filename', __dirname + '/css/test.styl')