Change orient() to have only the anchor argument

attachments.scad

@@ -429,73 +429,51 @@ module position(from)
 
 // Module: orient()
 // Usage:
-//   orient(dir, [spin=]) CHILDREN;
+//   PARENT() orient(anchor, [spin]) CHILDREN;
-//   PARENT() orient(anchor=, [spin=]) CHILDREN;
 // Topics: Attachments
 // Description:
-//   Orients children such that their top is tilted towards the given direction, or towards the
+//   Orients children such that their top is tilted in the direction of the specified parent anchor point. 
-//   direction of a given anchor point on the parent.  For a step-by-step explanation of
+//   For a step-by-step explanation of attachments, see the [[Attachments Tutorial|Tutorial-Attachments]].
-//   attachments, see the [[Attachments Tutorial|Tutorial-Attachments]].
 // Arguments:
-//   dir = The direction to orient towards.
+//   anchor = The anchor on the parent which you want to match the orientation of.
-//   ---
-//   anchor = The anchor on the parent which you want to match the orientation of.  Use instead of `dir`.
 //   spin = The spin to add to the children.  (Overrides anchor spin.)
 // Side Effects:
 //   `$attach_anchor` is set to the `[ANCHOR, POSITION, ORIENT, SPIN]` information for the `anchor=`, if given.
 //   `$attach_to` is set to `undef`.
 //   `$attach_norot` is set to `true`.
 // See Also: attachable(), attach(), orient()
-// Example: Orienting by Vector
+// Example: When orienting to an anchor, the spin of the anchor may cause confusion:
 //   prismoid([50,50],[30,30],h=40) {
 //       position(TOP+RIGHT)
 //           orient(RIGHT)
 //               prismoid([30,30],[0,5],h=20,anchor=BOT+LEFT);
 //   }
-// Example: When orienting to an anchor, the spin of the anchor may cause confusion:
-//   prismoid([50,50],[30,30],h=40) {
-//       position(TOP+RIGHT)
-//           orient(anchor=RIGHT)
-//               prismoid([30,30],[0,5],h=20,anchor=BOT+LEFT);
-//   }
 // Example: You can override anchor spin with `spin=`.
 //   prismoid([50,50],[30,30],h=40) {
 //       position(TOP+RIGHT)
-//           orient(anchor=RIGHT,spin=0)
+//           orient(RIGHT,spin=0)
 //               prismoid([30,30],[0,5],h=20,anchor=BOT+LEFT);
 //   }
 // Example: Or you can anchor the child from the back
 //   prismoid([50,50],[30,30],h=40) {
 //       position(TOP+RIGHT)
-//           orient(anchor=RIGHT)
+//           orient(RIGHT)
 //               prismoid([30,30],[0,5],h=20,anchor=BOT+BACK);
 //   }
-module orient(dir, anchor, spin) {
+module orient(anchor, spin) {
     req_children($children);
-    if (!is_undef(dir)) {
+    check=
-        spin = default(spin, 0);
+      assert($parent_geom != undef, "No parent to orient from!")
-        check =
+      assert(is_string(anchor) || is_vector(anchor));
-          assert(anchor==undef, "Only one of dir= or anchor= may be given to orient()")
+    anch = _find_anchor(anchor, $parent_geom);
-          assert(is_vector(dir))
+    two_d = _attach_geom_2d($parent_geom);
-          assert(is_finite(spin));
+    fromvec = two_d? BACK : UP;
-        two_d = _attach_geom_2d($parent_geom);
+    $attach_to = undef;
-        fromvec = two_d? BACK : UP;
+    $attach_anchor = anch;
-        rot(spin, from=fromvec, to=dir) children();
+    $attach_norot = true;
-    } else {
+    spin = default(spin, anch[3]);
-        check=
+    assert(is_finite(spin));
-          assert(dir==undef, "Only one of dir= or anchor= may be given to orient()")
+    rot(spin, from=fromvec, to=anch[2]) children();
-          assert($parent_geom != undef, "No parent to orient from!")
-          assert(is_string(anchor) || is_vector(anchor));
-        anch = _find_anchor(anchor, $parent_geom);
-        two_d = _attach_geom_2d($parent_geom);
-        fromvec = two_d? BACK : UP;
-        $attach_to = undef;
-        $attach_anchor = anch;
-        $attach_norot = true;
-        spin = default(spin, anch[3]);
-        assert(is_finite(spin));
-        rot(spin, from=fromvec, to=anch[2]) children();
-    }
 }
 
 

tutorials/Attachments.md

@@ -391,19 +391,18 @@ orient the object relative to some face other than the TOP face that
 meets at that edge or corner.  You can always apply a `rotation()` to 
 change the orientation of the child object, but in order to do this,
 you need to figure out the correct rotation.  The `orient()` module provides a
-mechanism for re-orienting the child() that eases this burden.
+mechanism for re-orienting the child() that eases this burden: 
-Using its `anchor=` argument you can orient the
+it can orient the child relative to the parent anchor directions.  This is different
-child relative to the parent anchor directions.  This is different
 than giving an `orient=` argument to the child, because that orients
 relative to the parent's global coordinate system by just using the vector
-directly instead of orienting to the parent's anchor, which takes
+directly, instead of orienting to the parent's anchor, which takes
 account of face orientation.  A series of three
 examples shows the different results.  In the first example, we use
 only `position()`.  The child cube is erected pointing upwards, in the
 Z direction.  In the second example we use `orient=RIGHT` in the child
 and the result is that the child object points in the X+ direction,
 without regard for the shape of the parent object.  In the final
-example we apply `orient(anchor=RIGHT)` and the child is oriented
+example we apply `orient(RIGHT)` and the child is oriented
 relative to the slanted right face of the parent using the parent
 RIGHT anchor.   
 
@@ -427,7 +426,7 @@ prismoid([50,50],[30,30],h=40)
 include<BOSL2/std.scad>
 prismoid([50,50],[30,30],h=40)
   position(RIGHT+TOP)
-     orient(anchor=RIGHT)
+     orient(RIGHT)
         cube([15,15,25],anchor=BACK+BOT);
 ```
 
@@ -460,17 +459,11 @@ prismoid([50,50],[30,30],h=40)
 include<BOSL2/std.scad>
 prismoid([50,50],[30,30],h=40)
   position(RIGHT+TOP)
-     orient(anchor=RIGHT)
+     orient(RIGHT)
         anchor_arrow(40);
 ```
 
 
-Note also that `orient()` can be used to orient the child relative to
-the parent global coordinate system using its first argument, `dir=`.  This
-use of `orient()` is the same as using the `orient=` argument for the
-child object.    
-
-
 ## Attachment overview
 
 Attachables get their name from their ability to be attached to each
@@ -590,7 +583,7 @@ cube(50,center=true)
 In the second example, the child object points diagonally away
 from the cube.  If you want the child at at edge of the parent it's
 likely that this result will not be what you want.  To get a different
-result, use `position()` with `orient(anchor=)`, if needed. 
+result, use `position()` with `orient()`, if needed. 
 
 If you give an anchor point to the child object it moves the child
 around (in the attached coordinate system).  Or alternatively you can