From 5cb96e19d83b9ff620259cb3c2aae028f36c11ac Mon Sep 17 00:00:00 2001
From: Andy Meneely <andy.meneely@gmail.com>
Date: Tue, 13 Jan 2015 23:27:37 -0500
Subject: [PATCH] Revising layout docs

---
 README.md | 39 +++++++++++++++++++++------------------
 1 file changed, 21 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index a52eb33..40272e0 100644
--- a/README.md
+++ b/README.md
@@ -183,30 +183,19 @@ Layouts also allow merging, extending, and combining layouts. The sample demonst
 
 {include:file:samples/layouts.rb}
 
-### Merge Keys and `extends`
+### Special key: `extends`
 
-Since Layouts are in Yaml, we have the full power of that data format. One particular feature you should look into are ["merge keys"](http://www.yaml.org/YAML_for_ruby.html#merge_key). With merge keys, you can define base styles in one entry, then include those keys elsewhere. For example:
+Squib provides a way of reusing layouts with the special `extends` key. When defining an `extends` key, we can merge in another key and modify data coming in if we want to. This allows us to do things like set an inner object that changes its location based on its parent.
 
 ```yaml
-icon: &icon
-  width: 50
-  height: 50
-icon_left
-  <<: *icon
-  x: 100
-# The layout for icon_left will have the width/height from icon!
-```
-
-Also!! Squib provides a more feature-rich way of merging: the `extends` key in layouts. When defining an extends key, we can merge in another key and modify data coming in if we want to. This allows us to do things like set an inner object that changes its location based on its parent.
-
-```yaml
-yin:
+attack:
   x: 100
   y: 100
   radius: 100
-yang:
-  extends: yin
+defend:
+  extends: attack
   x: += 50
+  #defend now is {:x => 150, :y => 100}
 ```
 
 Furthermore, if you want to extend multiple parents, it looks like this:
@@ -214,7 +203,7 @@ Furthermore, if you want to extend multiple parents, it looks like this:
 ```yaml
 socrates:
   x: 100
-aristotle:
+plato:
   y: 200
 aristotle:
   extends:
@@ -223,6 +212,20 @@ aristotle:
   x: += 50
 ```
 
+Note that extends keys are similar to Yaml's ["merge keys"](http://www.yaml.org/YAML_for_ruby.html#merge_key). With merge keys, you can define base styles in one entry, then include those keys elsewhere. For example:
+
+```yaml
+icon: &icon
+  width: 50
+  height: 50
+icon_left
+  <<: *icon
+  x: 100
+# The layout for icon_left will have the width/height from icon!
+```
+
+If you use both `extends` and Yaml merge keys, the Yaml merge keys are processed first, then extends. For clarity, however, you're probably just better off using `extends` instead.
+
 ### Multiple layout files
 
 Squib also supports the combination of multiple layout files. As shown in the above example, if you provide an `Array` of files then Squib will merge them sequentially. Colliding keys will be completely re-defined by the later file. Extends is processed after _each file_. YAML merge keys are NOT supported across multiple files - use extends instead. Here's a demonstrative example: