POLYMER
=======

DESCRIPTION
-----------

Polymer is a tool for creating sprite images which combine many smaller
sources into a single larger image. Spriting allows you to reduce the
number of HTTP requests required to load a web page, and as such can
result in reduced load times.

Polymer also creates the necessary CSS to position the sprite within an
HTML element so that only the desired source appears. Those writing
their website or application in Ruby can make use of Polymer's Sass
builder which creates a Sass mixin, further simplifying the use of your
sprites.

In order to reduce the amount of data transferred to clients loading
your pages, Polymer optimises the sprites it generates using PNGOUT,
OptiPNG, and PNGCrush.

INSTALLATION
------------

The recommended way to install Polymer is with Rubygems:

    $ [sudo] gem install polymer

Polymer currently uses RMagick/ImageMagick in order to read and write
images. Eventually, I want to offer support for ChunkyPNG also, which
should substantially ease installation.

Most Linux and BSD distributions include ImageMagick in their packaging
system; while Mac OS X users can install it with [Homebrew][homebrew]:

    $ brew install ghostscript
    $ brew install imagemagick

If you wish to install Polymer from source:

    $ git clone http://github.com/antw/polymer.git && cd polymer
    $ gem build polymer.gemspec
    $ [sudo] gem install --local polymer-VERSION.gem

(Where "VERSION" is the current version of Polymer). If you do not have
Git installed, the latest versions can be [downloaded instead][download].

GETTING STARTED
---------------

In order for Polymer to create sprites from your source images, it must
first create a "project" -- this is a `.polymer` file which is placed
into your project's root directory. This file comes with some sensible
defaults which should suffice for most cases. This file is generated by
running `polymer init`.

1. Run `polymer init` to create a ".polymer" file in the current
   directory. Prior to running the command, you may want to glance at
   the [polymer-init(1)][polymer-init] manpage to get an overview of the
   supported options. `polymer init` also places some example source
   images into your project.

2. Run `polymer bond`: this is the main task which converts the source
   images into the final sprites. If you have PNGOUT, OptiPNG, or
   PNGCrush installed, Polymer will also optimise the generates sprites
   to reduce them to the smallest possible filesize.

3. Run `polymer bond` again. Nothing happens! Polymer maintains a cache
   of your sprite images so that it only generates them again if any of
   the sources have changed; pretty handy since optimising large sprites
   can take some time. See [polymer(5)][polymer-5] to learn how to
   disable this.

USING YOUR SPRITES
------------------

### Updating Sprites

Having created some example sprites in "Getting Started", you can now
add completely new sprites by adding new directories alongside "one" and
"two", alter existing sprites by adding, changing, or removing source
images, then once again running `polymer bond`.

If this isn't sufficiently flexible, see [polymer(5)][polymer-5] to
learn how to define your own sprites in the ".polymer" file.

### Sass / SCSS Stylesheets

Out-of-the-box, Polymer generates a Sass stylesheet containing a mixin.
This stylesheet is created at the path given to "config.sass" in
".polymer".

This mixin can be used thusly: (in this case, "main" is the name of the
sprite, "home" and "products" are the names of source images
sans-extension).

    Assuming directory structure:

    public/images/sprites/
      messages/
        new.png
        reply.png

    Your Sass stylesheet like:

      @import polymer.sass

      .buttons
        a#compose, a#reply
          +polymer("messages/new")
        a#reply
          +polymer-pos("messages/reply")

Which creates:

    .buttons a#compose, .buttons a#reply {
      background: url(/path/to/sprite.ext) 0 0 no-repeat; }

    .buttons a#products {
      background-position: 0 -40px; }

With the latest versions of the Haml library, you may use SCSS instead:

      @import("polymer.sass")

      .buttons {
        a#compose, a#reply {
          @include polymer("messages/new") }
        a#reply {
          @include polymer-pos("messages/reply") } }

You can disable creation of the Sass mixin file by setting `config.sass
false` in the ".polymer" file.

Sass users can make use of data URIs; the sprite contents will, instead
of being written to disk, be inlined into your CSS files. This reduces
the number of HTTP requests required to load your pages, but results in
slightly more data having to be transferred to your users. See
[polymer(5)][polymer-5] for instructions.


### CSS Stylesheets

... are not yet implemented. Hold tight; these should be around before
Polymer hits v1.0.

PNG OPTIMISATION
----------------

... needs to be written up.

CONTRIBUTING
------------

A Bundler Gemfile is provided to simplify installing Polymer's
dependencies. Running `bundle install` will install everything needed to
contribute. Bundler is not used in the Polymer library itself.

* Fork the project, taking care not to get any in your eyes.

* Make your feature addition or bug fix.

* Add tests for it. This is especially important not only because it
  helps ensure that I don't unintentionally break it in a future
  version, but also since it appeases Epidity, God of Potatoes, who has
  been known to shower rancid cucumbers upon those who fail to test.

* Commit, but please do not mess with the Rakefile or history. If you
  want to have your own version, _that is fine_, but bump the version in
  a commit by itself so that I can ignore it when I pull.

* Send me a pull request. Bonus points for topic branches (although
  "everything is made up, and the points don't matter...").

Polymer specs are run against:

* Ruby (MRI) 1.8.7 p302,
* Ruby (YARV) 1.9.1 p378,
* Ruby (YARV) 1.9.2 p0.

GETTING HELP
------------

Polymer comes complete with some manpages which document the various
commands:

* **[polymer(1)][polymer-1]** -- `polymer help`
* **[polymer(5)][polymer-5]** -- `polymer help .polymer`
* **[polymer-init(1)][polymer-init]** -- `polymer help init`
* **[polymer-bond(1)][polymer-bond]** -- `polymer help bond`
* **[polymer-optimise(1)][polymer-optimise]** -- `polymer help optimise`
* **[polymer-position(1)][polymer-position]** -- `polymer help position`

If you've encountered a bug, or Polymer isn't behaving as you expect,
please [file an issue report][issues].

DETAILS
-------

**Source**
:  [http://github.com/antw/polymer][polymer]

**Author**
:  Anthony Williams

**Copyright**
:  2009-2010

**License**
:  BSD License

Polymer © 2009-2010 by [Anthony Williams](mailto:hi@antw.me).
Polymer is free software, released under the BSD license. Please see the
LICENSE file for more information.

The sample sources in lib/polymer/templates/sources are courtesy of
[Yusuke Kamiyamane][yusuke], whose extraordinary generosity in releasing
three-thousand royalty-free icons cannot be stated enough.

[montage]:   http://github.com/antw/montage
[polymer]:   http://github.com/antw/polymer
[homebrew]:  http://mxcl.github.com/homebrew/
[pngout]:    http://advsys.net/ken/utils.htm
[download]:  http://github.com/antw/polymer/downloads
[kin]:       http://github.com/antw/kin
[semver]:    http://semver.org/
[yard]:      http://yardoc.org/
[issues]:    http://github.com/antw/polymer/issues
[yusuke]:    http://p.yusukekamiyamane.com

[polymer-1]:        http://antw.github.com/polymer/polymer.1.html
[polymer-5]:        http://antw.github.com/polymer/polymer.5.html
[polymer-init]:     http://antw.github.com/polymer/polymer-init.1.html
[polymer-bond]:     http://antw.github.com/polymer/polymer-bond.1.html
[polymer-optimise]: http://antw.github.com/polymer/polymer-optimise.1.html
[polymer-position]: http://antw.github.com/polymer/polymer-position.1.html