'rotate' and 'rotateBy' should be pure 2D operations

Author: dirkschulze

matrix/ChangeLog

@@ -1,2 +1,6 @@
+2013-03-07  Dirk Schulze  <dschulze@adobe.com>
+	'rotate' and 'rotateBy' should be pure 2D operations.
+	More detailed example for passing DOM string and stringifier.
+
 2013-03-07  Dirk Schulze  <dschulze@adobe.com>
 	Fixed typos in defitnions.

matrix/index.html

@@ -149,9 +149,18 @@ <h3>The constructors</h3>
             </dl>
             The DOMString must consist of a transform function list as specified by CSS Transforms.
             <div class='example'>
+              <p>In the following example a CSS Transform string is passed to the Matrix constructor.</p>
               <pre><code>var matrix = new Matrix("translate(20px,20px), scale(2,3), rotate(45deg)"</code></pre>
+              <p>The resulting matrix is equal to the following sequence of method calls:</p>
+              <pre><code>
+var matrix = new Matrix();
+matrix.translateBy(20,20);
+matrix.scaleNonUniformBy(2,3);
+matrix.rotateBy(45);
+              </code></pre>
             </div>
             <p class='issue'>Should it be postponed to avoid CSS3 Transforms dependency?</p>
+            <p class='issue'>Should unit-less values (like for SVG transform presentation attribute) be allowed too? <code>"translate(20,20)"</code></p>
           </dd>
           <dt>Constructor()</dt>
           <dd>
@@ -412,8 +421,6 @@ <h3>Immutable transformation methods</h3>
                 <dd>Transformation origin on the x-axis. Defaulting to 0.</dd>
                 <dt>optional double y</dt>
                 <dd>Transformation origin on the y-axis. Defaulting to 0.</dd>
-                <dt>optional double z</dt>
-                <dd>Transformation origin on the z-axis. Defaulting to 0.</dd>
               </dl>
               Post-multiplies a rotation transformation on the current matrix with the given origin and returns the resulting matrix. The current matrix is not modified.
             </dd>
@@ -579,8 +586,6 @@ <h3>Mutable transformation methods</h3>
                 <dd>Transformation origin on the x-axis. Defaulting to 0.</dd>
                 <dt>optional double y</dt>
                 <dd>Transformation origin on the y-axis. Defaulting to 0.</dd>
-                <dt>optional double z</dt>
-                <dd>Transformation origin on the z-axis. Defaulting to 0.</dd>
               </dl>
               Post-multiplies a rotation transformation on the current matrix with the given origin.
             </dd>
@@ -675,8 +680,21 @@ <h3>Helper methods</h3>
             </dd>
             <dt>void stringifier()</dt>
             <dd>
-              Returns a string in the form of a CSS Transforms <code>matrix</code> function if the current matrix is a 2D transform or a CSS Transforms <code>matrix3d</code> else.
+              Returns a string in the form of a CSS Transforms <code>matrix</code> function if the current matrix is a 2D transform or a CSS Transforms <code>matrix3d</code> else. The syntax is as specified in CSS Transforms [[!CSS3-TRANSFORMS]].
               <p class='issue'>Should be <code>stringifier;</code>. Bug in old respec tool.</p>
+              <div class='example'>
+                <p>In this example a matrix is created and several methods with 2D transformations are called.</p>
+                <pre><code>var matrix = new Matrix();
+matrix.scaleBy(2);
+matrix.translateBy(20,20);</code></pre>
+                <p>The <code>matrix.toString()</code> returns the DOM string:</p>
+                <pre><code>"matrix(2,0,0,2,20,20)"</code></pre>
+                <p>For 3D operations, the <var>stringifier</var> returns DOM string representing a 3D matrix.</p>
+                <pre><code>var matrix = new Matrix();
+matrix.scale3dBy(2);</code></pre>
+                <p>Calling <code>matrix.toString()</code> after the snippet above returns the DOM string:</p>
+                <pre><code>"matrix3d(2,0,0,0,0,2,0,0,0,0,2,0,0,0,0,1)"</code></pre>
+              </div>
             </dd>
           </dl>
       </section>