squib 0.9.0 → 0.10.0

data/docs/dsl/disable_build.rst

@@ -0,0 +1,28 @@
+disable_build
+=============
+
+Disable the given build group for the rest of the build. Thus, code within the corresponding :doc:`/dsl/group` block will not be executed. See :doc:`/build_groups` for ways to use this effectively.
+
+
+Required Arguments
+------------------
+
+build_group_name
+  default: ``:all``
+  the name of the group to disable. Convention is to use a Ruby symbol.
+
+.. note::
+
+
+
+Examples
+--------
+
+Can be used to disable a group (even if it's enabled via command line)::
+
+  Squib::Deck.new do
+    disable_build :pnp
+    build :pnp do
+      save_pdf
+    end
+  end

data/docs/dsl/ellipse.rst

@@ -0,0 +1,17 @@
+ellipse
+-------
+
+Draw an ellipse at the given coordinates. An ellipse is an oval that is defined by a bounding rectangle. To draw a circle, see :doc:`circle`.
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+.. include:: /args/xy.rst
+.. include:: /args/wh.rst
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+^^^^^^^^

data/docs/dsl/enable_build.rst

@@ -0,0 +1,25 @@
+enable_build
+============
+
+Enable the given build group for the rest of the build. Thus, code within the corresponding :doc:`/dsl/group` block will be executed. See :doc:`/build_groups` for ways to use this effectively.
+
+
+Required Arguments
+------------------
+
+build_group_name
+  the name of the group to enable. Convention is to use a Ruby symbol.
+
+
+
+Examples
+--------
+
+Can be used to disable a group (even if it's enabled via command line)::
+
+  Squib::Deck.new do
+    disable_build :pnp
+    build :pnp do
+      save_pdf
+    end
+  end

data/docs/dsl/grid.rst

@@ -0,0 +1,31 @@
+grid
+----
+
+Draw an unlimited square grid of lines on the deck, starting with x,y and extending off the end of the deck.
+
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+.. include:: /args/xy.rst
+
+
+width
+  default: ``:deck`` (the width of the deck)
+
+  the spacing between vertical gridlines. Supports :doc:`/units`.
+
+
+height
+  default: ``:deck`` (the height of the deck)
+
+  the spacing between horizontal gridlines. Supports :doc:`/units`.
+
+
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+^^^^^^^^

data/docs/dsl/hand.rst

@@ -0,0 +1,40 @@
+hand
+====
+
+Renders a range of cards fanned out as if in a hand. Saves as PNG regardless of back end.
+
+Options
+-------
+
+radius
+  default: ``:auto``
+
+  The distance from the bottom of each card to the center of the fan. If set to ``:auto``, then it is computed as 30% of the card's height. Why 30%? Because it looks good that way. Reasons.
+
+angle_range
+  default: ``((Math::PI / -4.0)..(Math::PI / 2))``
+
+  The overall width of the fan, in radians. Angle of zero is a vertical card. Further negative angles widen the fan counter-clockwise and positive angles widen the fan clockwise.
+
+margin
+  default: ``75``
+
+  the margin around the entire image. Supports :doc:`/units`.
+
+fill_color
+  default: ``:white``
+
+  Backdrop color. See :doc:`/colors`.
+
+.. include:: /args/trim.rst
+
+file
+  default: ``'hand.png'``
+
+  The file to save relative to the current directory. Will overwrite without warning.
+
+.. include:: /args/output_dir.rst
+.. include:: /args/range.rst
+
+Examples
+--------

data/docs/dsl/hint.rst

@@ -0,0 +1,15 @@
+hint
+====
+
+Toggle text hints globally. A text hint is a 1-pixel line drawn around the extents of a text box. They are intended to be temporary guides.
+
+Options
+-------
+
+text
+  default: ``:off``
+
+  The color of the text hint. See :doc:`/colors` To turn off use ``:off`` or ``nil``.
+
+Examples
+--------

data/docs/dsl/inches.rst

@@ -0,0 +1,19 @@
+inches
+------
+
+Given inches, returns the number of pixels according to the deck's DPI.
+
+Parameters
+^^^^^^^^^^
+
+n
+  the number of inches
+
+
+Examples
+^^^^^^^^
+
+.. code-block:: ruby
+
+  inches(2.5)                # 750 (for default Deck::dpi of 300)
+  inches(2.5) + inches(0.5)  # 900 (for default Deck::dpi of 300)

data/docs/dsl/index.rst

@@ -0,0 +1,9 @@
+DSL Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /dsl/deck
+   /dsl/*

data/docs/dsl/line.rst

@@ -0,0 +1,52 @@
+line
+----
+
+Draw a line from x1,y1 to x2,y2.
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+x1
+  default: ``0``
+
+  the x-coordinate to place. Supports :doc:`/units/`
+
+
+y1
+  default: ``0``
+
+  the y-coordinate to place. Supports :doc:`/units/`
+
+
+x2
+  default: ``50``
+
+  the x-coordinate to place. Supports :doc:`/units/`
+
+
+y2
+  default: ``50``
+
+  the y-coordinate to place. Supports :doc:`/units/`
+
+
+x3
+  default: ``0``
+
+  the x-coordinate to place. Supports :doc:`/units/`
+
+
+y3
+  default: ``50``
+
+  the y-coordinate to place. Supports :doc:`/units/`
+
+
+
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+^^^^^^^^

data/docs/dsl/png.rst

@@ -0,0 +1,49 @@
+png
+===
+
+Renders PNG images.
+
+Options
+-------
+.. include:: /args/expansion.rst
+
+file
+  default: ``''`` (empty string)
+
+  file(s) to read in. As in :doc:`/arrays`, if this a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done for that card.
+
+.. include:: /args/xy.rst
+
+width
+  default: ``:native``
+
+  the pixel width that the image should scale to. Supports :doc:`/units`. When set to ``:native``, uses the DPI and units of the loaded SVG document. Using ``:deck`` will scale to the deck width. Using ``:scale`` will use the ``height`` to scale and keep native the aspect ratio. Scaling PNGs is not recommended for professional-looking cards, and up-scaling a PNG will throw a warning in the console (see :doc:`/config`).
+
+height
+  default: ``:native``
+
+  the pixel height that the image should scale to. Supports :doc:`/units`. When set to ``:native``, uses the DPI and units of the loaded SVG document. Using ``:deck`` will scale to the deck height. Using ``:scale`` will use the ``width`` to scale and keep native the aspect ratio. Scaling PNGs is not recommended for professional-looking cards, and up-scaling a PNG will throw a warning in the console (see :doc:`/config`).
+
+alpha
+  default: 1.0
+
+  the alpha-transparency percentage used to blend this image. Must be between ``0.0`` and ``1.0``
+
+blend
+  default: ``:none``
+
+  the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators.
+  The possibilties include :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
+
+mask
+  default: ``nil``
+
+  Accepts a color (see :doc:`/colors`). If specified, the image will be used as a mask for the given color/gradient. Transparent pixels are ignored, opaque pixels are the given color. Note: the origin for gradient coordinates is at the given x,y, not at 0,0 as it is most other places.
+
+.. include:: /args/transform.rst
+
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+--------

data/docs/dsl/polygon.rst

@@ -0,0 +1,28 @@
+polygon
+-------
+
+Draw an n-sided regular polygon, centered at x,y.
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+.. include:: /args/xy.rst
+
+radius
+  default: 0
+
+  the distance from the center of the star to the inner circle of its points. Supports :doc:`/units`.
+
+angle
+  default: 0
+
+  the angle at which to rotate the star
+
+
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+^^^^^^^^

data/docs/dsl/rect.rst

@@ -0,0 +1,18 @@
+rect
+----
+
+Draw a rounded rectangle
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+.. include:: /args/xy.rst
+.. include:: /args/wh.rst
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+
+Examples
+^^^^^^^^

data/docs/dsl/save.rst

@@ -0,0 +1,23 @@
+save
+====
+
+Saves the given range of cards to either PNG or PDF. Wrapper method for other save methods.
+
+Options
+-------
+
+This method delegates everything to :doc:`save_png` or :doc:`save_pdf` using the ``format`` option. All other options are passed along.
+
+format
+  default: ``[]`` (do nothing)
+
+  Use ``:png`` to save as a PNG, and ``:pdf`` to save as PDF. To save to both at once, use ``[:png, :pdf]``
+
+Examples
+--------
+
+::
+
+  save format: :png, prefix: 'front_' # same as: save_png prefix: 'front_'
+  save format: :pdf, prefix: 'cards_' # same as: save_pdf prefix: 'cards_'
+  save format: [:png, :pdf]           # same as: save_png; save_pdf

data/docs/dsl/save_pdf.rst

@@ -0,0 +1,48 @@
+save_pdf
+========
+
+Lays out the cards in range on a sheet and renders a PDF
+
+Options
+-------
+
+
+
+file
+  default: ``'output.pdf'``
+
+  the name of the PDF file to save. Will be overwritten without warning.
+
+dir
+  default: ``_output``
+
+  the directory to save to. Created if it doesn't exist.
+
+width
+  default: ``3300``
+
+  the height of the page in pixels. Default is 11in * 300dpi. Supports :doc:`/units`.
+
+height
+  default: ``2550``
+
+  the height of the page in pixels. Default is 8.5in * 300dpi. Supports :doc:`/units`.
+
+margin
+  default: ``75``
+
+  the margin around the outside of the page. Supports :doc:`/units`.
+
+gap
+  default: ``0``
+
+  the space in pixels between the cards. Supports :doc:`/units`.
+
+trim
+  default: ``0``
+
+  the space around the edge of each card to trim (e.g. to cut off the bleed margin for print-and-play). Supports :doc:`/units`.
+
+
+Examples
+--------

data/docs/dsl/save_png.rst

@@ -0,0 +1,46 @@
+save_png
+========
+
+Saves the given range of cards to a PNG
+
+Options
+-------
+
+
+range
+  default ``:all``
+
+  the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
+
+dir
+  default: ``'_output'``
+
+  the directory for the output to be sent to. Will be created if it doesn't exist.
+
+prefix
+  default ``'card_'``
+
+  the prefix of the file name to be printed.
+
+count_format
+  default: ``'%02d'``
+
+  the format string used for formatting the card count (e.g. padding zeros). Uses a Ruby format string (see the Ruby doc for ``Kernel::sprintf`` for specifics)
+
+rotate
+  default: ``false``
+
+  If ``true``, the saved cards will be rotated 90 degrees clockwise. Or, rotate by the number of radians. Intended to rendering landscape instead of portrait. Possible values: ``true``, ``false``, ``:clockwise``, ``:counterclockwise``
+
+trim
+  default: ``0``
+
+  the space around the edge of each card to trim (e.g. to cut off the bleed margin for print-and-play). Supports :doc:`/units`.
+
+trim_radius
+  default: ``0``
+
+  the rounded rectangle radius around the card to trim before saving.
+
+Examples
+--------