starting documenting xywh_shorthands

docs/index.rst

@@ -15,6 +15,7 @@ Contents:
    layouts
    data
    units
+   shorthands
    colors
    text_feature
    bleed

docs/shorthands.rst

@@ -0,0 +1,29 @@
+XYWH Shorthands
+===============
+
+For the arguments ``x``, ``y``, ``width``, and ``height``, a few convenient shorthands are available.
+
+* ``middle`` for ``x`` and ``width`` refer to the deck's width / 2
+* ``middle`` for ``y`` and ``height`` refer to the deck's height / 2
+* ``deck`` refers to the deck's width for ``x`` and ``width``
+* ``deck`` refers to the deck's height for ``y`` and ``height``
+* You can offset from the middle by using +, -, and /, e.g. ``middle + 1in``
+* You can offset from the width or height using, e.g. ``width - 1in`` or ``height - 2mm``
+* Works with the ``cell`` unit as well, e.g. `middle + 1 cell`. See :doc:`units`.
+
+These are all passed as strings. So you will need to quote them in Ruby, or just plain in your layout YAML.
+
+Note that the following are NOT supported:
+
+* The `+=` operator when using `extends` in a layout file
+
+Samples
+-------
+
+_shorthands.rb
+^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/units/_shorthands.rb
+  :language: ruby
+  :linenos:
+

docs/units.rst

@@ -3,6 +3,27 @@ Unit Conversion
 
 By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. We provide some conversion methods, including looking for strings that end in "in", "cm", or "mm" and computing based on the current DPI. The dpi is set on `Squib::Deck.new` (not `config.yml`).
 
+Cells
+-----
+
+A "cell" is a custom unit in Squib that, by default, refers to ``37.5`` pixels. In a 300 DPI situation (i.e. the default), that refers to a 1/8 inch or 3.175mm. This tends to be a standard unit of measure in a lot of templates. By specifying your units in cells, you can increase your rapid prototyping without having to multiply 37.5.
+
+The ``cell_px`` measure is configurable. See :doc:`config`.
+
+To use the cell unit, you need to give Squib a string ending in `cell`, `cells`, or just `c`. For example:
+
+* ``2 cells``
+* ``1cell``
+* ``0.5c``
+
+See more examples below.
+
+Samples
+-------
+
+_units.rb
+^^^^^^^^^
+
 Here are some examples, which `lives here <https://github.com/andymeneely/squib/tree/master/samples/units.rb>`_
 
 .. literalinclude:: ../samples/units/_units.rb
@@ -12,3 +33,14 @@ Here are some examples, which `lives here <https://github.com/andymeneely/squib/
 .. raw:: html
 
   <img src="units/units_00_expected.png" class="figure">
+
+_cells.rb
+^^^^^^^^^
+
+.. literalinclude:: ../samples/units/_cells.rb
+  :language: ruby
+  :linenos:
+
+.. raw:: html
+
+  <img src="units/cells_00_expected.png" class="figure">