Merge pull request #1722 from RAMilewski/master

Link fixes for Attachment Tutorial Reorg.
2025-08-12 13:44:14 +02:00 · 2025-06-18 21:56:47 -04:00
parent 94e0afbc41 afd6e23454
commit 6eb7b60d1e
1 changed files with 27 additions and 30 deletions
--- a/attachments.scad
+++ b/attachments.scad
@@ -61,7 +61,7 @@ _ANCHOR_TYPES = ["intersect","hull"];
 //   - Orientation is rotating an object so that its top is pointed towards a given vector.
 //   .
 //   An object will first be translated to its anchor position, then spun, then oriented.
-//   For a detailed step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachments).
+//   For a detailed step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Relative-Positioning).
 //   .
 //   For describing directions, faces, edges, and corners the library provides a set of shortcuts
 //   all based on combinations of unit direction vectors.  You can use these for anchoring and orienting
@@ -490,7 +490,7 @@ _ANCHOR_TYPES = ["intersect","hull"];
 //   PARENT() position(at) CHILDREN;
 // Description:
 //   Attaches children to a parent object at an anchor point.  For a step-by-step explanation
-//   of attachments, see the [Attachments Tutorial](Tutorial-Attachments).
+//   of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Relative-Positioning).
 // Arguments:
 //   at = The vector, or name of the parent anchor point to attach to.
 // Side Effects:
@@ -536,7 +536,7 @@ module position(at,from)
 //   PARENT() orient(anchor, [spin]) CHILDREN;
 // Description:
 //   Orients children such that their top is tilted in the direction of the specified parent anchor point. 
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Relative-Positioning).
 // Arguments:
 //   anchor = The anchor on the parent which you want to match the orientation of.
 //   spin = The spin to add to the children.  (Overrides anchor spin.)
@@ -834,8 +834,7 @@ function _make_anchor_legal(anchor,geom) =
 //   These options will probably be necessary, in fact, to get the child correctly positioned.  Note that
 //   giving `spin=` to `attach()` in this case is the same as applying `zrot()` to the child. 
 //   .
-//   For a step-by-step explanation of
-//   attachments, see the [Attachments Tutorial](Tutorial-Attachments).
+//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Relative-Positioning).
 // Arguments:
 //   parent = The parent anchor point to attach to or a list of parent anchor points.
 //   child = Optional child anchor point.  If given, orients the child to connect this anchor point to the parent anchor.
@@ -1126,7 +1125,7 @@ module attach_part(name)
 //   This works by setting the `$tag` variable, but it provides extra error checking and
 //   handling of scopes.  You may set `$tag` directly yourself, but this is not recommended.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = tag string, which must not contain any spaces.
 // Side Effects:
@@ -1163,7 +1162,7 @@ module tag(tag)
 //   Assigns the specified tag to the children at the current level only, with tags reverting to
 //   the previous tag in force for deeper descendents.  This works using `$tag` and `$save_tag`.  
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = tag string, which must not contain any spaces.
 // Side Effects:
@@ -1217,7 +1216,7 @@ module tag_this(tag)
 //   get the correct behavior, every non-attachable module needs an invocation of force_tag, even ones
 //   that are not tagged.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = tag string, which must not contain any spaces
 // Side Effects:
@@ -1264,7 +1263,7 @@ module force_tag(tag)
 //   specified tag from a parent, which can be very confusing to a user trying to change the tag on a module.
 //   The `do_tag` parameter allows you to apply a default tag conditionally without having to repeat the children.  
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = tag string, which must not contain any spaces.
 //   do_tag = if false do not set the tag.  
@@ -1419,7 +1418,7 @@ module tag_scope(scope){
 //   .
 //   Note that `diff()` invokes its children three times.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   remove = String containing space delimited set of tag names of children to difference away.  Default: `"remove"`
 //   keep = String containing space delimited set of tag names of children to keep; that is, to union into the model after differencing is completed.  Default: `"keep"`
@@ -1595,7 +1594,7 @@ module diff(remove="remove", keep="keep")
 //   but if you have kept objects and want to operate on this difference object as a whole object using
 //   more tag operations, you will probably not get the results you want if you simply use {{tag()}}.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = Tag string to apply to this difference object.  Default: `""` (no tag)
 //   remove = String containing space delimited set of tag names of children to difference away.  Default: `"remove"`
@@ -1675,7 +1674,7 @@ module tag_diff(tag="",remove="remove", keep="keep")
 //   .
 //   Note that `intersect()` invokes its children three times.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   intersect = String containing space delimited set of tag names of children to intersect.  Default: "intersect"
 //   keep = String containing space delimited set of tag names of children to keep whole.  Default: "keep"
@@ -1738,7 +1737,7 @@ module intersect(intersect="intersect",keep="keep")
 //   but if you have kept objects and want to operate on this difference object as a whole object using
 //   more tag operations, you will probably not get the results you want if you simply use {{tag()}}.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = Tag to set for the intersection.  Default: `""` (no tag)
 //   intersect = String containing space delimited set of tag names of children to intersect.  Default: "intersect"
@@ -1794,7 +1793,7 @@ module tag_intersect(tag="",intersect="intersect",keep="keep")
 //   .
 //   Note that `conv_hull()` invokes its children twice.  
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   keep = String containing space delimited set of tag names of children to keep out of the hull.  Default: "keep"
 // Example:
@@ -1833,7 +1832,7 @@ module conv_hull(keep="keep")
 //   but if you have kept objects and want to operate on the hull object as a whole object using
 //   more tag operations, you will probably not get the results you want if you simply use {{tag()}}.
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Arguments:
 //   tag = Tag string to apply to this convex hull object.  Default: `""` (no tag)
 //   keep = String containing space delimited set of tag names of children to keep out of the hull.  Default: "keep"
@@ -1880,7 +1879,7 @@ module tag_conv_hull(tag="",keep="keep")
 //   hide(tags) CHILDREN;
 // Description:
 //   Hides all attachable children with the given tags, which you supply as a space separated string. Previously hidden objects remain hidden, so hiding is cumulative, unlike `show_only()`.
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Side Effects:
 //   Sets `$tags_hidden` to include the tags you specify.
 // Example:  Hides part of the model.
@@ -1915,7 +1914,7 @@ module hide(tags)
 //   hide_this() CHILDREN;
 // Description:
 //   Hides all attachable children at the current level, while still displaying descendants.  
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Side Effects:
 //   Sets `$tag` and `$save_tag`
 // Example: Use an invisible parent to position children.  Unlike with {{hide()}} we do not need to explicitly use any tags.  
@@ -1948,7 +1947,7 @@ module hide_this()
 //   show_only(tags) CHILDREN;
 // Description:
 //   Show only the children with the listed tags, which you supply as a space separated string.  Only unhidden objects will be shown, so if an object is hidden either before or after the `show_only()` call then it will remain hidden.  This overrides any previous `show_only()` calls.  Unlike `hide()`, calls to `show_only()` are not cumulative.
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of tagged attachments, see the [Attachments Tutorial](Tutorial-Attachment-Tags).
 // Side Effects:
 //   Sets `$tags_shown` to the tag you specify.
 // Example:  Display the attachments but not the parent
@@ -2027,7 +2026,7 @@ module show_int(tags)
 //   (Z-) shaped to be diffed away from the face of parent attachable shape.  If no tag is set then
 //   `face_mask()` sets the tag for children to "remove" so that it will work with the default {{diff()}} tag.
 //   For details on specifying the faces to mask see [Specifying Faces](attachments.scad#subsection-specifying-faces).
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 // Arguments:
 //   edges = Faces to mask.  See  [Specifying Faces](attachments.scad#subsection-specifying-faces) for information on specifying faces.  Default: All faces
 // Side Effects:
@@ -2070,7 +2069,7 @@ module face_mask(faces=[LEFT,RIGHT,FRONT,BACK,BOT,TOP]) {
 //   quadrant (X+Y+) shaped to be diffed away from the edge of parent attachable shape.  If no tag is set
 //   then `edge_mask` sets the tag for children to "remove" so that it will work with the default {{diff()}} tag.
 //   For details on specifying the edges to mask see [Specifying Edges](attachments.scad#subsection-specifying-edges).
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 // Figure: A Typical Edge Rounding Mask
 //   module roundit(l,r) difference() {
 //       translate([-1,-1,-l/2])
@@ -2133,7 +2132,7 @@ module edge_mask(edges=EDGES_ALL, except=[]) {
 //   be differenced away.  The 3D corner mask shape should be designed to mask away the X+Y+Z+ octant.  If no tag is set
 //   then `corner_mask` sets the tag for children to "remove" so that it will work with the default {{diff()}} tag.
 //   See [Specifying Corners](attachments.scad#subsection-specifying-corners) for information on how to specify corner sets.
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 // Arguments:
 //   corners = Corners to mask.  See [Specifying Corners](attachments.scad#subsection-specifying-corners).  Default: All corners.
 //   except = Corners to explicitly NOT mask.  See [Specifying Corners](attachments.scad#subsection-specifying-corners).  Default: No corners.
@@ -2181,7 +2180,7 @@ module corner_mask(corners=CORNERS_ALL, except=[]) {
 //   Given a 2D edge profile, extrudes it into a mask for all edges and corners bounding each given face. If no tag is set
 //   then `face_profile` sets the tag for children to "remove" so that it will work with the default {{diff()}} tag.
 //   See  [Specifying Faces](attachments.scad#subsection-specifying-faces) for information on specifying faces.
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 // Arguments:
 //   faces = Faces to mask edges and corners of.
 //   r = Radius of corner mask.
@@ -2222,8 +2221,7 @@ module face_profile(faces=[], r, d, excess=0.01, convexity=10) {
 //   extruded length to be `diff()`ed away, to give the edge a matching profile.  If no tag is set
 //   then `edge_profile` sets the tag for children to "remove" so that it will work with the default {{diff()}} tag.
 //   For details on specifying the edges to mask see [Specifying Edges](attachments.scad#subsection-specifying-edges).
-//   For a step-by-step
-//   explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachments).
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 // Arguments:
 //   edges = Edges to mask.  See [Specifying Edges](attachments.scad#subsection-specifying-edges).  Default: All edges.
 //   except = Edges to explicitly NOT mask.  See [Specifying Edges](attachments.scad#subsection-specifying-edges).  Default: No edges.
@@ -2318,8 +2316,7 @@ module edge_profile(edges=EDGES_ALL, except=[], excess=0.01, convexity=10) {
 //   orientation and extruded length to be `diff()`ed away, to give the edges and corners a matching profile.
 //   If no tag is set then `edge_profile_asym()` sets the tag for children to "remove" so that it will work
 //   with the default {{diff()}} tag.  For details on specifying the edges to mask see [Specifying Edges](attachments.scad#subsection-specifying-edges).
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
-//   .
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 //   The asymmetric profiles are joined consistently at the corners.  This is impossible if all three edges at a corner use the profile, hence
 //   this situation is not permitted.  The profile orientation can be inverted using the `flip=true` parameter.
 //   .
@@ -2670,7 +2667,7 @@ module edge_profile_asym(
 //   to the selected corners with the appropriate orientation. If no tag is set then `corner_profile()`
 //   sets the tag for children to "remove" so that it will work with the default {{diff()}} tag.
 //   See [Specifying Corners](attachments.scad#subsection-specifying-corners) for information on how to specify corner sets.
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of masking attachments, see the [Attachments Tutorial](Tutorial-Attachment-Edge-Profiling).
 // Arguments:
 //   corners = Corners to mask.  See [Specifying Corners](attachments.scad#subsection-specifying-corners).  Default: All corners.
 //   except = Corners to explicitly NOT mask.  See [Specifying Corners](attachments.scad#subsection-specifying-corners).  Default: No corners.
@@ -2813,7 +2810,7 @@ module corner_profile(corners=CORNERS_ALL, except=[], r, d, convexity=10) {
 //   Note that anchors created by attachable() are generally intended for use by the user-supplied children of the attachable object, but they
 //   are available internally and can be used in the object's definition.  
 //   .
-//   For a step-by-step explanation of attachments, see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
+//   For a step-by-step explanation of making objects attachable, see the [Attachments Tutorial](Tutorial-Attachment-Making).
 //
 // Arguments:
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
@@ -3338,8 +3335,8 @@ function reorient(
 //   Creates an anchor data structure.  You can specify the position, orient direction and spin directly.
 //   Alternatively for the 3D case you can give a 4x4 rotation matrix which can specify the orient and spin, and optionally
 //   the position, using a translation component of the matrix.  If you specify `pos` along with `rot` then the position you
-//   give overrides any translation included in `rot`.  For a step-by-step explanation of attachments,
-//   see the [Attachments Tutorial](Tutorial-Attachments).
+//   give overrides any translation included in `rot`.  For a step-by-step explanation of attachments, 
+//   see the [Attachments Tutorial](Tutorial-Attachment-Basic-Positioning).
 // Arguments:
 //   name = The string name of the anchor.  Lowercase.  Words separated by single dashes.  No spaces.
 //   pos = The [X,Y,Z] position of the anchor.