From 29b8d31b9b4b67ad99a75cba5353085199e9a7c2 Mon Sep 17 00:00:00 2001
From: Andy Meneely <andy@se.rit.edu>
Date: Wed, 3 Feb 2016 17:05:07 -0500
Subject: [PATCH] docs: minor revisions to layouts and other

---
 .gitignore         |  2 +-
 docs/args/draw.rst |  2 +-
 docs/install.rst   |  6 ++++++
 docs/layouts.rst   | 39 +++++++++++++++++++++++++++++----------
 4 files changed, 37 insertions(+), 12 deletions(-)
 create mode 100644 docs/install.rst

diff --git a/.gitignore b/.gitignore
index ae6d2fd8..3d9ac6fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,7 +9,7 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
-docs/_build
+docs/_build*
 doc/
 lib/bundler/man
 pkg
diff --git a/docs/args/draw.rst b/docs/args/draw.rst
index c9549749..1813895c 100644
--- a/docs/args/draw.rst
+++ b/docs/args/draw.rst
@@ -7,7 +7,7 @@ fill_color
 stroke_color
   default: ``:black``
 
-  the color with which to stroke the outside of the rectangle. See :docs:`/colors`.
+  the color with which to stroke the outside of the rectangle. See :doc:`/colors`.
 
 
 stroke_width
diff --git a/docs/install.rst b/docs/install.rst
new file mode 100644
index 00000000..c4e5ab13
--- /dev/null
+++ b/docs/install.rst
@@ -0,0 +1,6 @@
+Installation
+------------
+
+Squib is a Ruby gem, and is managed like most Ruby gems.
+
+TODO: recover this from other writing
diff --git a/docs/layouts.rst b/docs/layouts.rst
index 87bac920..bd006b1f 100644
--- a/docs/layouts.rst
+++ b/docs/layouts.rst
@@ -51,12 +51,16 @@ For example, back to our example::
 
   # custom-layout.yml
   bleed:
-    x: 75
-    y: 75
-    width: 975
-    height: 675
+    x: 0.25in
+    y: 0.25in
+    width: 2.5in
+    height: 3.5in
+
+(Note that this example makes use of :doc:`/units`)
 
-And this script::
+Combined with this script:
+
+.. code-block:: ruby
 
   # deck.rb
   Squib::Deck.new(layout: 'custom-layout.yml') do
@@ -87,20 +91,35 @@ When Layouts Are Similar, Use ``extends``
 
 Using layouts are a great way of keeping your Ruby code clean and concise. But those layout Yaml files can get pretty long. If you have a bunch of icons along the top of a card, for example, you're specifying the same ``y`` option over and over again. This is annoyingly verbose, and what if you want to move all those icons downward at once?
 
-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 its data coming in if we want to. This allows us to do things like place text next to an icon and be able to move them with each other. Like this::
+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 its data coming in if we want to. This allows us to do things like place text next to an icon and be able to move them with each other. Like this::
 
   # If we change attack, we move defend too!
   attack:
     x: 100
     y: 100
-    radius: 100
   defend:
     extends: attack
-    x: += 50
+    x: 150
     #defend now is {:x => 150, :y => 100}
 
 Over time, using ``extends`` saves you a lot of space in your Yaml files while also giving more structure and readability to the file itself.
 
+You can also **modify** data as they get passed through extends::
+
+  # If we change attack, we move defend too!
+  attack:
+    x: 100
+  defend:
+    extends: attack
+    x: += 50
+    #defend now is {:x => 150, :y => 100}
+
+The following operators are supported within evaluating ``extends``
+  * ``+=`` will add the giuven number to the inherited number
+  * ``-=`` will subtract the given number from the inherited number
+
+Both operators also support :doc:`/units`
+
 From a design point of view, you can also extract out a base design and have your other layouts extend from them::
 
   top_icons:
@@ -144,9 +163,9 @@ If multiple keys override the same keys in a parent, the later ("younger") child
     x: 200
   aristotle:
     extends:
-      - plato
+      - plato    # note the order here
       - socrates
-    x: += 50   # evaluates to 250 from socrates
+    x: += 50     # evaluates to 150 from socrates
 
 
 Multiple Layout Files get Merged