Merge pull request #6001 from freesewing/joost

feat(core): Added Path.combine and related changes, closes #5976

markdown/dev/reference/api/path/combine/en.md

@@ -0,0 +1,58 @@
+---
+title: Path.combine()
+---
+
+The `Path.combines()` method combines this path with one or more other paths
+into a single Path instance.
+
+Any gaps in the path (caused by move operations) will be left as-is, rather
+than joined with a line.  If that's not what you want, you should use
+[`Path.join()`](/reference/api/path/join) instead.
+
+## Signature
+
+```js
+Path path.combine(path other)
+```
+
+## Examples
+
+<Example caption="Example of the Path.combine() method">
+```js
+({ Point, points, Path, paths, part }) => {
+
+  points.A1 = new Point(0, 0)
+  points.A2 = new Point(60, 0)
+  points.B1 = new Point(0, 10)
+  points.B2 = new Point(60, 10)
+  points.C1 = new Point(0, 20)
+  points.C2 = new Point(60, 20)
+
+  paths.path1 = new Path()
+    .move(points.A1)
+    .line(points.A2)
+    .setClass("various")
+
+  paths.path2 = new Path()
+    .move(points.B1)
+    .line(points.B2)
+    .setClass("note")
+
+  paths.path3 = new Path()
+    .move(points.C1)
+    .line(points.C2)
+    .setClass("canvas")
+
+  paths.combo = paths.path1
+    .combine(paths.path2, paths.path3)
+    .setClass("lining dotted")
+
+  return part
+}
+```
+</Example>
+
+
+## Notes
+
+`Path.combine()` method is _variadic_, so you can pass multiple paths to join

markdown/dev/reference/api/path/join/en.md

@@ -2,7 +2,11 @@
 title: Path.join()
 ---
 
-The `Path.join()` method joins this path with another path.
+The `Path.join()` method joins this path with one or more other paths.
+
+Any gaps in the path (caused by move operations) will be filled-in with a line.
+If that's not what you want, you should use
+[`Path.combine()`](/reference/api/path/combine) instead.
 
 
 ## Signature
@@ -17,24 +21,30 @@ Path path.join(path other)
 ```js
 ({ Point, points, Path, paths, part }) => {
 
-  points.A = new Point(45, 60)
-  points.B = new Point(10, 30)
-  points.BCp2 = new Point(40, 20)
-  points.C = new Point(90, 30)
-  points.CCp1 = new Point(50, -30)
+  points.A1 = new Point(0, 0)
+  points.A2 = new Point(60, 0)
+  points.B1 = new Point(0, 10)
+  points.B2 = new Point(60, 10)
+  points.C1 = new Point(0, 20)
+  points.C2 = new Point(60, 20)
 
   paths.path1 = new Path()
-    .move(points.A)
-    .line(points.B)
+    .move(points.A1)
+    .line(points.A2)
     .setClass("various")
 
   paths.path2 = new Path()
-    .move(points.B)
-    .curve(points.BCp2, points.CCp1, points.C)
+    .move(points.B1)
+    .line(points.B2)
     .setClass("note")
 
+  paths.path3 = new Path()
+    .move(points.C1)
+    .line(points.C2)
+    .setClass("canvas")
+
   paths.joint = paths.path1
-    .join(paths.path2)
+    .join(paths.path2, paths.path3)
     .setClass("lining dotted")
 
   return part
@@ -45,4 +55,5 @@ Path path.join(path other)
 
 ## Notes
 
-You cannot join a closed path to another path
+- `Path.join()` is _variadic_, so you can pass multiple paths to join
+- You cannot join a closed path to another path

markdown/dev/reference/api/path/length/en.md

@@ -7,50 +7,43 @@ The `Path.length()` method returns the length of the path.
 ## Signature
 
 ```js
-float path.length()
+float path.length(bool withMoves = false)
 ```
 
 ## Example
 
 <Example caption="Example of the Path.length() method">
 ```js
-({ Point, points, Path, paths, macro, utils, units, part }) => {
+({ Point, points, Path, paths, units, part }) => {
 
-  points.A = new Point(45, 60)
-  points.B = new Point(10, 30)
-  points.BCp2 = new Point(40, 20)
-  points.C = new Point(90, 30)
-  points.CCp1 = new Point(50, -30)
+  points.A1 = new Point(0, 0)
+  points.A2 = new Point(160, 0)
+  points.B1 = new Point(0, 10)
+  points.B2 = new Point(160, 10)
+  points.C1 = new Point(0, 20)
+  points.C2 = new Point(160, 20)
 
-  paths.AB = new Path()
-    .move(points.A)
-    .line(points.B)
+  paths.path1 = new Path()
+    .move(points.A1)
+    .line(points.A2)
+    .move(points.B1)
+    .line(points.B2)
+    .move(points.C1)
+    .line(points.C2)
+    .setClass("various")
 
-  paths.BC = new Path()
-    .move(points.B)
-    .curve(points.BCp2, points.CCp1, points.C)
+  points.label1 = new Point(25, 8).addText('Total length = ' + units(paths.path1.length()))
+  points.label2 = new Point(25, 18).addText('Total length with moves = ' + units(paths.path1.length(true)))
 
-  const lengthABC = paths.AB.length() + paths.BC.length()
-
-  macro("pd", {
-     path: new Path().move(points.B).line(points.A),
-     d: 10
-   })
-
-   macro("pd", {
-     path: new Path().move(points.B).curve(points.BCp2, points.CCp1, points.C),
-     d: -10
-   })
-
-  points.label = new Point(25, 40)
-    .addText('Total length = ' + units(lengthABC))
-
-  // Set a path to prevent clipping
-  paths.noclip = new Path()
-    .move(new Point(10, -15))
-    .move(new Point(90, 60))
 
   return part
 }
 ```
 </Example>
+
+## Notes
+
+By default, `Path.length()` will measure the combined length of all drawing operations in the Path, but skip
+over gaps in the path (caused by move operations). 
+If you want the full length of the Path, including move operations, pass `true` to `Path.length()`.
+