docs: rip out gigantic README, finish port to rtfd
This commit is contained in:
Andy Meneely
+11
-1
@@ -98,10 +98,20 @@ smart_quotes
|
||||
|
||||
|
||||
Options are available as methods
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
--------------------------------
|
||||
|
||||
For debugging/sanity purposes, if you want to make sure your configuration options are parsed correctly, the above options are also available as methods within ``Squib::Deck``, for example::
|
||||
|
||||
Squib::Deck.new do
|
||||
puts backend # prints 'memory' by default
|
||||
end
|
||||
|
||||
|
||||
Making Squib Verbose
|
||||
--------------------
|
||||
|
||||
By default, Squib's logger is set to ``WARN``, but more fine-grained logging is embedded in the code. To set the logger, just put this at the top of your script::
|
||||
|
||||
Squib::logger.level = Logger::INFO
|
||||
|
||||
If you REALLY want to see tons of output, you can also set DEBUG, but that's not intended for general consumption.
|
||||
|
||||
+114
-3
@@ -24,12 +24,110 @@ 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.
|
||||
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
|
||||
--------------------
|
||||
|
||||
TODO: Write this up
|
||||
.. 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
|
||||
|
||||
The preferred way of doing getting Squib directly from my GitHub repository. Bundler makes this easy.
|
||||
|
||||
Beta: Using Pre-Builds
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
@@ -37,4 +135,17 @@ 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.
|
||||
|
||||
If you have code to contribute, see our
|
||||
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``.
|
||||
|
||||
@@ -17,6 +17,7 @@ Contents:
|
||||
data
|
||||
units
|
||||
colors
|
||||
text_feature
|
||||
bleed
|
||||
config
|
||||
backends
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
The Might text Method
|
||||
=====================
|
||||
|
||||
|
||||
The :doc:`/dsl/text` method is a particularly powerful method with a ton of options. Be sure to check the option-by-option details in the DSL reference, but here are the highlights.
|
||||
|
||||
Fonts
|
||||
-----
|
||||
|
||||
To set the font, your ``text`` method call will look something like this::
|
||||
|
||||
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 :doc:`/dsl/text` calls with different Pango font strings::
|
||||
|
||||
text str: "Hello", font: 'Sans 18'
|
||||
text str: "Hello", font: 'Arial,Verdana weight=900 style=oblique 36'
|
||||
text str: "Hello", font: 'Times New Roman,Sans 25'
|
||||
|
||||
|
||||
Finally, 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 (see :doc:`/layouts`).
|
||||
|
||||
.. 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. In some operating systems, you'll want to simply end with a comma::
|
||||
|
||||
text str: "Hello", font: 'Times New Roman, 25'
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
Width and Height
|
||||
------------------
|
||||
|
||||
By default, Pango text boxes will scale the text box to whatever you need, hence the ``:native`` default. However, for most of the other customizations to work (e.g. center-aligned) you'll need to specify the width. If both the width and the height are specified and the text overflows, then the ``ellipsize`` option is consulted to figure out what to do with the overflow. Also, the ``valign`` will only work if ``height`` is also set to something other than ``:native``.
|
||||
|
||||
Hints
|
||||
-----
|
||||
|
||||
Laying out text by typing in numbers can be confusing. What Squib calls "hints" is merely a rectangle around the text box. Hints can be turned on globally in the config file, using the :doc:`/dsl/hint` method, or in an individual text method. These are there merely for prototyping and are not intended for production. Additionally, these are not to be conflated with "rendering hints" that Pango and Cairo mention in their documentation.
|
||||
|
||||
Extents
|
||||
------
|
||||
|
||||
Sometimes you want size things based on the size of your rendered text. For example, drawing a rectangle around card's title such that the rectangle perfectly fits. Squib returns the final rendered size of the text so you can work with it afterward. It's an array of hashes that correspond to each card. The output looks like this::
|
||||
|
||||
Squib::Deck.new(cards: 2) do
|
||||
extents = text(str: ['Hello', 'World!'])
|
||||
puts extents
|
||||
end
|
||||
|
||||
will output::
|
||||
|
||||
[{:width=>109, :height=>55}, {:width=>142, :height=>55}] # Hello was 109 pixels wide, World 142 pixels
|
||||
|
||||
Embedding Images
|
||||
------------------
|
||||
|
||||
Squib can embed icons into the flow of text. To do this, you need to define text keys for Squib to look for, and then the corresponding files. The object given to the block is a ``TextEmbed``, which supports PNG and SVG. Here's a minimal example::
|
||||
|
||||
text(str: 'Gain 1 :health:') do |embed|
|
||||
embed.svg key: ':health:', file: 'heart.svg'
|
||||
end
|
||||
|
||||
Markup
|
||||
------
|
||||
|
||||
See :ref:`Markup <text-markup>` in :doc:`/dsl/text`.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
* Examples of all of the above are crammed into the ``text_options.rb`` sample `found here <https://github.com/andymeneely/squib/tree/master/samples/text_options.rb>`_
|
||||
* The ``embed_text.rb`` sample has more examples of embedding text, which can be `found here <https://github.com/andymeneely/squib/tree/master/samples/embed_text.rb>`_
|
||||
* The ``config_text_markup.rb`` sample demonstrates how quoting can be configured, `found here <https://github.com/andymeneely/squib/tree/master/samples/config_text_markup.rb>`_
|
||||
|
||||
And this one too:
|
||||
|
||||
.. 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="52d7b8e332194946bc69" data-gist-file="_text.rb"></code>
|
||||
<code data-gist-id="52d7b8e332194946bc69" data-gist-file="_text_00_expected.png"></code>
|
||||
Reference in New Issue
Block a user