tenrose

A simple Penrose binding for Typst using the WebAssembly plugin system.

This is heavily inspired by the equivalent for graphviz, diagraph.

Usage

Basic usage

This plugin is quite simple to use, you just need to import it:

TODO

#import "@preview/diagraph:0.2.2": *

You can render a Graphviz Dot string to a SVG image using the render function:

#render("digraph { a -> b }")

Alternatively, you can use raw-render to pass a raw instead of a string:

#raw-render(
  ```dot
  digraph {
    a -> b
  }
  ```
)

You can see an example of this in examples/.

For more information about the Graphviz Dot language, you can check the official documentation.

Arguments

render and raw-render accept multiple arguments that help you customize your graphs.

• engine (str) is the name of the engine to generate the graph with. Available engines are circo, dot, fdp, neato, nop, nop1, nop2, osage, patchwork, sfdp, and twopi. Defaults to "dot".

• width and height (length or auto) are the dimensions of the image to display. If set to auto (the default), will be the dimensions of the generated SVG. If a length, cannot be expressed in em.

• clip (bool) determines whether to hide parts of the graph that extend beyond its frame. Defaults to true.

• background (none or color or gradient) describes how to fill the background. If set to none (the default), the background will be transparent.

• labels (dict) is a list of labels to use to override the defaults labels. This is discussed in depth in the next section. Defaults to (:).

Labels

By default, all node labels are rendered by Typst. If a node has no explicitly set label (using the [label="..."] syntax), its name is used as its label, and interpreted as math if possible. This means a node named n_0 will render as 𝑛₀.

If you want a node label to contain a more complex mathematical equation, or more complex markup, you can use the labels argument: pass a dictionary that maps node names to Typst content. Each node with a name within the dictionary will have its label overridden by the corresponding content.

#raw-render(
  ```
  digraph {
    rankdir=LR
    node[shape=circle]
    Hmm -> a_0
    Hmm -> big
    a_0 -> "a'" -> big [style="dashed"]
    big -> sum
  }
  ```,
  labels: (:
    big: [_some_#text(2em)[ big ]*text*],
    sum: $ sum_(i=0)^n 1/i $,
  ),
)

See examples/ for the rendered graph.

Build

This project was built with emscripten 3.1.46. Apart from that, you just need to run make wasm to build the wasm file. All libraries are downloaded and built automatically to get the right version that works.

There are also some other make commands:

• make link: Link the project to the typst plugin folder
• make clean: Clean the build folder and the link
• make clean-link: Only clean the link
• make compile_database: Generate the compile_commands.json file
• make module: It copy the files needed to run the plugin in a folder called graphviz in the current directory
• make wasi-stub: Build the wasi stub executable, it require a rust toolchain properly configured

Wasi stub

Somme functions need to be stubbed to work with the webassembly plugin system. The wasi-stub executable is a spetial one fitting the needs of the typst plugin system. You can find the source code here. It is important to use this one as the default subbed functions are not the same and the makefile is suited for this one.

License

This project is licensed under the MIT License - see the LICENSE file for details

Changelog

0.2.2

• Fix an alignment issue
• Added a better mathematic formula recognition for node labels

0.2.1

• Added support for relative lenghts in the width and height arguments
• Fix various bugs

0.2.0

• Node labels are now handled by Typst

0.1.2

• Graphs are now scaled to make the graph text size match the document text size

0.1.1

• Remove the raw-render-rule show rule because it doesn't allow use of custom font and the render / raw-render functions are more flexible
• Add the background parameter to the render and raw-render typst functions and default it to transparent instead of white
• Add center attribute to draw graph in the center of the svg in the render c function

0.1.0

Initial working version