Some doc fixes for the exposing of vars to views in 0.3

docs/0.3-gumbo/migration.md

@@ -19,11 +19,11 @@ Data importing
   - `@get '/:foo': -> @render @params.foo`
   - `@get '/:foo': (c) -> @render c.params.foo`
   - `@set databag: 'param'; @get '/:foo': (d) -> @render d.foo`
-  - `@set databag: 'context'; @get '/:foo': (c) -> c.render @foo`
+  - `@set databag: 'this'; @get '/:foo': (c) -> c.render @foo`
 
 Data exporting
 
 - Change `get '/': -> @foo = 'bar'; render 'index'` to one of these alternatives:
   - `@get '/': -> @render index: {foo: 'bar'}`
   - `@set databag: 'param'; @get '/': (d) -> d.foo = 'bar'; @render 'index'`
-  - `@set databag: 'context'; @get '/': (c) -> @foo = 'bar'; c.render 'index'`
+  - `@set databag: 'this'; @get '/': (c) -> @foo = 'bar'; c.render 'index'`

docs/0.3-gumbo/reference.md

@@ -141,12 +141,57 @@ Or:
 
     @set 'view engine': 'jade'
 
-All variables at `@`/`params` (request params + those you created) are automatically made available to templates as `params.foo` (in CoffeeKup, `@params.foo`).
+> 0.3 upgrade note: `@`/`params` variables are no longer automatically exported
+> to your views.
 
-In addition, if you're using the *zappa view adapter* (as is the case by default, with CoffeeKup), they're also made available at the template's "root namespace" (`foo` or CoffeeKup's `@foo`).
+The issue here is that `@` is now the namespace for all the internal zappa stuff, so it can't just be exposed to your views without unexpected consequences.  So you need to explicitly choose what to expose.
+
+You have three options to expose your variables to your views.
+
+#### 1. List them explicitly in your render call:
+
+    @enable 'default layout'
+
+    @get '/:foo': ->
+      @render 'foo', foo: @params.foo, bar: 'bar'
+
+    @view foo: ->
+      p @foo
+      p @bar
+
+#### 2. Use the handler's argument for zappa's `this` (allowing your own data to use `@`):
+
+    @enable 'default layout'
+    @set databag: 'this'
+
+    @get '/:foo': (z) ->
+      @bar = 'bar'
+      z.render 'foo'
+
+    @view foo: ->
+      p @foo
+      p @bar
+
+
+#### 3. Use the handler's argument for the params and your data:
+
+    @enable 'default layout'
+    @set databag: 'param'
+
+    @get '/:foo': (c) ->
+      c.bar = 'bar'
+      @render 'foo'
+
+    @view foo: ->
+      p @foo
+      p @bar
+
+As you can see both options 2 and 3 allow the request params to be auto-assigned to `@` vars in CoffeeKup and plain vars in other template engines.
 
 Since in express templating data is usually mixed up with framework locals and template options, the adapter will only put variables in the template root if there isn't a variable there with the same name already, *and* the name is not blacklisted.
 
+#### TODO: fix the require so the below works
+
 To use this feature with other templating engines:
 
     blacklist = 'scope self locals filename debug compiler compileDebug inline'.split ' '
@@ -517,4 +562,4 @@ When `param`:
 
     @get '/:foo': (c) ->
       c.foo += '!'
-      @render 'index'
+      @render 'index'