squib 0.9.0 → 0.10.0

data/docs/guides/getting-started/part_2_iconography.rst

@@ -0,0 +1,152 @@
+The Squib Way pt 2: Iconography
+===================================
+
+.. warning::
+
+  This chapter is still being written
+
+In the previous guide, we walked you through the basics of going from ideas in your head to a very simple set of cards ready for playtesting at the table. In this guide we take the next step: creating a visual language.
+
+Art: Graphic Design vs. Illustration
+------------------------------------
+
+A common piece of advice in the prototyping world is "Don't worry about artwork, just focus on the game and do the artwork later". That's good advice, but a bit over-simplified. What folks usually mean by "artwork" is really "illustration", like the oil painting of a wizard sitting in the middle of the card or the intricate border around the edges.
+
+But games are more than just artwork with text - they're a system of rules that need to be efficiently conveyed to the players. They're a *visual language*. When players are new to your game, the layout of the cards need to facilitate learning. When players are competing in their 30th game, though, they need the cards to maximize usability by reducing their memory load, moving gameplay along efficiently, and provide an overall aesthetic that conveys the game theme. That's what graphic design is all about, and requires a game designer's attention much more than commissioning an illustration.
+
+Developing the visual language on your cards is not a trivial task. It's one that takes a lot of iteration, feedback, testing, improvement, failure, small successes, and reverse-engineering. It's something you should consider in your prototype early on. It's also a series of decisions that don't necessarily require artistic ability - just an intentional effort applied to usability.
+
+Icons and the their placement are, perhaps, the most efficient and powerful tools in your toolbelt for conveying your game's world. In the prototyping process, you don't need to be worried about using icons that are your *final* icons, but you should put some thought into what the visuals will look like because you'll be iterating on that in the design process.
+
+Iconography in Popular Games
+----------------------------
+
+When you get a chance, I highly recommend studying the iconography of some popular games. What works for you? What didn't? What kinds of choices did the designers make that works *for their game*? Here are a few that come my mind:
+
+Race for the Galaxy
+^^^^^^^^^^^^^^^^^^^
+
+The majority of the cards in RFTG have no description text on them, and yet the game contains hundreds of unique cards. RFTG has a vast, rich visual iconography that conveys a all of the bonuses and trade-offs of a card efficiently to the user. As a drawback, though, the visual language can be intimidating to new players - every little symbol and icon means a new thing, and sometimes you just need to memorize that "this card does that", until you realize that the icons show that.
+
+But once you know the structure of the game and what various bonuses mean, you can understand new cards very easily. Icons are combined in creative ways to show new bonuses. Text is used only when a bonus is much more complicated than what can be expressed with icons. Icons are primarily arranged along left side of the card so you can hold them in your hand and compare bonuses across cards quickly. All of these design decisions match the gameplay nicely because the game consists of a lot of scrolling through cards in your hand and evaluating which ones you want to play.
+
+Go check out images of Race for the Galaxy `on BoardGameGeek.com <https://boardgamegeek.com/boardgame/28143/race-galaxy>`_.
+
+Dominion
+^^^^^^^^
+
+Unlike RFTG, Dominion has a much simpler iconography. Most of the bonuses are conveyed in a paragraph of text in the description, with a few classifications conveyed by color or format. The text has icons embedded in it to tie in the concept of Gold, Curses, or Victory Points.
+
+But Dominion's gameplay is much different: instead of going through tons of different cards, you're only playing with 10 piles of cards in front of you. So each game really just requires you to remember what 10 cards mean. Once you purchase a card and it goes into your deck, you don't need to evaluate its worth quickly as in RFTG because you already bought it. Having most of the game's bonuses in prose means that new bonuses are extremely flexible in their expression. As a result, Dominion's bonuses and iconography is much more about text and identifying known cards than about evaluating new ones.
+
+Go check out images of Dominion `on BoardGameGeek.com <https://boardgamegeek.com/boardgame/36218/dominion>`_
+
+How Squib Supports Iconography
+------------------------------
+
+Squib is good for supporting any kind of layout you can think of, but it's also good for supporting multiple ways of translating your data into icons on cards. Here are some ways that Squib provides support for your ever-evolving iconography:
+
+  * :doc:`/dsl/svg` method, and all of its features like scaling, ID-specific rendering, direct XML manipulation, and all that the SVG file format has to offer
+  * :doc:`/dsl/png` method, and all of its features like blending operators, alpha transparency, and masking
+  * Layout files allow multiple icons for one data column (see :doc:`/layouts`)
+  * Layout files also have the ``extends`` feature that allows icons to inherit details from each other
+  * The ``range`` option on :doc:`/dsl/text`, :doc:`/dsl/svg`, and :doc:`/dsl/png` allows you to specify text and icons for any subset of your files
+  * The :doc:`/dsl/text` method allows for embedded icons.
+  * Ruby provides neat ways of aggregating data with ``inject``, ``map``, and ``zip`` that supports iconography
+
+Back to the Example: Drones vs. Humans
+--------------------------------------
+
+Ok, let's go back to our running example, project ``arctic-lemming`` from Part 1. We created cards for playtesting, but we never put down the faction for each card. That's a good candidate for an icon.
+
+Let's get some stock icons for this exercise. For this example, I went to http://game-icons.net. I set my foreground color to black, and background to white. I then  downloaded "auto-repair.svg" and "backup.svg". I'm choosing not to rename the files so that I can find them again on the website if I need to. (If you want to know how to do this process DIRECTLY from Ruby, and not going to the website, check out my *other* Ruby gem called `game_icons <https://github.com/andymeneely/game_icons>`_ - it's tailor-made for Squib!)
+
+When we were brainstorming our game, we placed one category of icons in a single column ("faction"). Presumably, one would want the faction icon to be in the same place on every card, but a different icon depending on the card's faction. There are a couple of ways of accomplishing this in Squib. First, here some less-than-clean ways of doing it::
+
+  svg range: 0, file: 'auto_repair.svg' # hard-coded range number? not flexible
+  svg range: 1, file: 'auto_repair.svg' # hard-coded range number? not flexible
+  svg range: 2, file: 'backup.svg'      # hard-coded range number? not flexible
+  svg range: 3, file: 'backup.svg'      # hard-coded range number? not flexible
+  # This gets very hard to maintain over time
+  svg file: ['auto_repair.svg', 'auto_repair.svg', 'backup.svg', 'backup.svg']
+  # This is slightly easier to maintain, but is more verbose and still hardcoded
+  svg range: 0..1, file 'auto_repair.svg'
+  svg range: 2..3, file 'backup.svg'
+
+That's too much hardcoding of data into our Ruby code. That's what layouts are for. Now, we've already specified a layout file in our prior example. Fortunately, Squib supports *multiple* layout files, which get combined into a single set of layout styles. So let's do that: we create our own layout file that defines what a ``human`` is and what a ``drone`` is. Then just tell ``svg`` to use the layout data. The data column is simply an array of factions, the icon call is just connecting the factions to their styles with::
+
+  svg layout: data['faction']
+
+So, putting it all together, our code looks like this.
+
+.. raw:: html
+
+  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
+  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
+  <code data-gist-id="d2bb2eb028b27cf1dace"
+        data-gist-file="_part2_01_factions.rb"
+        data-gist-highlight-line="13"
+        ></code>
+  <code data-gist-id="d2bb2eb028b27cf1dace"
+        data-gist-file="_part2_01_factions.yml"></code>
+  <code data-gist-id="d2bb2eb028b27cf1dace" data-gist-file="data.csv"></code>
+  <code data-gist-id="d2bb2eb028b27cf1dace"
+        data-gist-file="_part2_01_factions_00.png"></code>
+
+**BUT!** There's a very important software design principle we're violating here. It's called DRY: Don't Repeat Yourself. In making the above layout file, I hit copy and paste. What happens later when we change our mind and want to move the faction icon!?!? We have to change TWO numbers. Blech.
+
+There's a better way: ``extends``
+
+The layout files in Squib also support a special keyword, ``extends``, that allows us to "copy" (or "inherit") another style onto our own, and then we can override as we see fit. Thus, the following layout is a bit more DRY:
+
+.. raw:: html
+
+  <code data-gist-id="d2bb2eb028b27cf1dace"
+      data-gist-file="_part2_02_factions.yml"></code>
+
+Much better!
+
+Now if we want to add a new faction, we don't have to copy-pasta any code! We just extend from faction and call in our new SVG file. Suppose we add a new faction that needs a bigger icon - we can define our own ``width`` and ``height`` beneath the ``extends`` that will override the parent values of 75.
+
+Looks great! Now let's get these cards out to the playtesting table!
+
+At this point, we've got a very scalable design for our future iterations. Let's take side-trip and discuss why this design works.
+
+Why Ruby+YAML+Spreadsheets Works
+--------------------------------
+
+In software design, a "good" design is one where the problem is broken down into a set of easier duties that each make sense on their own, where the interaction between duties is easy, and where to place new responsbilities is obvious.
+
+In Squib, we're using automation to assist the prototyping process. This means that we're going to have a bunch of decisions and responsibilities, such as:
+
+  * *Game data decisions*. How many of this card should be in the deck? What should this card be called? What should the cost of this card be?
+  * *Style Decisions*. Where should this icon be? How big should the font be? What color should we use?
+  * *Logic Decisions*. Can we build this to a PDF, too? How do we save this in black-and-white? Can we include a time stamp on each card? Can we just save one card this time so we can test quickly?
+
+With the Ruby+YAML+Spreadsheets design, we've separated these three kinds of questions into three areas:
+
+  * Game data is in a spreadsheet
+  * Styles are in YAML layout files
+  * Code is in Ruby
+
+When you work with this design, you'll probably find yourself spending a lot of time working on one of these files for a long time. That means this design is working.
+
+For example, you might be adjusting the exact location of an image by editing your layout file and re-running your code over and over again to make sure you get the exact x-y coordinates right. That's fine. You're not making game data decisions in that moment, so you shouldn't be presented with any of that stuff. This eases the cognitive complexity of what you're doing.
+
+The best way to preserve this design is to try to keep the Ruby code clean. As wonderful as Ruby is, it's the hardest of the three to edit. It is code, after all. So don't clutter it up with game data or style data - let it be the glue between your styles and your game.
+
+Ok, let's get back to this prototype.
+
+Icons for Some, But Not All, Cards
+----------------------------------
+
+.. note::
+
+  to be written
+
+One Column per Icon
+-------------------
+
+.. note::
+
+  to be written

data/docs/guides/getting-started/part_3_workflows.rst

@@ -0,0 +1,4 @@
+The Squib Way pt 3: Workflows
+===============================
+
+To be written.

data/docs/guides/git.rst

@@ -0,0 +1,13 @@
+Squib + Git
+===========
+
+.. note::
+
+  To be written
+
+
+Ideas:
+  * Workflow
+  * Tracking binary data (show json method)
+  * Snippet about "what's changed"
+  * Releases via tags and versioning

data/docs/guides/hello_world.rst

@@ -0,0 +1,6 @@
+Hello, World!
+=============
+
+.. note::
+
+  Under construction

data/docs/help.rst

@@ -0,0 +1,157 @@
+Get Help and Give Help
+======================
+
+.. raw:: html
+
+  On BoardGameGeek.com? Show your Squib pride by <a href="https://boardgamegeek.com/microbadge/37841">getting the microbadge <img src="https://cdn.rawgit.com/andymeneely/squib/gh-pages/images/microbadge.png"></a> and <a href="https://boardgamegeek.com/guilds/2601">joining our guild!</a>
+
+Get Help
+--------
+
+Squib is powerful and customizable, which means it can get complicated pretty quickly. Don't settle for being stuck.
+
+Here's an ordered list of how to find help:
+
+1. Go through this documentation
+2. Go through `the wiki <https://github.com/andymeneely/squib/wiki>`_
+3. Go through `the samples <https://github.com/andymeneely/squib/tree/master/samples>`_
+4. Google it - people have asked lots of questions about Squib already in many forums.
+5. Ask on Stackoverflow `using the tags "ruby" and "squib" <http://stackoverflow.com/questions/ask?tags=ruby squib>`_. You will get answers quickly from Ruby programmers it's and a great way for us to archive questions for future Squibbers.
+6. Our `thread on BoardGameGeek <http://boardgamegeek.com/thread/1293453>`_ or `our guild <https://boardgamegeek.com/guild/2601>`_ is quite active and informal (if a bit unstructured).
+
+If you email me directly I'll probably ask you to post your question publicly so we can document answers for future Googling Squibbers.
+
+Please use GitHub issues for bugs and feature requests.
+
+Help by Troubleshooting
+-----------------------
+
+One of the best ways you can help the Squib community is to be active on the above forums. Help people out. Answer questions. Share your code. Most of those forums have a "subscribe" feature.
+
+You can also watch the project on GitHub, which means you get notified when new bugs and features are entered. Try reproducing code on your own machine to confirm a bug. Help write minimal test cases. Suggest workarounds.
+
+Help by Beta Testing
+--------------------
+
+.. Testers needed!! If you want to test new features as I develop them, or make sure I didn't break your code, you can always point your Gemfile to the repository and follow what I'm doing there. Your Gemfile specification looks like this::
+..
+..   gem 'squib', git: 'git://github.com/andymeneely/squib', branch: 'dev'
+..
+.. * The ``dev`` branch is where I am working on features in-process. I have not done much regression testing at this point, but would love testing feedback nonetheless.
+.. * The ``master`` branch is where I consider features and bug that are done and tested, but not released yet.
+
+Squib is a small operation. And programming is hard. So we need testers! In particular, I could use help from people to do the following:
+
+  * Test out new features as I write them
+  * Watch for regression bugs by running their current projects on new Squib code, checking for compatibility issues.
+
+Want to join the mailing list and get notifications? https://groups.google.com/forum/#!forum/squib-testers
+
+There's no time commitment expectation associated with signing up. Any help you can give is appreciated!
+
+Beta: Using Pre-Builds
+^^^^^^^^^^^^^^^^^^^^^^
+
+The preferred way of doing beta testing is by to get Squib directly from my GitHub repository. Bundler makes this easy.
+
+If you are just starting out you'll need to install bundler::
+
+  $ gem install bundler
+
+Then, in the root of your Squib project, create a file called `Gemfile` (capitalization counts). Put this in it::
+
+  source 'https://rubygems.org'
+
+  gem 'squib', git: 'git://github.com/andymeneely/squib', branch: 'master'
+
+Then run::
+
+  $ bundle install
+
+Your output will look something like this::
+
+
+  Fetching git://github.com/andymeneely/squib
+  Fetching gem metadata from https://rubygems.org/.........
+  Fetching version metadata from https://rubygems.org/...
+  Fetching dependency metadata from https://rubygems.org/..
+  Resolving dependencies...
+  Using pkg-config 1.1.6
+  Using cairo 1.14.3
+  Using glib2 3.0.7
+  Using gdk_pixbuf2 3.0.7
+  Using mercenary 0.3.5
+  Using mini_portile2 2.0.0
+  Using nokogiri 1.6.7
+  Using pango 3.0.7
+  Using rubyzip 1.1.7
+  Using roo 2.3.0
+  Using rsvg2 3.0.7
+  Using ruby-progressbar 1.7.5
+  Using squib 0.9.0b from git://github.com/andymeneely/squib (at master)
+  Using bundler 1.10.6
+  Bundle complete! 1 Gemfile dependency, 14 gems now installed.
+  Use `bundle show [gemname]` to see where a bundled gem is installed.
+
+To double-check that you're using the test version of Squib, puts this in your code::
+
+  require 'squib'
+  puts Squib::VERSION # prints the Squib version to the console when you run this code
+
+  # Rest of your Squib code...
+
+When you run your code, say ``deck.rb``, you'll need to put ``bundle exec`` in front of it. Otherwise Ruby will just go with full releases (e.g. ``0.8`` instead of pre-releases, e.g. ``0.9a``). That would look like this::
+
+  $ bundle exec ruby deck.rb
+
+If you need to know the exact commit of the build, you can see that commit hash in the generated ``Gemfile.lock``. That ``revision`` field will tell you the *exact* version you're using, which can be helpful for debugging. That will look something like this::
+
+  remote: git://github.com/andymeneely/squib
+    revision: 440a8628ed83b24987b9f6af66ad9a6e6032e781
+    branch: master
+
+To update to the latest from the repository, run ``bundle up``.
+
+To remove Squib versions, run ``gem cleanup squib``. This will also remove old Squib releases.
+
+Beta: About versions
+^^^^^^^^^^^^^^^^^^^^
+
+  * When the version ends in "a" (e.g. ``v0.9a``), then the build is "alpha". I could be putting in new code all the time without bumping the version. I try to keep things as stable after every commit, but this is considered the least stable code. (Testing still appreciated here, though.) This is also tracked by my ``dev`` branch.
+  * For versions ending in "b" (e.g. ``v0.9b``), then the build is in "beta". Features are frozen until release, and we're just looking for bug fixes.  This tends to be tracked by the ``master`` branch in my repository.
+  * I follow the `Semantic Versioning <http://semver.org>`_ as best I can
+
+Beta: About Bundler+RubyGems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Gemfile is a configuration file (technically it's a Ruby DSL) for a widely-used library in the Ruby community called Bundler. Bundler is a way of managing multiple RubyGems at once, and specifying exactly what you want.
+
+Bundler is different from RubyGems. Technically, you CAN use RubyGems without Bundler: just ``gem install`` what you need and your ``require`` statements will work. BUT Bundler helps you specify versions with the Gemfile, and where to get your gems. If you're switching between different versions of gems (like with being tester!), then Bundler is the way to go. The Bundler website is here: http://bundler.io/.
+
+By convention, your ``Gemfile`` should be in the root directory of your project. If you did ``squib new``, there will be one created by default. Normally, a Squib project Gemfile will look `like this <https://github.com/andymeneely/squib/blob/master/lib/squib/project_template/Gemfile>`_. That configuration just pulls the Squib from RubyGems.
+
+But, as a tester, you'll want to have Bundler install Squib from my repository. That would look like this: https://github.com/andymeneely/project-spider-monkey/blob/master/Gemfile. (Just line 4 - ignore the other stuff.) I tend to work with two main branches - dev and master. Master is more stable, dev is more bleeding edge. Problems in the master branch will be a surprise to me, problems in the dev branch probably won't surprise me.
+
+After changing your Gemfile, you'll need to run ``bundle install``. That will generate a ``Gemfile.lock`` file - that's Bundler's way of saying exactly what it's planning on using. You don't modify the Gemfile.lock, but you can look at it to see what version of Squib it's locked onto.
+
+
+
+Help by Fixing Bugs
+-------------------
+
+A great way to make yourself known in the community is to go over `our backlog <https://github.com/andymeneely/squib/issues>`_ and work on fixing bugs. Even suggestions on troubleshooting what's going on (e.g. trying it out on different OS versions) can be a big help.
+
+Help by Contributing Code
+-------------------------
+
+Our biggest needs are in community support. But, if you happen to have some code to contribute,  follow this process:
+
+1. Fork the git repository ( https://github.com/[my-github-username]/squib/fork )
+2. Create your feature branch (``git checkout -b my-new-feature``)
+3. Commit your changes (``git commit -am 'Add some feature'``)
+4. Push to the branch (``git push origin my-new-feature``)
+5. Create a new Pull Request
+
+Be sure to write tests and samples for new features.
+
+Be sure to run the unit tests and packaging with just ``rake``. Also, you can check that the samples render properly with ``rake sanity``.

data/docs/index.rst

@@ -0,0 +1,35 @@
+Squib Documentation
+===================
+
+Welcome to the official Squib documentation!
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   install
+   learning
+   parameters
+   arrays
+   layouts
+   data
+   units
+   colors
+   text_feature
+   bleed
+   config
+   backends
+   build_groups
+   help
+   dsl/index.rst
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+
+
+.. meta::
+   :google-site-verification: BWelviUOeiImUuyxt54P6YinZcSuxHm8_aQidm9ju-U

data/docs/install.rst

@@ -0,0 +1,66 @@
+Install & Update
+================
+
+Squib is a Ruby gem, and installation is handled like most gems.
+
+Pre-requisites
+--------------
+
+  * `Ruby 2.1+ <https://www.ruby-lang.org>`_
+
+Squib works with both x86 and x86_64 versions of Ruby.
+
+Typical Install
+---------------
+
+Regardless of your OS, installation is::
+
+  $ gem install squib
+
+If you're using `Bundler <http://bundler.io>`_, add this line to your application's Gemfile::
+
+  gem 'squib'
+
+And then execute::
+
+  $ bundle install
+
+Squib has some native dependencies, such as `Cairo <https://github.com/rcairo/rcairo>`_, `Pango <http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3ALayout>`_, and `Nokogiri <http://nokogiri.org/>`_, which will compile upon installation - this is normal.
+
+Updating Squib
+--------------
+
+At this time we consider Squib to be still in initial development, so we are not supporting older versions. Please upgrade your Squib as often as possible.
+
+To keep track of when new Squib releases come out, you can watch the `BoardGameGeek thread <https://boardgamegeek.com/thread/1293453>`_ or follow the RSS feed for Squib on its `RubyGems page <https://rubygems.org/gems/squib>`_.
+
+In RubyGems, the command looks like this::
+
+  $ gem up squib
+
+As a quirk of Ruby/RubyGems, sometimes older versions of gems get caught in caches. You can see which versions of Squib are installed and clean them up, use ``gem list`` and ``gem cleanup``::
+
+  $ gem list squib
+
+  *** LOCAL GEMS ***
+
+  squib (0.9.0, 0.8.0)
+
+  $ gem cleanup squib
+  Cleaning up installed gems...
+  Attempting to uninstall squib-0.8.0
+  Successfully uninstalled squib-0.8.0
+  Clean Up Complete
+
+This will remove all prior versions of Squib.
+
+As a sanity check, you can see what version of Squib you're using by referencing the ``Squib::VERSION`` constant::
+
+  require 'squib'
+  puts Squib::VERSION
+
+
+OS-Specific Quirks
+------------------
+
+See the `wiki <http://github.com/andymeneely/squib/wiki>`_ for idiosyncracies about specific operating systems, dependency clashes, and other installation issues. If you've run into issues and solved them, please post your solutions for others!

data/docs/layouts.rst

@@ -0,0 +1,235 @@
+Layouts are Squib's Best Feature
+================================
+
+Working with tons of options to a method can be tiresome. Ideally everything in a game prototype should be data-driven, easily changed, and your Ruby code should readable without being littered with `magic numbers <http://stackoverflow.com/questions/47882/what-is-a-magic-number-and-why-is-it-bad>`_.
+
+For this, most Squib methods have a ``layout`` option. Layouts are a way of setting default values for any parameter given to the method. They let you group things logically, manipulate options, and use built-in stylings.
+
+Think of layouts and DSL calls like CSS and HTML: you can always specify style in your logic (e.g. directly in an HTML tag), but a cleaner approach is to group your styles together in a separate sheet and work on them separately.
+
+To use a layout, set the ``layout:`` option on ``Deck.new`` to point to a YAML file. Any command that allows a ``layout`` option can be set with a Ruby symbol or string, and the command will then load the specified options. The individual command can also override these options.
+
+For example, instead of this::
+
+  # deck.rb
+  Squib::Deck.new do
+    rect x: 75, y: 75, width: 675, height: 975
+  end
+
+You can put your logic in the layout file and reference them::
+
+  # custom-layout.yml
+  bleed:
+    x: 75
+    y: 75
+    width: 975
+    height: 675
+
+Then your script looks like this::
+
+  # deck.rb
+  Squib::Deck.new(layout: 'custom-layout.yml') do
+    rect layout: 'bleed'
+  end
+
+The goal is to make your Ruby code separate the data decisions from logic. For the above example, you are separating the decision to draw rectangle around the "bleed" area, and then your YAML file is defining specifically what "bleed" actually means. (Who is going to remember that ``x: 75`` means "bleed area"??) This process of separating logic from data makes your code more readable, changeable, and maintainable.
+
+.. warning::
+
+   YAML is very finnicky about not allowing tab characters. Use two spaces for indentation instead. If you get a ``Psych`` syntax error, this is likely the culprit. Indendation is also strongly enforced in Yaml too. See the `Yaml docs <http://www.yaml.org/YAML_for_ruby.html>`_ for more info.
+
+Order of Precedence for Options
+-------------------------------
+
+Layouts will override Squib's system defaults, but are overriden by anything specified in the command itself. Thus, the order of precedence looks like this:
+
+  1. Use what the DSL method specified, e.g. ``rect x: 25``
+  2. If anything was not yet specified, use what was given in a layout (if a layout was specified in the command and the file was given to the Deck). e.g. ``rect layout: :bleed``
+  3. If still anything was not yet specified, use what was given in Squib's defaults as defined in the :doc:`dsl/index`.
+
+For example, back to our example::
+
+  # custom-layout.yml
+  bleed:
+    x: 0.25in
+    y: 0.25in
+    width: 2.5in
+    height: 3.5in
+
+(Note that this example makes use of :doc:`/units`)
+
+Combined with this script:
+
+.. code-block:: ruby
+
+  # deck.rb
+  Squib::Deck.new(layout: 'custom-layout.yml') do
+    rect layout: 'bleed', x: 50
+  end
+
+The options that go into ``rect`` will be:
+
+  * ``x`` will be 50 because it's specified in the DSL method and overrides the layout
+  * ``y``, ``width``, and ``height`` were specified in the layout file, so their values are used
+  * The rect's ``stroke_color`` (and others options like it) was never specified anywhere, so the default for ``rect`` is used - as discussed in :doc:`parameters`.
+
+.. note::
+
+ Defaults are not global for the name of the option - they are specific to the method itself. For example, the default ``fill_color`` for ``rect`` is ``'#0000'`` but for ``showcase`` it's ``:white``.
+
+.. note::
+
+  Layouts work with *all* options (for DSL methods that support layouts), so you can use options like ``file`` or ``font`` or whatever is needed.
+
+.. warning::
+
+  If you provide an option in the Yaml file that is not supported by the DSL method, the DSL method will simply ignore it. Same behavior as described in :doc:`parameters`.
+
+
+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::
+
+  # If we change attack, we move defend too!
+  attack:
+    x: 100
+    y: 100
+  defend:
+    extends: attack
+    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:
+    y: 100
+    font: Arial 36
+  attack:
+    extends: top_icon
+    x: 25
+  defend:
+    extends: top_icon
+    x: 50
+  health:
+    extends: top_icon
+    x: 75
+  # ...and so on
+
+.. note::
+
+   Those fluent in Yaml may notice that ``extends`` key is similar to Yaml's `merge keys <http://www.yaml.org/YAML_for_ruby.html#merge_key>`_. Technically, you can use these together - but I just recommend sticking with ``extends`` since it does what merge keys do *and more*. If you do choose to use both ``extends`` and Yaml merge keys, the Yaml merge keys are processed first (upon Yaml parsing), then ``extends`` (after parsing).
+
+Yes, ``extends`` is Multi-Generational
+--------------------------------------
+
+As you might expect, ``extends`` can be composed multiple times::
+
+  socrates:
+    x: 100
+  plato:
+    extends: socrates
+    x: += 10    # evaluates to 150
+  aristotle:
+    extends: plato
+    x: += 20    # evaluates to 150
+
+Yes, ``extends`` has Multiple Inheritance
+-----------------------------------------
+
+If you want to extend multiple parents, it looks like this::
+
+  socrates:
+    x: 100
+  plato:
+    y: 200
+  aristotle:
+    extends:
+      - socrates
+      - plato
+    x: += 50    # evaluates to 150
+
+If multiple keys override the same keys in a parent, the later ("younger") child in the ``extends`` list takes precedent. Like this::
+
+  socrates:
+    x: 100
+  plato:
+    x: 200
+  aristotle:
+    extends:
+      - plato    # note the order here
+      - socrates
+    x: += 50     # evaluates to 150 from socrates
+
+
+Multiple Layout Files get Merged
+--------------------------------
+
+Squib also supports the combination of multiple layout files. If you provide an ``Array`` of files then Squib will merge them sequentially. Colliding keys will be completely re-defined by the later file. The ``extends`` key is processed after *each file*, but can be used across files. Here's an example::
+
+  # load order: a.yml, b.yml
+
+  ##############
+  # file a.yml #
+  ##############
+  grandparent:
+    x: 100
+  parent_a:
+    extends: grandparent
+    x: += 10   # evaluates to 110
+  parent_b:
+    extends: grandparent
+    x: += 20   # evaluates to 120
+
+  ##############
+  # file b.yml #
+  ##############
+  child_a:
+    extends: parent_a  # i.e. extends a layout in a separate file
+    x: += 3    # evaluates to 113 (i.e 110 + 3)
+  parent_b:    # redefined
+    extends: grandparent
+    x: += 30   # evaluates to 130 (i.e. 100 + 30)
+  child_b:
+    extends: parent_b
+    x: += 3    # evaluates to 133 (i.e. 130 + 3)
+
+This can be helpful for:
+  * Creating a base layout for structure, and one for full color for easier color/black-and-white switching
+  * Sharing base layouts with other designers
+
+Squib Comes with Built-In Layouts
+---------------------------------
+
+Why mess with x-y coordinates when you're first prototyping your game? Just use a built-in layout to get your game to the table as quickly as possible.
+
+If your layout file is not found in the current directory, Squib will search for its own set of layout files.  The latest the development version of these can be found `on GitHub <https://github.com/andymeneely/squib/tree/master/lib/squib/layouts>`_.
+
+Contributions in this area are particularly welcome!!
+
+See Layouts in Action
+---------------------
+
+`This sample <https://github.com/andymeneely/squib/tree/master/samples/>`_ demonstrates many different ways of using and combining layouts.
+
+`This sample <https://github.com/andymeneely/squib/tree/master/samples/>`_ demonstrates built-in layouts based on popular games (e.g. ``fantasy.yml`` and ``economy.yml``)