Expanding the Working With Text section

[skip ci]

README.md

@@ -192,21 +192,36 @@ All files opened for reading or writing (e.g. for `png` and `xlsx`) are opened r
 If you find that you `cd` a lot while working on the command line, your `_output` folder might get generated in multiple places. An easy way to fix this is to use a `Rakefile`, [see below](#Rakefile)
 
 ## Working with Text
-The `text` method is a particularly powerful method with a ton of options. Be sure to check the [API docs](docs/Squib/Deck#text-instance_method) on an option-by-option discussion, but here are the highlights.
+The `text` method is a particularly powerful method with a ton of options. Be sure to check the [API docs](/squib/doc/Squib/Deck#text-instance_method) on an option-by-option discussion, but here are the highlights.
 
-**Fonts**. The font is specified in a given Pango "font string", which can involve a ton of options embedded there in the string. In addition to the typical bold and italic variations, you can also specify all-caps, the specific boldness weight (e.g. 900), or go with oblique. These options are only available if the underlying font supports them, however. Here's are some example Pango font strings:
+###Fonts.
+
+To set the font, your `text` method call will look something like this:
+
+```ruby
+text str: "Hello", font: 'MyFont Bold 32'
+```
+
+The `'MyFont Bold 32'` is specified as a "Pango font string", which can involve [a lot of options](http://ruby-gnome2.osdn.jp/hiki.cgi?Pango%3A%3AFontDescription#Pango%3A%3AFontDescription.new) including backup font families, size, all-caps, stretch, oblique, italic, and degree of boldness. (These options are only available if the underlying font supports them, however.) Here's are some `text` calls with different Pango font strings:
 
 ```
-Sans 18
+text str: "Hello", font: 'Sans 18'
-Arial,Verdana weight=900 style=oblique 36
+text str: "Hello", font: 'Arial,Verdana weight=900 style=oblique 36'
-Times New Roman,Sans 25
+text str: "Hello", font: 'Times New Roman,Sans 25'
 ```
 
-Note: When the font has a space it, you'll need to put a backup to get Pango's parsing to work.
+Note: When the font has a space in the name (e.g. Times New Roman), you'll need to put a backup to get Pango's parsing to work.
 
 It's also important to note that most of the font rendering is done by a combination of your installed fonts, your OS, and your graphics card. Thus, different systems will render text slightly differently.
 
-Furthermore, options like `font_size` allow you to override the font string. This means that you can set a blanket font for the whole deck, then adjust sizes from there. This is useful with layouts and `extends` too.
+Fonts can also be set globally using the `set` method. For example:
+
+```
+set font: 'Arial 26'
+text str: 'blah' # in Arial 26
+```
+
+Furthermore, Squib's `text` method has options such as `font_size` that allow you to override the font string. This means that you can set a blanket font for the whole deck, then adjust sizes from there. This is useful with layouts and `extends` too.
 
 ### Width and Height
 

samples/text_options.rb

@@ -50,14 +50,15 @@ Squib::Deck.new(width: 825, height: 1125, cards: 3) do
 
   # Text hints are guides for showing you how your text boxes are laid out exactly
   hint text: :cyan
-  text str: 'Text hints are also globally togglable!',
+  set font: 'Serif 20' # Impacts all future text calls (unless they specify differently)
-        x: 65, y: 625,
+  text str: 'Text hints & fonts are globally togglable!', x: 65, y: 625
-        font: 'Arial 22'
+  set font: :default # back to Squib-wide default
   hint text: :off
   text str: 'See? No hint here.',
         x: 565, y: 625,
         font: 'Arial 22'
 
+  # Text can be rotated, in radians, about the upper-left corner of the text box.
   text str: 'Rotated',
         x: 565, y: 675, angle: 0.2,
         font: 'Arial 18', hint: :red

spec/data/samples/text_options.rb.txt

@@ -544,7 +544,7 @@ cairo: translate([65, 625])
 cairo: rotate([0])
 cairo: move_to([0, 0])
 pango: font_description=([MockDouble])
-pango: text=(["Text hints are also globally togglable!"])
+pango: text=(["Text hints & fonts are globally togglable!"])
 pango: wrap=([#<Pango::Layout::WrapMode word-char>])
 pango: ellipsize=([#<Pango::Layout::EllipsizeMode end>])
 pango: alignment=([#<Pango::Layout::Alignment left>])
@@ -564,7 +564,7 @@ cairo: translate([65, 625])
 cairo: rotate([0])
 cairo: move_to([0, 0])
 pango: font_description=([MockDouble])
-pango: text=(["Text hints are also globally togglable!"])
+pango: text=(["Text hints & fonts are globally togglable!"])
 pango: wrap=([#<Pango::Layout::WrapMode word-char>])
 pango: ellipsize=([#<Pango::Layout::EllipsizeMode end>])
 pango: alignment=([#<Pango::Layout::Alignment left>])
@@ -584,7 +584,7 @@ cairo: translate([65, 625])
 cairo: rotate([0])
 cairo: move_to([0, 0])
 pango: font_description=([MockDouble])
-pango: text=(["Text hints are also globally togglable!"])
+pango: text=(["Text hints & fonts are globally togglable!"])
 pango: wrap=([#<Pango::Layout::WrapMode word-char>])
 pango: ellipsize=([#<Pango::Layout::EllipsizeMode end>])
 pango: alignment=([#<Pango::Layout::Alignment left>])