README.md in motion-kit-0.12.0 vs README.md in motion-kit-0.13.0

@@ -7,11 +7,11 @@
 
 1. Crossplatform compatibility: iOS, OSX, and planned support for Android
 2. Simple, easy to learn DSL
 3. Crossframework compatibility:
    - [UIKit][readmore-uikit]
-   - [ApplicationKit][readmore-applicationkit]
+   - [AppKit][readmore-appkit]
    - [AutoLayout][readmore-autolayout]
    - [Frame geometry][readmore-frames]
    - [CoreAnimation][readmore-coreanimation]
    - [NSMenu/NSMenuItem][readmore-nsmenu]
 4. Easily extendable to support custom, mini-DSLs
@@ -27,12 +27,13 @@
 [RMQ]: https://github.com/infinitered/rmq
 [Teacup]: https://github.com/rubymotion/teacup
 [SweetKit]: https://github.com/rubymotion/sweet-kit
 
 [READMORE]: https://github.com/rubymotion/motion-kit/blob/master/READMORE.md
+[readmore-migrating]:      https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#migrating-from-teacup
 [readmore-uikit]:          https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#uikit
-[readmore-applicationkit]: https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#applicationkit
+[readmore-appkit]: https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#appkit
 [readmore-coreanimation]:  https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#coreanimation
 [readmore-frames]:         https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#frames
 [readmore-autolayout]:     https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#autolayout
 [readmore-nsmenu]:         https://github.com/rubymotion/motion-kit/blob/master/READMORE.md#nsmenu-os-x
 
@@ -40,11 +41,15 @@
 ## What happened to Teacup??
 
 You can [read all about](#goodbye-teacup) why Colin decided that Teacup needed to
 be replaced with a new project, rather than upgraded or refactored.
 
+If you need to update your app to use MotionKit, see
+[READMORE.md][readmore-migrating] for an example of migrating stylesheets,
+styles, and constraints.
 
+
 ## Usage
 
 In your Gemfile
 
 ```ruby
@@ -186,11 +191,11 @@
       # we'll use 'sizeToFit' to calculate the height
       add UITextField, :username_input do
         frame [[10, 10], ['100% - 10', :auto]]
       end
       add UITextField, :password_input do
-        frame below(:username_input, margin: 8)
+        frame below(:username_input, down: 8)
       end
     end
   end
 end
 ```
@@ -239,14 +244,15 @@
 ```ruby
 # app/styles/login_styles.rb
 module LoginStyles
 
   def login_button_style
+    # this example uses SugarCube to create UIColor and CGColor objects.
     background_color '#51A8E7'.uicolor
     title 'Log In'
     # `layer` returns a CALayer, which in turn becomes the new context inside
-    # this block!
+    # this block
     layer do
       corner_radius 7.0
       shadow_color '#000000'.cgcolor
       shadow_opacity 0.9
       shadow_radius 2.0
@@ -340,12 +346,15 @@
 ### How do styles get applied?
 
 If you've used RMQ's Stylers, you'll recognize a very similar pattern here. In
 RMQ the 'style' methods are handed a 'Styler' instance, which wraps access to
 the view.  In MotionKit we make use of `method_missing` to call these methods
-indirectly.  That takes care of most methods related to styling, except those
-that take multiple arguments.  Those can get "helper" methods.
+indirectly.  That takes care of most methods related to styling, but you might
+want to write some "helper" methods so that your styling code is more concise.
+Some examples are included in the MotionKit core, but the [SweetKit][] gem has
+many more.  If you are writing helpers for UIKit or AppKit, please consider
+adding them to SweetKit, so we can all share in the productivity boost! :smiley:
 
 ```ruby
   def login_label_style
     text 'Press me'  # this gets delegated to UILabel#text
   end
@@ -354,10 +363,11 @@
   # title on a UIButton
   def login_button_style
     title 'Press me'
     # this gets delegated to UIButtonHelpers#title(title), which in turn calls
     # button.setTitle(title, forState: UIControlStateNormal)
+    # See uibutton_helpers.rb for implementation.
   end
 ```
 
 MotionKit offers shortcuts and mini-DSLs for frames, auto-layout, and
 miscellaneous helpers.  But if a method is not defined, it is sent to the view
@@ -382,12 +392,12 @@
 Introspection and method_missing add a little overhead to your code, but in our
 benchmarking it is insignificant and undetectable. Let us know if you find any
 performance issues.
 
 You can easily add your own helpers to MotionKit. They
-are all named consistenly, e.g. `MotionKit::UIViewHelpers`, e.g.
-`MotionKit::UILabelHelpers`.  You just need to specify the "target class" that
+should all be named consistenly, e.g. `MotionKit::UIViewHelpers`,
+`MotionKit::UILabelHelpers`, etc.  You just need to specify the "target class" that
 your helper class is meant to work with.  Each class can only have *one helper
 class*.
 
 ```ruby
 module MotionKit
@@ -923,9 +933,19 @@
 The OS X helpers are really nice, because it tries to hide most of the
 annoying subtletees of the NSCell/NSControl dichotomy.
 
     gem install sweet-kit
 
+
+# Gotchas
+
+### A Note on `add` and `remove`
+
+When you use the `add` method to add a subview, that view will be retained by
+the Layout *even if you remove it from the view hierarchy*.  If you want the
+Layout to forget all about the view, call `remove(view)` (which also calls
+`removeFromSuperview`) or `forget(element_id)` (which only removes it from the
+Layout) on the Layout.
 
 # Contributing
 
 We welcome your contributions! Please be sure to run the specs before you do,
 and consider adding support for both iOS and OS X.