Re-Add Function Documentation

CHANGES.md

@@ -7,6 +7,7 @@
 - **BREAKING** Rotation direction changed to CCW
 - **BREAKING** Removed the `shadow` function
 - **BREAKING** Changed the behaviour of `mark`
+- **BREAKING** Changed the behaviour of `translate` by changing the transformation order, changed arguments of `scale` and `translate`
 - Content padding has been improved to be configurable per side
 - Groups support same padding options as content
 - Mark offsetting has been fixed and improved

doc/style.typ

@@ -8,7 +8,7 @@
     #heading(fn.name, level: style-args.first-heading-level + 1)
     #label(style-args.label-prefix + fn.name + "()")
   ]
-  let description  = if is.sequence(fn.description) {
+  let description = if is.sequence(fn.description) {
     fn.description.children
   } else {
     (fn.description,)

manual.typ

@@ -832,8 +832,8 @@ my-star((0,6), inner-radius: .3)
 = Internals
 == Context
 
-The state of the canvas is encoded in its context object. Elements or other
-draw calls may return a modified context element to the canvas to change its
+The state of the canvas is encoded in its context dictionary. Elements or other
+draw calls may return a modified context to the canvas to change its
 state, e.g. modifying the transformating matrix, adding a group or setting a style.
 
 ```example
@@ -847,7 +847,7 @@ get-ctx(ctx => {
 
 Each CeTZ element (`line`, `bezier`, `circle`, ...) returns an array of
 functions for drawing to the canvas. Such function takes the canvas'
-context object and must return an dictionary of the following keys:
+context and must return an dictionary of the following keys:
 - `ctx` (required): The (modified) canvas context object
 - `drawables`: List of drawables to render to the canvas
 - `anchors`: A function of the form `(<anchor-identifier>) => <vector>`

src/canvas.typ

@@ -12,7 +12,7 @@
 
 /// Set up a Canvas for drawing
 ///
-/// - length (length,ratio): Used to specify what 1 coordinate unit is. If given a ration, that ratio is
+/// - length (length,ratio): Used to specify what 1 coordinate unit is. If given a ratio, that ratio is
 ///   relative to the containing elements width!
 /// - body (none,array,element): A code block in which functions from `draw.typ` have been called.
 /// - background (none,color): A color to be used for the background of the canvas.

src/coordinate.typ

@@ -307,7 +307,7 @@
   return t
 }
 
-/// Resolve a list of coordinates to a absolute vectors
+/// Resolve a list of coordinates to absolute vectors
 ///
 /// #example(```
 /// line((0,0), (1,1), name: "l")

src/draw/grouping.typ

@@ -13,7 +13,8 @@
 
 #import "transformations.typ": move-to
 
-/// Calculates the intersections between multiple paths and create one anchor per intersection point.
+/// Calculates the intersections between multiple paths and creates one anchor
+/// per intersection point.
 ///
 /// All resulting anchors will be named numerically, starting at 0.
 /// i.e., a call `intersections("a", ...)` will generate the anchors

src/draw/transformations.typ

@@ -40,7 +40,9 @@
 /// circle((0,0))
 /// ```)
 ///
-/// - ..angles (angle): A single angle as a positional argument to rotate on the z-axis by. Named arguments of `x`, `y` or `z` can be given to rotate on their respective axis. You can give named arguments of `yaw`, `pitch` or `roll` to TODO
+/// - ..angles (angle): A single angle as a positional argument to rotate on the z-axis by.
+///   Named arguments of `x`, `y` or `z` can be given to rotate on their respective axis.
+///   You can give named arguments of `yaw`, `pitch` or `roll`, too.
 #let rotate(..angles) = {
   assert(angles.pos().len() == 1 or angles.named().len() > 0,
     message: "Rotate takes a single z-angle or angles " +
@@ -75,63 +77,92 @@
 ///
 /// #example(```
 /// // Outer rect
-/// rect((0,0), (2,2))
+/// rect((0, 0), (2, 2))
 /// // Inner rect
-/// translate((.5,.5,0))
-/// rect((0,0), (1,1))
+/// translate(x: .5, y: .5)
+/// rect((0, 0), (1, 1))
 /// ```)
 ///
-/// - vec (vector, dictionary): The vector to translate by. A dictionary can be given instead with optional keys `x`, `y` and `z` to translate in the relevant axis.
-/// - pre (bool): #box[Specify matrix multiplication order
-///                   - false: `World = World * Translate`
-///                   - true:  `World = Translate * World`]
-#let translate(vec, pre: true) = {
+/// - ..args (vector, float, length): A single vector or any combination of the named arguments `x`, `y` and `z` to translate by.
+///   A translation matrix with the given offsets gets multiplied with the current transformation depending on the value of `pre`.
+/// - pre (bool): Specify matrix multiplication order
+///   - false: `World = World * Translate`
+///   - true:  `World = Translate * World`
+#let translate(..args, pre: false) = {
+  assert((args.pos().len() == 1 and args.named() == (:)) or
+         (args.pos() == () and args.named() != (:)),
+    message: "Expected a single positional argument or one or more named arguments, got: " + repr(args))
+
+  let pos = args.pos()
+  let named = args.named()
+
+  let vec = if named != (:) {
+    (named.at("x", default: 0), named.at("y", default: 0), named.at("z", default: 0))
+  } else {
+    vector.as-vec(pos.at(0), init: (0, 0, 0))
+  }
+
   (ctx => {
-    let (x, y, z) = if type(vec) == "dictionary" {
-      (
-        vec.at("x", default: 0),
-        vec.at("y", default: 0),
-        vec.at("z", default: 0),
-      )
-    } else if type(vec) == "array" {
-      vec
-      if vec.len() <= 2 {
-        (0,)
-      }
+    // Allow translating by length values
+    let vec = vec.map(v => if type(v) == length {
+      util.resolve-number(ctx, v)
     } else {
-      panic("Invalid format '" + repr(vec) + "'")
-    }
-
-
-    let transforms = (matrix.transform-translate(x, -y, z), ctx.transform)
-    if not pre {
-      transforms = transforms.rev()
+      v
+    })
+
+    let t = matrix.transform-translate(..vec)
+    if pre {
+      ctx.transform = matrix.mul-mat(t, ctx.transform)
+    } else {
+      ctx.transform = matrix.mul-mat(ctx.transform, t)
     }
-    ctx.transform = matrix.mul-mat(..transforms)
-
     return (ctx: ctx)
   },)
 }
 
 /// Scales the transformation matrix by the given factor(s).
 ///
 /// #example(```
-/// // Scale x-axis
-/// scale((x: 1.8))
+/// // Scale the y-axis
+/// scale(y: 50%)
 /// circle((0,0))
 /// ```)
 ///
-/// - factor (float,dictionary): A float to scale the transformation matrix by. A dictionary with optional keys `x`, `y` and `z` can also be given to scale in the respective directions.
-#let scale(factor) = {
-  (
-    ctx => {
-      ctx.transform = matrix.mul-mat(ctx.transform, matrix.transform-scale(factor))
-      return (ctx: ctx)
-    },
-  )
+/// - ..args (float, ratio): A single value to scale the transformation matrix by or per axis
+///   scaling factors. Accepts a single float or ratio value or any combination of the named arguments
+///   `x`, `y` and `z` to set per axis scaling factors. A ratio of 100% is the same as the value $1$.
+#let scale(..args) = {
+  assert((args.pos().len() == 1 and args.named() == (:)) or
+         (args.pos() == () and args.named() != (:)),
+    message: "Expected a single positional argument or one or more named arguments, got: " + repr(args))
+
+  let pos = args.pos()
+  let named = args.named()
+
+  let vec = if args.named() != (:) {
+    (named.at("x", default: 1), named.at("y", default: 1), named.at("z", default: 1))
+  } else if type(pos.at(0)) == array {
+    vector.as-vec(pos, init: (1, 1, 1))
+  } else {
+    let factor = pos.at(0)
+    (factor, factor, factor)
+  }
+
+  // Allow scaling using ratio values
+  vec = vec.map(v => if type(v) == ratio {
+    v / 100%
+  } else {
+    v
+  })
+
+  (ctx => {
+    ctx.transform = matrix.mul-mat(ctx.transform, matrix.transform-scale(vec))
+    return (ctx: ctx)
+  },)
 }
 
-/// Sets the given position as the origin
+/// Sets the given position as the new origin `(0, 0, 0)`
+///
 /// #example(```
 /// // Outer rect
 /// rect((0,0), (2,2), name: "r")
@@ -196,20 +227,21 @@
     let bounds = vector.as-vec(bounds, init: (1, 1, 1))
 
     let (ctx, from, to) = coordinate.resolve(ctx, from, to)
-
-    let (fx, fy, fz, tx, ty, tz) = from + to
+    let (fx, fy, fz) = from
+    let (tx, ty, tz) = to
 
     // Compute scaling
-    let (sx, sy, sz) = vector.sub((tx, ty, tz), (fx, fy, fz)).enumerate().map(((i, v)) => if bounds.at(i) == 0 {
+    let (sx, sy, sz) = vector.sub((tx, ty, tz),
+                                  (fx, fy, fz)).enumerate().map(((i, v)) => if bounds.at(i) == 0 {
       0
     } else {
       v / bounds.at(i)
     })
 
-    ctx.transform = matrix.mul-mat(ctx.transform, matrix.mul-mat(
-      matrix.transform-translate(fx, fy, fz),
-      matrix.transform-scale((x: sx, y: sy, z: sz)),
-    ))
+    ctx.transform = matrix.mul-mat(ctx.transform,
+      matrix.transform-translate(fx, fy, fz))
+    ctx.transform = matrix.mul-mat(ctx.transform,
+      matrix.transform-scale((sx, sy, sz)))
     return (ctx: ctx)
   },)
 }

src/lib/axes.typ

@@ -260,7 +260,7 @@
       bounds: (x.max - x.min,
                y.max - y.min,
                0))
-    draw.translate((-x.min, y.min, 0), pre: false)
+    draw.translate((-x.min, -y.min))
     body
   })
 }

src/lib/decorations.typ

@@ -84,25 +84,25 @@
 
     let pointiness = style.pointiness
     assert(
-      type(pointiness) in (int, float)
-        and pointiness >= 0 and pointiness <= 1
-      or type(pointiness) == ratio
-        and pointiness >= 0% and pointiness <= 100%
-      or type(pointiness) == angle
-        and pointiness >= 0deg and pointiness <= 90deg,
+      (type(pointiness) in (int, float)
+        and pointiness >= 0 and pointiness <= 1)
+      or (type(pointiness) == ratio
+        and pointiness >= 0% and pointiness <= 100%)
+      or (type(pointiness) == angle
+        and pointiness >= 0deg and pointiness <= 90deg),
       message: "pointiness must be a factor between 0 and 1 or an angle between 0deg and 90deg, got " + repr(pointiness),
     )
     let pointiness = if type(pointiness) == angle { pointiness } else { pointiness * 90deg }
 
     let outer-pointiness = style.outer-pointiness
     assert(
       outer-pointiness == auto
-      or type(outer-pointiness) in (int, float)
-        and outer-pointiness >= 0 and outer-pointiness <= 1
-      or type(outer-pointiness) == ratio
+      or (type(outer-pointiness) in (int, float)
+        and outer-pointiness >= 0 and outer-pointiness <= 1)
+      or (type(outer-pointiness) == ratio)
         and outer-pointiness >= 0% and outer-pointiness <= 100%
-      or type(outer-pointiness) == angle
-        and outer-pointiness >= 0deg and outer-pointiness <= 90deg,
+      or (type(outer-pointiness) == angle
+        and outer-pointiness >= 0deg and outer-pointiness <= 90deg),
       message: "outer-pointiness must be a factor between 0 and 1 or an angle between 0deg and 90deg or auto, got " + repr(outer-pointiness),
     )
     let outer-pointiness = if outer-pointiness == auto {
@@ -272,10 +272,10 @@
 
     let aspect = style.aspect
     assert(
-      type(aspect) == ratio
-        and aspect >= 0% and aspect <= 100%
-      or type(aspect) == (int, float)
-        and aspect >= 0 and aspect <= 1,
+      (type(aspect) == ratio
+        and aspect >= 0% and aspect <= 100%)
+      or (type(aspect) in (int, float)
+        and aspect >= 0 and aspect <= 1),
       message: "aspect must be a ratio between 0% and 100%, got " + repr(aspect),
     )
     if type(aspect) == ratio { aspect /= 100% }

src/lib/plot.typ

@@ -52,9 +52,9 @@
 /// #show-parameter-block("min", ("auto", "float"), default: "auto", [
 ///   Axis lower domain value. If this is set greater than than `max`, the axis' direction is swapped])
 /// #show-parameter-block("max", ("auto", "float"), default: "auto", [
-///   Axis upper domain value. If this is set little than than `min`, the axis' direction is swapped])
+///   Axis upper domain value. If this is set to a lower value than `min`, the axis' direction is swapped])
 /// #show-parameter-block("equal", ("string"), default: "none", [
-///   Set the axis domain to keep a fixed aspect ration by multiplying the other axis domain by the plots aspect ratio,
+///   Set the axis domain to keep a fixed aspect ratio by multiplying the other axis domain by the plots aspect ratio,
 ///   depending on the other axis orientation (see `horizontal`).
 ///   This can be useful to force one axis to grow or shrink with another one.
 ///   You can only "lock" two axes of different orientations.
@@ -79,8 +79,8 @@
 /// #show-parameter-block("minor-tick-step", ("none", "float"), default: "none", [
 ///   Like `tick-step`, but for minor tick marks. In contrast to ticks, minor ticks do not have labels.])
 /// #show-parameter-block("ticks", ("none", "array"), default: "none", [
-///   A List o0 custom tick marks to additionally draw along the axis. They can be passed as
-///   an array of `<floa>` values or an array of `(<float>, <content>)` tuples for
+///   A List of custom tick marks to additionally draw along the axis. They can be passed as
+///   an array of `<float>` values or an array of `(<float>, <content>)` tuples for
 ///   setting custom tick mark labels per mark.
 ///
 ///   #example(```
@@ -96,7 +96,7 @@
 ///
 ///   Examples: `(1, 2, 3)` or `((1, [One]), (2, [Two]), (3, [Three]))`])
 /// #show-parameter-block("format", ("none", "string", "function"), default: "float", [
-///   How to format the tick label: You can give a function that takes a `<float>` and returnu
+///   How to format the tick label: You can give a function that takes a `<float>` and return
 ///   `<content>` to use as the tick label. You can also give one of the predefined options:
 ///   / float: Floating point formatting rounded to two digits after the point (see `decimals`)
 ///   / sci: Scientific formatting with $times 10^n$ used as exponet syntax
@@ -134,7 +134,7 @@
 /// ])
 ///
 /// - body (body): Calls of `plot.add` or `plot.add-*` commands. Note that normal drawing
-///   commands like `line` or `rect` are not allowed insides the plots body, instead wrap
+///   commands like `line` or `rect` are not allowed inside the plots body, instead wrap
 ///   them in `plot.add-annotation`, which lets you select the axes used for drawing.
 /// - size (array): Plot size tuple of `(<width>, <height>)` in canvas units.
 ///   This is the plots inner plotting size without axes and labels.
@@ -427,8 +427,9 @@
 ///   Both values can have the special values "min" and
 ///   "max", which resolve to the axis min/max value.
 ///   Position is in axis space defined by the axes passed to `axes`.
-/// - axes (tuple): Name of the axes to use `("x", "y")`, note that both
-///   axes must exist, as `add-anchors` does not create axes on demand.
+/// - axes (tuple): Name of the axes to use `("x", "y")` as coordinate
+///   system for `position`. Note that both axes must be used,
+///   as `add-anchors` does not create them on demand.
 #let add-anchor(name, position, axes: ("x", "y")) = {
   ((
     type: "anchor",

src/lib/plot/contour.typ

@@ -260,7 +260,7 @@
 ///   above z (z >= 0) or below z (z < 0) get plotted.
 ///   If you specify multiple z values, they get plotted in the order of specification.
 /// - x-domain (domain): X axis domain used if `data` is a function, that is the
-///   domain insides the function gets sampled.
+///   domain inside the function gets sampled.
 /// - y-domain (domain): Y axis domain used if `data` is a function, see `x-domain`.
 /// - x-samples (int): X axis domain samples (2 < n). Note that contour finding
 ///   can be quite slow. Using a big sample count can improve accuracy but can

src/lib/plot/line.typ

@@ -192,7 +192,7 @@
 ///   graph. Uses the `mark` style key of `style` for drawing.
 /// - mark-size (float): Mark size in cavas units
 /// - data (array,function): Array of 2D data points (numeric) or a function
-///   of the form `x => y`, where `x` is a value insides `domain`
+///   of the form `x => y`, where `x` is a value in `domain`
 ///   and `y` must be numeric or a 2D vector (for parametric functions).
 ///   #example(```
 ///   import cetz.plot
@@ -270,8 +270,8 @@
   ),)
 }
 
-/// Add horizontal lines at one or more y-values. The lines start and end point
-/// is at its axis bounds.
+/// Add horizontal lines at one or more y-values. Every lines start and end points
+/// are at their axis bounds.
 ///
 /// #example(```
 /// cetz.plot.plot(size: (2,2), x-tick-step: none, y-tick-step: none, {
@@ -320,8 +320,8 @@
   ),)
 }
 
-/// Add vertical lines at one or more x-values. The lines start and end point
-/// is at its axis bounds.
+/// Add vertical lines at one or more x-values. Every lines start and end points
+/// are at their axis bounds.
 ///
 /// #example(```
 /// cetz.plot.plot(size: (2,2), x-tick-step: none, y-tick-step: none, {