From e35269a552aa1e02dc2bea7ac892e1cf1ca98648 Mon Sep 17 00:00:00 2001
From: Justin Lin <caterpillar@openhome.cc>
Date: Wed, 25 Mar 2020 08:32:17 +0800
Subject: [PATCH] add doc

---
 README.md                |  6 ++--
 docs/lib2x-ptf_rotate.md | 67 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 docs/lib2x-ptf_rotate.md

diff --git a/README.md b/README.md
index e92c3eb3..57a31144 100644
--- a/README.md
+++ b/README.md
@@ -73,7 +73,7 @@ See [examples](examples).
 	- [triangulate](https://openhome.cc/eGossip/OpenSCAD/lib2x-triangulate.html)
 
 - 2D/3D Function
-	- [rotate_p](https://openhome.cc/eGossip/OpenSCAD/lib2x-rotate_p.html)
+	- [rotate_p](https://openhome.cc/eGossip/OpenSCAD/lib2x-rotate_p.html) (It'll be deprecated from 2.3. Use `ptf/ptf_rotate` instead.)
 	- [cross_sections](https://openhome.cc/eGossip/OpenSCAD/lib2x-cross_sections.html)
 	- [paths2sections](https://openhome.cc/eGossip/OpenSCAD/lib2x-paths2sections.html)
 	- [path_scaling_sections](https://openhome.cc/eGossip/OpenSCAD/lib2x-path_scaling_sections.html)
@@ -145,7 +145,7 @@ See [examples](examples).
 	- [matrix/m_shearing](https://openhome.cc/eGossip/OpenSCAD/lib2x-m_shearing.html)
 
 - Point Transformation (2.3 Preview)
-    - ptf/ptf_rotate
+    - [ptf/ptf_rotate](https://openhome.cc/eGossip/OpenSCAD/lib2x-ptf_rotate.html)
     - ptf/ptf_x_twist
 	- ptf/ptf_y_twist
 	- ptf/ptf_circle
@@ -153,7 +153,7 @@ See [examples](examples).
 	- ptf/ptf_ring
 	- ptf/ptf_sphere
 	- ptf/ptf_torus
-	
+
 ----
 
 - Turtle
diff --git a/docs/lib2x-ptf_rotate.md b/docs/lib2x-ptf_rotate.md
new file mode 100644
index 00000000..0a7be09a
--- /dev/null
+++ b/docs/lib2x-ptf_rotate.md
@@ -0,0 +1,67 @@
+# ptf_rotate
+
+Rotates a point `a` degrees around the axis of the coordinate system or an arbitrary axis. It behaves as the built-in `rotate` module
+
+## Parameters
+
+- `point` : A 3D point `[x, y, z]` or a 2D point `[x, y]`.
+- `a` : If it's `[deg_x, deg_y, deg_z]`, the rotation is applied in the order `x`, `y`, `z`. If it's `[deg_x, deg_y]`, the rotation is applied in the order `x`, `y`.  If it's`[deg_x]`, the rotation is only applied to the `x` axis. If it's an number, the rotation is only applied to the `z` axis or an arbitrary axis.
+- `v`: A vector allows you to set an arbitrary axis about which the object will be rotated. When `a` is an array, the `v` argument is ignored. 
+
+**Since:** 2.3.
+
+## Examples
+
+    use <ptf/ptf_rotate.scad>;
+
+	point = [20, 0, 0];
+	a = [0, -45, 45];
+	
+	hull() {
+	    sphere(1);
+	    translate(ptf_rotate(point, a))    
+	       rotate(a)  
+	           sphere(1);   
+	}  
+
+![ptf_rotate](images/lib-rotate_p-1.JPG)
+
+    use <ptf/ptf_rotate.scad>;
+
+	radius = 40;
+	step_angle = 10;
+	z_circles = 20;
+	
+	points = [for(a = [0:step_angle:90 * z_circles]) 
+	    ptf_rotate(
+	        [radius, 0, 0], 
+	        [0, -90 + 2 * a / z_circles, a]
+	    )
+	];
+	
+	for(p = points) {
+	    translate(p) 
+	        sphere(1);
+	}
+	
+	%sphere(radius);
+
+![ptf_rotate](images/lib-rotate_p-2.JPG)
+
+	use <ptf/ptf_rotate.scad>;
+
+	v = [10, 10, 10];
+
+	hull() {
+		sphere(1);
+		translate(v)
+		sphere(1);   
+	}
+
+	p = [10, 10, 0];
+	for(i = [0:20:340]) {
+		translate(ptf_rotate(p, a = i, v = v)) 
+			sphere(1);  
+	}
+	
+![ptf_rotate](images/lib-rotate_p-3.JPG)
\ No newline at end of file