mannot:0.2.0 (#1597)

packages/preview/mannot/0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ryuryu-ymj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/preview/mannot/0.2.0/README.md

@@ -0,0 +1,106 @@
+# Mannot
+A package for marking and annotating in math blocks in [Typst](https://typst.app/).
+
+A full documentation is [here](docs/doc.pdf).
+
+## Example
+```typst
+$
+markul(p_i, tag: #<p>)
+= markrect(
+exp(- marktc(beta, tag: #<beta>) marktc(E_i, tag: #<E>, color: #green)),
+tag: #<Boltzmann>, color: #blue,
+) / mark(sum_j exp(- beta E_j), tag: #<Z>)
+
+#annot(<p>, pos: left)[Probability of \ state $i$]
+#annot(<beta>, pos: top + left, yshift: 2em)[Inverse temperature]
+#annot(<E>, pos: top + right, yshift: 1em)[Energy]
+#annot(<Boltzmann>, pos: top + left)[Boltzmann factor]
+#annot(<Z>)[Partition function]
+$
+```
+
+![Example1](examples/showcase.svg)
+
+## Usage
+Import the package `mannot` on the top of your document:
+```typst
+#import "@preview/mannot:0.2.0": *
+```
+
+To define the target of an annotation within a math block,
+use the following marking functions:
+- `mark`: marks the content with highlighting;
+- `markrect`: marks the content with a rectangular box;
+- `markul`: marks the content with an underline;
+- `marktc`: marks the content and changes the text color.
+```typst
+$
+  mark(x, tag: #<t1>) + markrect(2y, tag: #<t2>)
+  + markul(z+1, tag: #<t3>) + marktc(C, tag: #<t4>)
+$
+```
+![Usage1](examples/usage1.svg)
+
+You can customize the marking color and other styles:
+```typst
+$
+  mark(x, tag: #<t1>, color: #purple)
+  + markrect(2y, tag: #<t2>, color: #red, padding: #.2em)
+  + markul(z+1, tag: #<t3>, stroke: #.1em)
+  + marktc(C, tag: #<t4>, color: #olive)
+$
+```
+![Usage2](examples/usage2.svg)
+
+You can also use marking functions solely for styling parts of a math block,
+without tags:
+```typst
+$
+  mark(x^2 +, color: #blue, radius: #20%)
+  f(markul(x^2 + 1, color: #red, stroke: #.1em))
+$
+```
+![Usage3](examples/usage3.svg)
+
+Once you have marked content with a tag,
+you can annotate it using the `annot` function within the same math block:
+```typst
+$
+  mark(x, tag: #<t1>, color: #purple)
+  + markrect(2y, tag: #<t2>, color: #red, padding: #.2em)
+  + markul(z+1, tag: #<t3>, stroke: #.1em)
+  + marktc(C, tag: #<t4>, color: #olive)
+
+  #annot(<t1>)[annotation]
+  #annot(<t4>)[another annotation]
+$
+```
+![Usage4](examples/usage4.svg)
+
+You can customize the position of the annotation and its vertical distance from the marked content,
+using the `pos` and `yshift` parameters of the `annot` function:
+```typst
+#v(3em)
+$
+  mark(x, tag: #<t1>, color: #purple)
+  + markrect(2y, tag: #<t2>, color: #red, padding: #.2em)
+  + markul(z+1, tag: #<t3>, stroke: #.1em)
+  + marktc(C, tag: #<t4>, color: #olive)
+
+  #annot(<t1>, pos: left)[Set pos \ to left.]
+  #annot(<t2>, pos: top, yshift: 1em)[Set pos to top, and yshift to 1em.]
+  #annot(<t3>, pos: right, yshift: 1em)[Set pos to right,\ and yshift to 1em.]
+  #annot(<t4>, pos: top + left, yshift: 3em)[Set pos to top+left,\ and yshift to 3em.]
+$
+#v(2em)
+```
+![Usage5](examples/usage5.svg)
+
+
+## Changelogs
+* v0.2.0:
+  - remove the `mannot-init` function;
+  - support placing underlay under the math content when marking;
+  - add marking functions: `markrect`, `markul`, `marktc`.
+* v0.1.0: first release.

packages/preview/mannot/0.2.0/docs/doc-template.typ

@@ -0,0 +1,28 @@
+#import "/src/lib.typ": *
+
+#let entrypoint = toml("/typst.toml").package.entrypoint
+#let usage = "#import \"/" + entrypoint + "\": *\n"
+
+#let example(source) = {
+  grid(
+    columns: (2fr, 1fr),
+    rows: auto,
+    align: center + horizon,
+    gutter: 5pt,
+    {
+      // set text(0.9em)
+      // raw(block: true, lang: "typst", source)
+      source
+    },
+    rect(
+      width: 100%,
+      inset: 10pt,
+      eval(usage + source.text, mode: "markup"),
+    ),
+  )
+}
+
+#let example-vstack(source) = {
+  eval(usage + source.text, mode: "markup")
+  source
+}

packages/preview/mannot/0.2.0/docs/doc.typ

@@ -0,0 +1,145 @@
+#import "@preview/tidy:0.4.0"
+#import "@preview/codly:1.0.0": *
+#import "/src/lib.typ": *
+#import "doc-template.typ": *
+
+#show link: underline
+
+#show: codly-init.with()
+#codly(lang-format: none)
+
+#set text(font: "Noto Serif", size: 10pt)
+#show raw.where(block: false): set text(font: "Noto Sans Mono")
+
+#let package-info = toml("/typst.toml")
+#let name = package-info.package.name
+#let version = package-info.package.version
+
+#text(2em, weight: "bold", name)
+#h(1em)
+#text(1.2em, "v" + version)
+
+
+A package for marking and annotating in math blocks in Typst.
+
+#outline(depth: 1, indent: auto)
+
+
+= Example
+#example-vstack(```typst
+#set text(12pt)
+#v(2em)
+$
+  markul(p_i, tag: #<p>)
+  = markrect(
+    exp(- marktc(beta, tag: #<beta>) marktc(E_i, tag: #<E>, color: #green)),
+    tag: #<Boltzmann>, color: #blue,
+  ) / mark(sum_j exp(- beta E_j), tag: #<Z>)
+
+  #annot(<p>, pos: left)[Probability of \ state $i$]
+  #annot(<beta>, pos: top + left, yshift: 2em)[Inverse temperature]
+  #annot(<E>, pos: top + right, yshift: 1em)[Energy]
+  #annot(<Boltzmann>, pos: top + left)[Boltzmann factor]
+  #annot(<Z>)[Partition function]
+$
+```)
+
+
+= Usage
+Import the package #raw(name) on the top of your document:
+#let usage-code = "#import \"@preview/" + name + ":" + version + "\": *"
+#raw(block: true, lang: "typst", usage-code)
+
+To define the target of an annotation within a math block,
+use the following marking functions:
+- `mark`: marks the content with highlighting;
+- `markrect`: marks the content with a rectangular box;
+- `markul`: marks the content with an underline;
+- `marktc`: marks the content and changes the text color.
+#example(```typst
+$
+mark(x, tag: #<t1>) + markrect(2y, tag: #<t2>)
++ markul(z+1, tag: #<t3>) + marktc(C, tag: #<t4>)
+$
+```)
+
+You can customize the marking color and other styles:
+#example(```typst
+$
+mark(x, tag: #<t1>, color: #purple)
++ markrect(2y, tag: #<t2>, color: #red, padding: #2pt)
++ markul(z+1, tag: #<t3>, stroke: #1pt)
++ marktc(C, tag: #<t4>, color: #olive)
+$
+```)
+
+You can also use marking functions solely for styling parts of a math block,
+without tags:
+#example(```typst
+$
+mark(x^2 +, color: #blue, radius: #20%)
+f(markul(x^2 + 1, color: #red, stroke: #2pt))
+$
+```)
+
+Once you have marked content with a tag,
+you can annotate it using the `annot` function within the same math block:
+#example(```typst
+$
+mark(x, tag: #<t1>, color: #purple)
++ markrect(2y, tag: #<t2>, color: #red, padding: #2pt)
++ markul(z+1, tag: #<t3>, stroke: #1pt)
++ marktc(C, tag: #<t4>, color: #olive)
+
+#annot(<t1>)[annotation]
+#annot(<t4>)[another annotation]
+$
+```)
+
+You can customize the position of the annotation and its vertical distance from the marked content,
+using the `pos` and `yshift` parameters of the `annot` function:
+#example(```typst
+#v(3em)
+$
+mark(x, tag: #<t1>, color: #purple)
++ markrect(2y, tag: #<t2>, color: #red, padding: #2pt)
++ markul(z+1, tag: #<t3>, stroke: #1pt)
++ marktc(C, tag: #<t4>, color: #olive)
+
+#annot(<t1>, pos: left)[Set pos \ to left.]
+#annot(<t2>, pos: top, yshift: 1em)[
+  Set pos to top, and yshift to 1em.
+]
+#annot(<t3>, pos: right, yshift: 1em)[
+  Set pos to right,\ and yshift to 1em.
+]
+#annot(<t4>, pos: top + left, yshift: 3em)[
+  Set pos to top+left,\ and yshift to 3em.
+]
+$
+#v(2em)
+```)
+
+
+= Limitations
+If you mark a inline math element containing linebreaks,
+its layout will be broken:
+#example(```typst
+$mark(x + x + x + x + x + x + x + x)$
+```)
+
+
+= API
+#{
+  import "/src/lib.typ"
+  import "tidy-style.typ"
+
+  let docs = (
+    tidy.parse-module(
+      read("/src/mark.typ") + read("/src/annot.typ"),
+      scope: (lib: lib),
+      preamble: "import lib: *\n",
+    )
+  )
+  tidy.show-module(docs, show-outline: true, sort-functions: none, style: tidy-style)
+}

packages/preview/mannot/0.2.0/docs/tidy-style.typ

@@ -0,0 +1,56 @@
+#import "@preview/tidy:0.4.0"
+#import tidy.utilities: *
+#import tidy.styles.default: *
+
+
+#let show-example(
+  code,
+  scope: (:),
+  preamble: "",
+  mode: auto,
+  inherited-scope: (:),
+  col-spacing: 5pt,
+  preview-inset: 10pt,
+  ..options,
+) = {
+  let displayed-code = code.text.split("\n").filter(x => not x.starts-with(">>>")).join("\n")
+  let executed-code = code.text.split("\n").map(x => x.trim(">>>", at: start)).join("\n")
+
+  let lang = if code.has("lang") { code.lang } else { auto }
+  if mode == auto {
+    if lang == "typ" { mode = "markup" } else if lang == "typc" { mode = "code" } else if lang == "typm" {
+      mode = "math"
+    } else if lang == auto { mode = "markup" }
+  }
+  if lang == auto {
+    if mode == "markup" { lang = "typ" }
+    if mode == "code" { lang = "typc" }
+    if mode == "math" { lang = "typm" }
+  }
+  if mode != "code" {
+    preamble = "#" + preamble
+  }
+  assert(
+    lang in ("typ", "typc", "typm"),
+    message: "Previewing code only supports the languages \"typ\", \"typc\", and \"typm\"",
+  )
+
+  grid(
+    columns: (2fr, 1fr),
+    rows: auto,
+    align: horizon,
+    gutter: col-spacing,
+    {
+      // set text(0.7em)
+      raw(displayed-code, lang: lang, block: true)
+    },
+    rect(
+      width: 100%,
+      inset: preview-inset,
+      {
+        set text(font: "Noto Serif")
+        eval(preamble + executed-code, mode: mode, scope: scope + inherited-scope)
+      },
+    ),
+  )
+}