Use general 'note' command & extend documentation

[th1j5]

I use typst drafting as the typst equivalent of todonotes. I'm new to typst, which is why I struggled to get some equivalent functionality, but I think I managed: I'd like to propose to

1. add some extra examples in the documentation which show the usage of different variants of notes
2. add a general #note command, which can switch between the inline & margin variant, with a default to margin. (or if not, also add this to the documentation as an example of working with it...)

If you are ok with this, I can send a PR (when I find some time)

A note, defaulting to a margin note:

#let note(inline: false, ..kwargs) = {
    if inline {
        inline-note(..kwargs)
    } else {
        margin-note(..kwargs)
    }
}

An example of defining custom todo-commands:

#let todo-ballon = rect.with(inset: 0.3em, radius: 0.5em)
#let todo-unsure = note.with(
        stroke: maroon,
        rect  : todo-ballon.with(fill: maroon.lighten(70%)))
#let todo-add = note.with(
        stroke: blue,
        rect  : todo-ballon.with(fill: blue.lighten(60%)))
#let todo-change = note.with(...)

Usage:

#todo-add(inline: true)[Inline todo note, showing that I should add something...]
#todo-add[Todo note in the margin, showing that I should add something here...]

[ntjess]

Extra examples are welcome! Thank you for the consideration.

I am more hesitant to provide uniform access both to inline and margin notes, since each needs slightly different parameters (i.e. inline notes have a par-break option, and I am hoping in the future to have more margin-aware options for margin notes).

Since the code to provide this is so short, I'm also happy to merge an example that shows you can use a function like this if you need the unified API.

[th1j5]

Finding this complete example (with which I'm finally +- satisfied), motivates also my PR in #27 . My todo-notes have set rules to make the text smaller. For the colors of my todo-notes to be consistent in each usage (see usage in 1st post and here), the todo-ballon needs to be constructed this specific way. The documentation could be less 'misleading' if #27 is accepted, or otherwise documented.

If the set rules would be written like in the current documentation, then the background color is not applied in the text (see usage ⬇ ).

Complete example of #todo notes

#import "@preview/drafting:0.2.2": *
/*#set-page-properties() // whenever page is reconfigured
 * After importing, use this...
 */

#let note(inline: false, ..kwargs) = {
    if inline {
        inline-note(..kwargs)
    } else {
        margin-note(..kwargs)
    }
}
#let todo-ballon(..kwargs, content) = {
  /* The return value needs to be an 'element', such that the fields can
   * be accessed (aka todo-ballon.has("fill") is true). The 'set' rules
   * are thus applied inside the content of 'rect'.
   */
  rect(inset: 0.3em, radius: 0.5em, ..kwargs)[
      #set text(0.75em)
      #set par(leading:0.4em)
      #content
  ]
}

// Default todo
#let todo = note.with(rect: todo-ballon)
// Variations of todo
#let todo-unsure = todo.with(
        stroke: maroon,
        fill  : maroon.lighten(70%))
#let todo-add    = todo.with(
        stroke: blue,
        fill  : blue.lighten(60%))
#let todo-change = todo.with(
        stroke: red,
        fill  : red.lighten(50%))

Usage:

#todo-change(inline:true, par-break:false)[a part of a sentence, highlighted in the 'todo change' color, but only if todo-ballon was constructed the correct way]

About documenting this

As you can see, I use the general note command to provide a unified interface to certain todo commands, each with their own style. Of course, todo-change(inline:false, par-break: true) still doesn't mean anything, I'm not even sure if it errors or not. But the same style for a class of 'todo' notes is consistently applied, whether they are in the margin, inline or even inline without a par-break.

I'm not sure where to document this, so I'm not sure what else I can add personally.