Doc cleanup

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

@@ -14,4 +14,4 @@ classnames:
 - render 'reference' do
   %p.warning
     This import is deprecated. Please import
-    <a href="/docs/reference/compass/css3/box_shadow_v2/" class="better">box_shadow_v2</a> instead.
+    <a href="/docs/reference/compass/css3/box_shadow_v2/" class="better">box-shadow-v2</a> instead.

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

@@ -14,4 +14,5 @@ classnames:
 - render 'reference' do
   %p.warning
     This import is deprecated. Please import
-    <a href="/docs/reference/compass/css3/text-shadow-v2/" class="better">text_shadow_v2</a> instead.
+    <a href="/docs/reference/compass/css3/text-shadow-v2/" class="better">text-shadow-v2</a>
+    instead.

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

@@ -12,4 +12,16 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Provides mixins for CSS3 2D and 3D transforms. See <a href="http://www.w3.org/TR/css3-2d-transforms/">W3C: CSS 2D transforms</a> and See <a href="http://www.w3.org/TR/css3-3d-transforms/">W3C: CSS 3D transforms</a>.
+    Provides mixins for CSS3 2D and 3D transforms. See
+    <a href="http://www.w3.org/TR/css3-2d-transforms/">W3C: CSS 2D transforms</a>
+    and See <a href="http://www.w3.org/TR/css3-3d-transforms/">W3C: CSS 3D transforms</a>.
+  %p
+    Safari is the only browser that currently supports 3D transforms.
+    Because of that it can be important to control whether a given 2D transform
+    uses the full range of experimental browser prefixes, or only the 3D list.
+    To make that easy, all 2D transforms include an browser-targeting toggle ($only3d)
+    to switch between the two support lists. The toggle defaults to 'false' (2D),
+    and also accepts 'true' (3D). Currently the lists are as follows:
+    2D: Mozilla, Webkit, Opera, Official
+    3D: Webkit, Official **(Only Safari Supports 3D perspective)**
+  

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

@@ -14,4 +14,4 @@ classnames:
 - render 'reference' do
   %p.warning
     This import is deprecated. Please import
-    <a href="/docs/reference/compass/css3/transform-v2/" class="better">transform_v2</a> instead.
+    <a href="/docs/reference/compass/css3/transform-v2/" class="better">transform-v2</a> instead.

doc-src/content/tutorials/upgrading/css3-v2.markdown

@@ -1,3 +1,11 @@
+---
+title: CSS3 v2 Upgrade
+layout: tutorial
+crumb: CSS3 v2 Upgrade
+classnames:
+  - tutorial
+---
+# Upgrading to Compass CSS3 v2
 The `css3` import is deprecated as well as the following css3 modules:
 `box-shadow`, `text-shadow`, and `transform`. Instead import `css3/version-2`,
 `box-shadow-v2`, `text-shadow-v2`, and `transform-v2` respectively.
@@ -8,3 +16,38 @@ with the new, betterer APIs.
 You should read about what changed, update your stylesheets accordingly
 and then update your imports to the new version.
 
+<a name="box-shadow"></a>
+## Box Shadow
+The arguments to the [`box-shadow`][new_box_shadow] mixin have changed.
+As a result you should change your import of `compass/css3/box-shadow`
+to `compass/css3/box-shadow-v2` once you do one of the following choices:
+
+1. Change your use of the `box-shadow` and instead use `single-box-shadow`.
+   This mixin has the same behavior and arguments as the old `box-shadow` mixin.
+2. Keep using `box-shadow`, change how you pass the arguments. The new
+   `box-shadow` takes up to 10 comma-delimited shadows. Each shadow is
+   how the values should appear in the CSS (space separated).
+
+## Text Shadow
+
+Similarly to how the box shadow changed. The new [text-shadow][new_text_shadow]
+mixin now accepts multiple shadows. As a result you should change your import of
+`compass/css3/text-shadow` to `compass/css3/text-shadow-v2` once you do one of
+the following choices:
+
+1. Change your use of the `text-shadow` and instead use `single-text-shadow`.
+   This mixin has the same behavior and arguments as the old `text-shadow` mixin.
+2. Keep using `text-shadow`, change how you pass the arguments. The new
+   `text-shadow` takes up to 10 comma-delimited shadows. Each shadow is
+   how the values should appear in the CSS (space separated).
+
+## CSS Transforms
+The transform module was largely re-written to support 3D transforms. If you
+are using it, it is suggested that you read the [new module's documentation][new_transform]
+and adjust your code appropriately. Many mixin names and constants have changed.
+
+[old_box_shadow]: /docs/reference/compass/css3/box_shadow/#mixin-box-shadow
+[new_box_shadow]: /docs/reference/compass/css3/box_shadow_v2/#mixin-box-shadow
+[old_text_shadow]: /docs/reference/compass/css3/text_shadow/#mixin-text-shadow
+[new_text_shadow]: /docs/reference/compass/css3/text-shadow-v2/#mixin-text-shadow
+[new_transform]: /docs/reference/compass/css3/transform-v2/