Spriting tutorial.

doc-src/content/CHANGELOG.markdown

@@ -14,8 +14,14 @@ The Documentation for the [latest stable release](http://compass-style.org/docs/
 
 The Documentation for the [latest preview release](http://beta.compass-style.org/)
 
+0.11.alpha.2 (12/05/2010)
+-------------------------
+
+* Merge with Lemonade. Compass now provides a full featured spriting solution.
+  See the [spriting tutorial](/help/tutorials/spriting/) for more information.
+
 0.11.alpha.1 (11/22/2010)
----------------------------
+-------------------------
 
 * Support for Sass 3.1 alpha version
 * CSS3 PIE module. [Docs](/reference/compass/css3/pie/).
@@ -30,8 +36,8 @@ The Documentation for the [latest preview release](http://beta.compass-style.org
   and `box-shadow` mixins.
 * The docs are [getting a make-over](http://beta.compass-style.org/) by Brandon :) 
 
-0.11.alpha.0   (11/15/2010)
+0.11.alpha.0 (11/15/2010)
----------------------------
+-------------------------
 
 Note: Compass does not currently support Sass 3.1 alphas.
 

doc-src/content/help/tutorials/spriting.markdown

@@ -5,4 +5,162 @@ crumb: Spriting
 classnames:
   - tutorial
 ---
-# Spriting with Compass
+# Spriting with Compass
+
+Spriting has never been easier with Compass. You place the sprite images to be in a folder,
+import them into your stylesheet, and then you can use the sprite in your selectors in one
+of several convenient ways.
+
+## Setup
+
+For this tutorial, let's imagine that in your project's image folder there are four icons:
+
+* `public/images/icon/new.png`
+* `public/images/icon/edit.png`
+* `public/images/icon/save.png`
+* `public/images/icon/delete.png`
+
+Each is an icon that is 32px square.
+
+## Basic Usage
+The simplest way to use these icon sprites is to let compass give you a class for each sprite:
+
+    @import "icon/*.png";
+    @include all-icon-sprites;
+
+And you'll get the following CSS output:
+
+    .icon-sprite,
+    .icon-delete,
+    .icon-edit,
+    .icon-new,
+    .icon-save   { background: url('/images/icon.png?1291584143') no-repeat; }
+    
+    .icon-delete { background-position: 0 0; }
+    .icon-edit   { background-position: 0 -32px; }
+    .icon-new    { background-position: 0 -64px; }
+    .icon-save   { background-position: 0 -96px; }
+
+You can now apply the `icon-XXX` classes to your markup as needed.
+
+Let's go over what happened there. The import statement told compass to [generate a
+stylesheet that is customized for your sprites](https://gist.github.com/729507). This
+stylesheet is [magic](#magic-imports), it is not written to disk, and it can be customized
+by setting configuration variables before you import it. See the section below on
+[Customization Options](#customization-options). The goal of this stylesheet is to provide a
+simple naming convention for your sprites so that you they are easy to remember and use. You
+should never have to care what the is name of the generated sprite map, nor where a sprite
+is located within it.
+
+## Selector Control
+
+If you want control over what selectors are generated, it is easy to do. In this example,
+this is done by using the magic `icon-sprite` mixin. Note that the mixin's name is dependent
+on the name of the folder in which you've placed your icons.
+
+    @import "icon/*.png";
+    
+    .actions {
+      .new    { @include icon-sprite(new);    }
+      .edit   { @include icon-sprite(edit);   }
+      .save   { @include icon-sprite(save);   }
+      .delete { @include icon-sprite(delete); }
+    }
+
+And your stylesheet will compile to:
+
+    .icon-sprite,
+    .actions .new,
+    .actions .edit,
+    .actions .save,
+    .actions .delete { background: url('/images/icon.png?1291584143') no-repeat; }
+    
+    .actions .new    { background-position: 0 -64px; }
+    .actions .edit   { background-position: 0 -32px; }
+    .actions .save   { background-position: 0 -96px; }
+    .actions .delete { background-position: 0 0;     }
+
+<a name="magic-imports"></a>
+## Magic Imports
+
+As noted above, compass will magically create sprite stylesheets for you. Some people like
+magic, some people are scared by it, and others are curious about how the magic works. If
+you would like to avoid the magic, you can use compass to generate an import for you. On the
+command line:
+
+    compass sprite "public/images/icon/*.png"
+
+This will create file using your project's preferred syntax, or you can specify the
+output filename using the `-f` option and the syntax will be inferred from the extension.
+If you do this, you'll need to remember to regenerate the import whenever you rename, add,
+or remove sprites.
+
+Using the magic imports is recommended for most situations. But there are times when you
+might want to avoid it. For instance, if your sprite map has more than about 20 to 30
+sprites, you may find that hand crafting the import will speed up compilation times. See
+the section on [performance considerations](#performance) for more details.
+
+<a name="customization-options"></a>
+## Customization Options
+
+### Options per Sprite Map
+
+When constructing the sprite map, the entire sprite map and it's associated stylesheet
+can be configured in the following ways. Each option is specified by setting a [configuration
+variable](/help/tutorials/configurable-variables/) before importing the sprite. The variables
+are named according to the name of the folder containing the sprites. In the examples below
+the sprites were contained within a folder called `icon`.
+
+* `$<map>-spacing` -- The amount of transparent space, in pixels, around each sprite.
+  Defaults to `0px`. E.g. `$icon-spacing: 20px`.
+* `$<map>-repeat` -- Wether or not each sprite should repeat along the x axis. Defaults
+  to `no-repeat`. E.g. `$icon-repeat: repeat-x`.
+* `$<map>-position` -- The position of the sprite in the sprite map along the x-axis. Can
+  be specified in pixels or percentage of the sprite map's width. `100%` would cause the
+  sprite to be on the right-hand side of the sprite map. Defaults to `0px`.
+  E.g. `$icon-position: 100%`.
+* `$<map>-sprite-dimensions` -- Whether or not the dimensions of the sprite should be
+  included in each sprite's CSS output. Can be `true` or `false`. Defaults to `false`.
+* `$<map>-sprite-base-class` -- The base class for these sprites. Defaults to `.<map>-sprite`.
+  E.g. `$icon-sprite-base-class: ".action-icon"`
+
+### Options per Sprite
+
+When constructing the sprite map, each sprite can be configured in the following ways:
+
+* `$<map>-<sprite>-spacing` -- The amount of transparent space, in pixels, around the sprite. Defaults
+  to the sprite map's spacing which defaults to `0px`. E.g. `$icon-new-spacing: 20px`.
+* `$<map>-<sprite>-repeat` -- Wether or not the sprite should repeat along the x axis. Defaults
+  to the sprite map's repeat which defaults to `no-repeat`. E.g. `$icon-new-repeat: repeat-x`.
+* `$<map>-<sprite>-position` -- The position of the sprite in the sprite map along the x-axis. Can
+  be specified in pixels or percentage of the sprite map's width. `100%` would cause the
+  sprite to be on the right-hand side of the sprite map. Defaults to the sprite map's
+  position value which defaults to `0px`. E.g. `$icon-new-position: 100%`.
+
+<a name="performance"></a>
+## Performance Considerations
+
+Reading PNG files and assembling new images and saving them to disk might have a non-trivial
+impact to your stylesheet compilation times. Especially for the first compile. Please keep
+this in mind.
+
+## Large numbers of sprites
+The magic stylesheet can get very large when there are large numbers of sprites. 50 sprites
+will cause there to be over 150 variables created and then passed into the `sprite` function.
+You may find that customizing the sprite function call to only pass those values that you
+are overriding will provide a performance boost.
+
+## Oily PNG
+
+Compass generates PNG files using a pure-ruby library called
+[`chunky_png`](https://github.com/wvanbergen/chunky_png). This library can be made faster by
+installing a simple C extension called [`oily_png`](https://github.com/wvanbergen/oily_png).
+Add it to your `Gemfile` if you have one in your project:
+
+    gem 'oily_png'
+
+Or install the Rubygem:
+
+    gem install oily_png
+
+Compass will automatically detect its presence.