How to correctly annotate plots?

[psads-git]

The following plot is created by the code below:

It is the labels and the arrows in red that I want to add to the plot. I have tried plot.annotate with content, but, unfortunately, always got errors.

Could you please help me?

#import "@local/cetz:0.2.0"

#align(center, 
  cetz.canvas({
    import cetz.plot
    import cetz.palette

    plot.plot(size: (5,5),
      x-tick-step: 2,
      x-minor-tick-step: 1,
      y-tick-step: 6,
      y-minor-tick-step: 1,
      axis-style: "school-book", {
      plot.add(domain: (-2.5, 2.5),
        x => (4-calc.pow(x, 2)),
        style: palette.tango-light)
      plot.add(domain: (-2.5, 2.5),
        x => (4-2*x),
        style: palette.tango-light)
      plot.add-fill-between(domain: (0, 2),
        x => (4-calc.pow(x, 2)),
        x => (4-2*x),
        style: palette.tango-light)
      plot.add(((0,4), (2,0)),
        mark: "o",
        mark-style: (stroke: none, fill: black),
        style: (stroke: none))
      
      })
  })
)

[psads-git]

After having struggled a bit, I was successful in producing the wanted plot, by using the code below:

#import "@local/cetz:0.2.0"

#align(center, 
  cetz.canvas({
    import cetz.plot
    import cetz.palette
    import cetz.draw: *

    plot.plot(size: (5,5),
      name: "plot",
      x-tick-step: 2,
      x-minor-tick-step: 1,
      y-tick-step: 6,
      y-minor-tick-step: 1,
      axis-style: "school-book", {
      plot.add(domain: (-2.5, 2.5),
        x => (4-calc.pow(x, 2)),
        style: palette.tango-light)
      plot.add(domain: (-2.5, 2.5),
        x => (4-2*x),
        style: palette.tango-light)
      plot.add-fill-between(domain: (0, 2),
        x => (4-calc.pow(x, 2)),
        x => (4-2*x),
        style: palette.tango-light)
      plot.add(((0,4), (2,0)),
        mark: "o",
        mark-style: (stroke: none, fill: black),
        style: (stroke: none))
      plot.add-anchor("pt1", (2,5))
      plot.add-anchor("pt2", (-2,5.5))
      plot.add-anchor("parab", (1, 4-calc.pow(1, 2)+0.2))
      plot.add-anchor("rline", (-1.5, 4-2*(-1.5)-0.2))

      })
    
    content("plot.pt1", [$y=4-2x^2$], anchor: "south", name: "prb")
    line("plot.parab", "prb", mark: (start: ">"))

    content("plot.pt2", [$y=4-2x$], anchor: "north", name: "curve2")
    line("plot.rline", "curve2", mark: (start: ">"))

  })
)

[johannes-wolf]

Anchors are the correct solution, I think.
Do you think there should be a better API for this? Maybe having a list of x values in plot.add to place anchors at? Why did plot.annotate not work?

A problem with plot.annotate is, that marks on lines get distorted because of the canvas' scaling.

[psads-git]

I would not suggest adding the API you mention for now, Johannes. It may confuse the newbies, as it involves a somewhat advanced concept: The concept of anchor.

From a strategic market point of view, CeTZ should be very easy to begin with, since it is a newcomer tool with well-established competitors. In this vein of thought, I would suggest creating a gallery of examples like this one that was created for TikZ:

https://texample.net//tikz/examples/

Furthermore, a set of introductory videos on YouTube would be most useful: At the moment, there is not a single video about CeTZ. (The extant videos on Typst are scarce and also mostly superficial.)