Reference documentation on spriting

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

@@ -0,0 +1,8 @@
+---
+title: Spriting with Compass
+layout: tutorial
+crumb: Spriting
+classnames:
+  - tutorial
+---
+# Spriting with Compass

doc-src/content/reference/compass/helpers/sprites.haml

@@ -0,0 +1,132 @@
+--- 
+title: Compass Sprite Helpers
+crumb: Sprites
+framework: compass
+meta_description: Helper functions for working with Sprite images.
+layout: core
+classnames:
+  - reference
+  - core
+  - helpers
+---
+%h1 Compass Sprite Helpers
+
+:markdown
+  These helpers make it easier to build and to work with sprites.
+  
+  While it is allowed to use these directly, to do so is considered "advanced usage".
+  It is recommended that you instead use the sprite mixins that are designed to work
+  with these functions.
+  
+  See the [Spriting Tutorial](/help/tutorials/spriting/) for more information.
+
+#sprite-map.helper
+  %h3
+    %a(href="#sprite-map")
+      sprite-map(<span class="arg">$glob</span>, <span class="arg">...</span>)
+  .details
+    :markdown
+      Generates a sprite map from the files matching the glob pattern. Uses the
+      keyword-style arguments passed in to control the placement.
+      
+      Only PNG files can be made into sprites at this time.
+      
+      The `$glob` should be glob pattern relative to the images directory that specifies
+      what files will be in the sprite. For example:
+      
+          $icons: sprite-map("icons/*.png");
+          background: $icons;
+      
+      This will generate a sprite map and return a reference to it. It's important to
+      capture this to a variable, because you will need to use it later when creating
+      sprites. In the above example you might end up with a new file named
+      `images/sprites/icons-a2ef041.png` and your css stylesheet will have:
+      
+          background: url('/images/sprites/icons-a2ef041.png?1234678') no-repeat;
+      
+      The exact image name is not something you should depend on as it may change based on the
+      arguments you pass in. Instead, you can use the `sprite-url()` function to create a
+      reference to the sprite map without generating the image again. Alternatively, simply
+      using the sprite map variable in an property will have the same effect as calling
+      `sprite-url()`.
+      
+      For each sprite in the sprite map you can control the position, spacing, and whether or
+      not it repeats. You do this by passing arguments to this function that tell each sprite
+      how to behave. For instance if there is a icons/new.png then you can control it like so:
+      
+          $icon-sprite: sprite-map("icons/*.png",
+                          $new-position: 100%, $new-spacing: 15px, $new-repeat: no-repeat);
+      
+      If you don't specify these options they will default to `0%` for `position`,
+      `0px` for spacing, and `no-repeat` for `repeat`.
+      
+      Default values for all sprites can be specified by passing values for `$position`,
+      `$spacing`, and `$repeat`.
+
+#sprite.helper
+  %h3
+    %a(href="#sprite")
+      sprite(<span class="arg">$map</span>, <span class="arg">$sprite</span>, <span class="arg" data-default-value="0">$offset-x</span>, <span class="arg" data-default-value="0">$offset-y</span>)
+  .details
+    :markdown
+      Returns the image and background position for use in a single shorthand property:
+      
+          $icons: sprite-map("icons/*.png"); // contains icons/new.png among others.
+          background: sprite($icons, new) no-repeat;
+      
+      Becomes:
+      
+          background: url('/images/icons.png?12345678') 0 -24px no-repeat;
+
+#sprite-map-name.helper
+  %h3
+    %a(href="#sprite-map-name")
+      sprite-map-name(<span class="arg">$map</span>)
+  .details
+    :markdown
+      Returns the name of a sprite map
+      The name is derived from the folder than contains the sprites.
+
+#sprite-file.helper
+  %h3
+    %a(href="#sprite-file")
+      sprite-file(<span class="arg">$map</span>, <span class="arg">$sprite</span>)
+  .details
+    :markdown
+      Returns the relative path (from the images directory) to the original file
+      used when construction the sprite. This is suitable for passing to the
+      `image-width` and `image-height` helpers.
+
+#sprite-url.helper
+  %h3
+    %a(href="#sprite-url")
+      sprite-url(<span class="arg">$map</span>)
+  .details
+    :markdown
+      Returns a url to the sprite image.
+
+#sprite-position.helper
+  %h3
+    %a(href="#sprite-position")
+      sprite-position(<span class="arg">$map</span>, <span class="arg">$sprite</span>, <span class="arg" data-default-value="0">$offset-x</span>, <span class="arg" data-default-value="0">$offset-y</span>)
+  .details
+    :markdown
+      Returns the position for the original image in the sprite.
+      This is suitable for use as a value to background-position:
+      
+          $icons: sprite-map("icons/*.png");
+          background-position: sprite-position($icons, new);
+      
+      Might generate something like:
+      
+          background-position: 0 -34px;
+      
+      You can adjust the background relative to this position by passing values for
+      `$offset-x` and `$offset-y`:
+      
+          $icons: sprite-map("icons/*.png");
+          background-position: sprite-position($icons, new, 3px, -2px);
+      
+      Would change the above output to:
+      
+          background-position: 3px -36px;

doc-src/content/reference/compass/utilities/sprites/base.haml

@@ -0,0 +1,18 @@
+--- 
+title: Compass Sprite Base
+crumb: Sprite Base
+framework: compass
+stylesheet: compass/utilities/sprites/_base.scss
+layout: core
+nav_stylesheet: compass/_utilities.scss
+classnames:
+  - reference
+  - core
+  - utilities
+---
+- render 'reference' do
+  :markdown
+    These mixins are useful for working with sprites. This file is imported by
+    magic sprite imports.
+    
+    See the [Spriting Tutorial](/help/tutorials/spriting/) for more information.