Merge commit 'wolfr/docs' into docs

* commit 'wolfr/docs':
  Updated documentation for CSS3 module [multi line comment]
  Added descripton for box shadow mixin and updated box-shadow sass file so it gets parsed through markdown correctly

doc-src/content/reference/compass/css3.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    The CSS3 module provides cross-browser mixins for CSS properties introduced in CSS3, for example <code>border-radius</code> and <code>text-shadow</code>.

doc-src/content/reference/compass/css3/background_clip.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin for <code>background-clip</code>. See <a href="http://www.w3.org/TR/2009/CR-css3-background-20091217/#background-clip">CSS3 spec: background-clip</a>.

doc-src/content/reference/compass/css3/background_origin.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin for the background origin property. See <a href="http://www.w3.org/TR/css3-background/#the-background-origin">CSS3 spec: background-origin property</a>.

doc-src/content/reference/compass/css3/background_size.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    This mixin provides . See <a href="http://www.w3.org/TR/css3-background/#the-background-size">CSS3 spec: background-size</a>.

doc-src/content/reference/compass/css3/border_radius.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    The border-radius mixin is used to give a block element rounded corners. It automatically outputs the correct syntax for each browser (e.g. <code>-webkit-border-radius</code> and <code>-moz-border-radius</code>).
+    The border-radius mixin is used to give a block element rounded corners. It automatically outputs the correct vendor specific syntax for each browser (e.g. <code>-webkit-border-radius</code> and <code>-moz-border-radius</code>). See <a href="http://www.w3.org/TR/css3-background/#the-border-radius">CSS3 spec: border-radius</a>.

doc-src/content/reference/compass/css3/box_shadow.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    The box-shadow mixin is used to give a block element a drop shadow.

doc-src/content/reference/compass/css3/box_sizing.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin for the <code>box-sizing</code> property, which allows you to change how the box model works. See <a href="http://www.w3.org/TR/css3-ui/#box-sizing">W3C CSS3 spec: box-sizing</a>.

doc-src/content/reference/compass/css3/columns.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin for the CSS3 Multi-column layout module. See <a href="http://www.w3.org/TR/css3-multicol/">CSS3 spec: Multi-colum layout module</a>.

doc-src/content/reference/compass/css3/font_face.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin to support @font-face. See <a href="http://www.w3.org/TR/css3-fonts/#the-font-face-rule">CSS3 spec: @font-face</a>.

doc-src/content/reference/compass/css3/gradient.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin to create cross-browser CSS3 gradients.

doc-src/content/reference/compass/css3/inline_block.haml

@@ -8,4 +8,6 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a cross-browser method to implement <code>display: inline-block;</code>. Note that this was actually introduced in CSS2, but badly implemented across browsers. See <a href="http://www.w3.org/TR/CSS21/visuren.html#propdef-display">CSS2.1 spec: display</a>.
+  %blockquote
+    This value causes an element to generate a block box, which itself is flowed as a single inline box, similar to a replaced element. The inside of an inline-block is formatted as a block box, and the element itself is formatted as an inline replaced element. 

doc-src/content/reference/compass/css3/opacity.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides cross-browser CSS opacity. See <a href="http://www.w3.org/TR/css3-color/#transparency">CSS3 spec: transparency</a>.

doc-src/content/reference/compass/css3/text_shadow.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin for CSS text shadows. See <a href="http://www.w3.org/TR/2003/CR-css3-text-20030514/#text-shadows">CSS3 spec: text-shadow</a>.

doc-src/content/reference/compass/css3/transform.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides mixins for CSS3 transforms. See <a href="http://www.w3.org/TR/css3-2d-transforms/">W3C: CSS 2D transforms</a>.

doc-src/content/reference/compass/css3/transition.haml

@@ -8,4 +8,4 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    Provides a mixin for CSS3 transitions. See <a href="http://www.w3.org/TR/css3-transitions/">CSS3 Spec: transitions</a>.

frameworks/compass/stylesheets/compass/css3/_background_clip.sass

@@ -1,9 +1,13 @@
-// Background Clip
+//
-// clip the background (image and color) at the edge of the padding or border
+  Clip the background (image and color) at the edge of the padding or border.
-//  - [padding-box | border-box]
+
-//  - browser defaults to border-box, mixin defaults to padding-box
+  Default constant is padding-box, the box model used by modern browsers.
+
+  If you wish to do so, you can override the default constant with <code>border-box</code>
+
+  To override to the border-box model, use this code:
+      !default_background_clip = "border-box"
 
-//  override constants to change defaults
 !default_background_clip ||= "padding-box"
 
 =background-clip(!clip = !default_background_clip)

frameworks/compass/stylesheets/compass/css3/_background_origin.sass

@@ -1,9 +1,11 @@
-// Background Origin
+//
-// position the background off the edge of the padding, border or content
+  Position the background off the edge of the padding, border or content
-//  - [padding-box | border-box | content-box]
+  
-//  - browser defaults to padding-box, mixin defaults to content-box
+  * Possible values: [padding-box | border-box | content-box]
+  * browser defaults to padding-box, mixin defaults to content-box
+
+  Override constants to change defaults.
 
-//  override constants to change defaults
 !default_background_origin ||= "content-box"
 
 =background-origin(!origin = !default_background_origin)

frameworks/compass/stylesheets/compass/css3/_background_size.sass

@@ -1,7 +1,8 @@
-// Background Size
+//
-// Set the size of background images using px, width and height, or percentages
+  Set the size of background images using px, width and height, or percentages. Supported in: Opera, Gecko, Webkit.
-//  - percentages are relative to the background-origin (default = padding-box)
+  
-//  - mixin defaults to "100% auto"
+  * percentages are relative to the background-origin (default = padding-box)
+  * mixin defaults to "100% auto"
 
 //  override constants to change defaults
 !default_background_size ||= 100% "auto"

frameworks/compass/stylesheets/compass/css3/_border_radius.sass

@@ -1,28 +1,45 @@
 !default_border_radius ||= 5px
 
-// Round all borders by amount
+//
+  Round all borders by a specific amount, defaults to value of !default_border_radius
+
 =border-radius(!radius = !default_border_radius)
   border-radius= !radius
   -moz-border-radius= !radius
   -webkit-border-radius= !radius
 
-// Round radius at position by amount.
+//
-// values for !vert: "top", "bottom"
+  Round radius at position by amount.
-// values for !horz: "left", "right
+
+  * values for !vert: "top", "bottom"
+  * values for !horz: "left", "right"
+
 =border-corner-radius(!vert, !horz, !radius = !default_border_radius)
   border-#{!vert}-#{!horz}-radius= !radius
   -moz-border-radius-#{!vert}#{!horz}= !radius
   -webkit-border-#{!vert}-#{!horz}-radius= !radius
 
+//
+  Round top-left radius only
+  
 =border-top-left-radius(!radius = !default_border_radius)
   +border-corner-radius("top", "left", !radius)
 
+//
+  Round top-right radius only
+
 =border-top-right-radius(!radius = !default_border_radius)
   +border-corner-radius("top", "right", !radius)
 
+//
+  Round bottom-left radius only
+
 =border-bottom-left-radius(!radius = !default_border_radius)
   +border-corner-radius("bottom", "left", !radius)
 
+//
+  Round bottom-right radius only
+
 =border-bottom-right-radius(!radius = !default_border_radius)
   +border-corner-radius("bottom", "right", !radius)
 

frameworks/compass/stylesheets/compass/css3/_box_shadow.sass

@@ -1,10 +1,12 @@
-//**
+//
-  Provides cross-browser css box shadows for Webkit, Gecko, and CSS3 standard
+  Provides cross-browser CSS box shadows for Webkit, Gecko, and CSS3.
-  arguments are color, horizontal offset, vertical offset, and blur
 
-//**
+  Standard arguments are color, horizontal offset, vertical offset, and blur.
+
+//
   These defaults make the arguments optional for this mixin
-  If you like, set different defaults in your project
+
+  If you like, set different defaults in your project.
   
 !default_box_shadow_color     ||= #333
 !default_box_shadow_h_offset  ||= 1px

frameworks/compass/stylesheets/compass/css3/_box_sizing.sass

@@ -1,5 +1,6 @@
-//**
+//
   Change the box model for Mozilla, Webkit, IE8 and the future
+
   @param !bs
     [ content-box | border-box ]
 =box-sizing(!bs)

frameworks/compass/stylesheets/compass/css3/_columns.sass

@@ -1,36 +1,50 @@
-//**
+// Specify the # of columns
-  CSS3 columns for Mozilla, Webkit and the Future
 
 =column-count(!n)
   -moz-column-count= !n
   -webkit-column-count= !n
   column-count= !n
 
+// Specify the gap between columns e.g. 20px
+
 =column-gap(!u)
   -moz-column-gap= !u
   -webkit-column-gap= !u
   column-gap= !u
 
+// Specify the width of columns e.g. 100px
+
 =column-width(!u)
   -moz-column-width= !u
   -webkit-column-width= !u
   column-width= !u
 
+// Specify the width of the rule between columns e.g. 1px
+
 =column-rule-width(!w)
   -moz-column-rule-width= !w
   -webkit-column-rule-width= !w
   column-rule-width= !w
 
+// Specify the style of the rule between columns e.g. 'dotted'. This works like border-style.
+
 =column-rule-style(!s)
   -moz-column-rule-style= !s
   -webkit-column-rule-style= !s
   column-rule-style= !s
 
+// Specify the style of the rule between columns e.g. 'dotted'. This works like border-color.
+
 =column-rule-color(!c)
   -moz-column-rule-color= !c
   -webkit-column-rule-color= !c
   column-rule-color= !c
 
+//
+  Mixin encompassing all column rule rules
+  For example:
+      +column-rule('1px', 'solid', '#000')
+
 =column-rule(!w, !s = "solid", !c = " ")
   +column-rule-width(!w)
   +column-rule-style(!s)

frameworks/compass/stylesheets/compass/css3/_font_face.sass

@@ -1,10 +1,12 @@
-// @Font-Face
+//
-// Cross-browser support for @font-face
+  Cross-browser support for @font-face. Supports IE, Gecko, Webkit, Opera.
-//  - !name is required, arbitrary, and what you will use in font stacks.
+
-//  - !font_files is required using font_files('relative_location', 'format').
+  * !name is required, arbitrary, and what you will use in font stacks.
-//     - for best results use this order: woff, opentype/truetype, svg
+  * !font_files is required using font_files('relative_location', 'format').
-//  - !eot is required by IE, and is a relative location of the eot file.
+    * for best results use this order: woff, opentype/truetype, svg
-//  - postscript name is required by some browsers to look for local fonts.
+  * !eot is required by IE, and is a relative location of the eot file.
+  * postscript name is required by some browsers to look for local fonts.
+
 =font-face( !name, !font_files, !eot = false, !postscript = false, !style = false)
   @font-face
     font-family: '#{!name}'

frameworks/compass/stylesheets/compass/css3/_gradient.sass

@@ -1,3 +1,8 @@
+//
+  Gradient mixin for all types of gradients. Use the other mixins for specific types of gradients.
+
+  Arguments are type, coords, color_start, color_end and color_stop
+
 =gradient(!type, !coords, !color_start, !color_end, !color_stop = false)
   !gradient= "#{!coords}, from(#{!color_start}), to(#{!color_end})"
   @if !color_stop
@@ -5,35 +10,36 @@
   background: -webkit-gradient(#{!type}, #{!gradient})
   background: -moz-#{!type}-gradient(#{!gradient})
 
-//*
+//
-  // This will yeild a radial gradient with an apparent specular highlight
+  This will yield a radial gradient with an apparent specular highlight  
       +radial-gradient("45 45, 10, 52 50, 30", Cyan, DodgerBlue)
 
 =radial-gradient(!coords, !color1, !color2, !color_stop = false)
   +gradient("radial", !coords, !color1, !color2, !color_stop)
 
-//* 
+//
-  // This yields a linear gradient spanning from !start to !end coordinates
+  This yields a linear gradient spanning from !start to !end coordinates  
       +linear-gradient("left top", "left bottom", #fff, #ddd)
 
 =linear-gradient(!start, !end, !color1, !color2, !color_stop = false)
   !coords = !start + ", " + !end
   +gradient("linear", !coords, !color1, !color2, !color_stop)
 
-//*
+//
-  // This yields a gradient starting at the top with #fff, ending in #aaa
+  This yields a gradient starting at the top with #fff, ending in #aaa  
       +v-gradient(#fff, #aaa)
-  // Same as above but with a #ccc at the halfway point
+
+  Same as above but with a #ccc at the halfway point  
       +v-gradient(#fff, #aaa, color_stop(50%, #ccc))
-  // Same as the first example but with #ccc at the 30% from the top, and #bbb at 70% from the top
+  
+  Same as the first example but with #ccc at the 30% from the top, and #bbb at 70% from the top  
       +v-gradient(#fff, #aaa, color_stop(30%, #ccc, 70%, #bbb))
 
 =v-gradient(!color1, !color2, !color_stop = false)
   +linear-gradient("left top", "left bottom", !color1, !color2, !color_stop)
 
-//* 
+//
-  // This yields a horizontal linear gradient spanning from left to right
+  This yields a horizontal linear gradient spanning from left to right. It can be used just like v-gradient above  
-  // It can be used just like v-gradient above
       h-gradient(#fff, #ddd)
 
 =h-gradient(!color1, !color2, !color_stop = false)

frameworks/compass/stylesheets/compass/css3/_inline_block.sass

@@ -1,3 +1,6 @@
+//
+  Provides a cross-browser method to implement <code>display: inline-block;</code>
+
 =inline-block 
   display: -moz-inline-box
   -moz-box-orient: vertical

frameworks/compass/stylesheets/compass/css3/_opacity.sass

@@ -1,7 +1,9 @@
-//**
+//
-  Provides cross-browser css opacity.
+  Provides cross-browser CSS opacity. Takes a number between 0 and 1 as the argument, e.g. 0.5 for 50% opacity.
+
       @param !opacity
           A number between 0 and 1, where 0 is transparent and 1 is opaque.
+
 =opacity(!opacity)
   opacity= !opacity
   -moz-opacity= !opacity

frameworks/compass/stylesheets/compass/css3/_text_shadow.sass

@@ -1,9 +1,11 @@
-//**
+//
-  Provides css text shadows
+  Provides CSS text shadows.
-  arguments are color, horizontal offset, vertical offset, and blur
 
-//**
+  Arguments are color, horizontal offset, vertical offset, and blur
+
+//
   These defaults make the arguments optional for this mixin
+
   If you like, set different defaults in your project
   
 !default_text_shadow_color     ||= #aaa

frameworks/compass/stylesheets/compass/css3/_transform.sass

@@ -1,20 +1,26 @@
 // CSS Transform and Transform-Origin
 
-// Apply a transform sent as a complete string
+//
+  Apply a transform sent as a complete string.
+
 =apply-transform(!transform = false)
   transform= !transform
   -webkit-transform= !transform
   -moz-transform= !transform
 
-// Apply a transform-origin sent as a complete string
+//
+  Apply a transform-origin sent as a complete string.
+
 =apply-origin(!origin = false)
   transform-origin= !origin
   -webkit-transform-origin= !origin
   -moz-transform-origin= !origin
 
-// transform-origin requires x and y coordinates
+//
-//  - only applies the coordinates if they are there
+  transform-origin requires x and y coordinates
-//    so that it can be called by scale, rotate and skew safely
+  
+  * only applies the coordinates if they are there so that it can be called by scale, rotate and skew safely
+
 =transform-origin(!originx = 50%, !originy = 50%)
   !origin = false
   @if !originx and !originy
@@ -26,37 +32,42 @@
   @if !origin 
     +apply-origin(!origin)
 
-// A full transform mixin with everything you could want
+//
-//  - including origin adjustments if you want them
+  A full transform mixin with everything you could want
-//  - scale, rotate and skew don't require units
+
-//    scale takes a multiplier, rotate and skew take degrees
+  * including origin adjustments if you want them
+  * scale, rotate and skew don't require units
+  * scale takes a multiplier, rotate and skew take degrees
+
 =transform(!scale = 1, !rotate = 0, !transx = 0, !transy = 0, !skewx = 0, !skewy = 0, !originx = false, !originy = false)
   !transform = "scale(#{!scale}) rotate(#{!rotate}deg) translate(#{!transx}, #{!transy}) skew(#{!skewx}deg, #{!skewy}deg)"
   +apply-transform(!transform)
   +transform-origin(!originx, !originy)
 
-// Transform Partials
+//
-// These work well on their own, but they don't add to each other, they override
+   Transform Partials
-// Use them with extra origin args, or along side +transform-origin
+
+   These work well on their own, but they don't add to each other, they override.
+   Use them with extra origin args, or along side +transform-origin
+
+// Adjust only the scale, with optional origin coordinates
 
-// adjust only the scale
-//  - with optional origin coordinates
 =scale(!scale = 1.25, !originx = false, !originy = false)
   +apply-transform("scale(#{!scale})")
   +transform-origin(!originx, !originy)
 
-// adjust only the rotation
+// Adjust only the rotation, with optional origin coordinates
-//  - with optional origin coordinates
+
 =rotate(!rotate = 45, !originx = false, !originy = false)
   +apply-transform("rotate(#{!rotate}deg)")
   +transform-origin(!originx, !originy)
 
-// adjust only the translation
+// Adjust only the translation
+
 =translate(!transx = 0, !transy = 0)
   +apply-transform("translate(#{!transx}, #{!transy})")
 
-// adjust only the skew
+// Adjust only the skew, with optional origin coordinates
-//  - with optional origin coordinates
 =skew(!skewx = 0, !skewy = 0, !originx = false, !originy = false)
   +apply-transform("skew(#{!skewx}deg, #{!skewy}deg)")
   +transform-origin(!originx, !originy)

frameworks/compass/stylesheets/compass/css3/_transition.sass

@@ -1,53 +1,76 @@
-// CSS Transitions
+//
-// Currently only works in Webkit
+  CSS Transitions
-//  - expected in CSS3, FireFox 3.6/7 and Opera Presto 2.3
+  Currently only works in Webkit.
-//  - we'll be prepared.
+
+  * expected in CSS3, FireFox 3.6/7 and Opera Presto 2.3
+  * We'll be prepared.
+
+  Including this submodule sets following defaults for the mixins:
+
+      !default_transition_property ||= "all"
+      !default_transition_duration ||= 1s
+      !default_transition_function ||= false
+      !default_transition_delay ||= false
+
+  Override them if you like. Timing-function and delay are set to false for browser defaults (ease, 0s).
 
-// Override these defaults with your own, if you like
-//  - timing-function and delay are set to false for browser defaults (ease, 0s)
 !default_transition_property ||= "all"
 !default_transition_duration ||= 1s
 !default_transition_function ||= false
 !default_transition_delay ||= false
 
-// One or more properties to transition
+//
-//  - for multiple, use a comma-delimited list
+  One or more properties to transition
-//  - also accepts "all" or "none"
+
+  * for multiple, use a comma-delimited list
+  * also accepts "all" or "none"
+
 =transition-property(!properties = !default_transition_property)
   transition-property = !properties
   -webkit-transition-property = !properties
   -moz-transition-property = !properties
   -o-transition-property = !properties
 
-// One or more durrations in seconds
+//
-//  - for multiple, use a comma-delimited list
+  One or more durations in seconds
-//    - these durrations will effect the properties in the same list position
+
+  * for multiple, use a comma-delimited list
+  * these durations will affect the properties in the same list position
+
 =transition-duration(!duration = !default_transition_duration)
   transition-duration = !duration
   -webkit-transition-duration = !duration
   -moz-transition-duration = !duration
   -o-transition-duration = !duration
 
-// One or more timing functions
+//
-//  - [ ease | linear | ease-in | ease-out | ease-in-out | cubic-bezier(x1, y1, x2, y2)]
+  One or more timing functions
-//  - for multiple, use a comma-delimited list
+  
-//    - these functions will effect the properties in the same list position
+  * [ ease | linear | ease-in | ease-out | ease-in-out | cubic-bezier(x1, y1, x2, y2)]
+  * For multiple, use a comma-delimited list
+  * These functions will effect the properties in the same list position
+
 =transition-timing-function(!function = !default_transition_function)
   transition-timing-function = !function
   -webkit-transition-timing-function = !function
   -moz-transition-timing-function = !function
   -o-transition-timing-function = !function
 
-// One or more transition-delays in seconds
+//
-//  - for multiple, use a comma-delimited list
+  One or more transition-delays in seconds
-//    - these delays will effect the properties in the same list position
+
+  * for multiple, use a comma-delimited list
+  * these delays will effect the properties in the same list position
+
 =transition-delay(!delay = !default_transition_delay)
   transition-delay = !delay
   -webkit-transition-delay = !delay
   -moz-transition-delay = !delay
   -o-transition-delay = !delay
 
-// Transition all-in-one shorthand
+//
+  Transition all-in-one shorthand
+
 =transition(!properties = !default_transition_property, !duration = !default_transition_duration, !function = !default_transition_function, !delay = !default_transition_delay)
   +transition-property(!properties)
   +transition-duration(!duration)