From 88914324fe964ecc13768800d0d7e40c507d7b93 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Wed, 4 Oct 2023 15:34:40 +0200 Subject: [PATCH] Improve plugin docs Fixes #2309 --- crates/typst/src/eval/plugin.rs | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/crates/typst/src/eval/plugin.rs b/crates/typst/src/eval/plugin.rs index af7810892..45fc26599 100644 --- a/crates/typst/src/eval/plugin.rs +++ b/crates/typst/src/eval/plugin.rs @@ -12,9 +12,6 @@ use crate::World; /// A WebAssembly plugin. /// -/// This is **advanced functionality** and not to be confused with -/// [Typst packages]($scripting/#packages). -/// /// Typst is capable of interfacing with plugins compiled to WebAssembly. Plugin /// functions may accept multiple [byte buffers]($bytes) as arguments and return /// a single byte buffer. They should typically be wrapped in idiomatic Typst @@ -30,6 +27,20 @@ use crate::World; /// directly work with Typst. You will either need to compile to a different /// target or [stub all functions](https://github.com/astrale-sharp/wasm-minimal-protocol/blob/master/wasi-stub). /// +/// # Plugins and Packages +/// Plugins are distributed as packages. A package can make use of a plugin +/// simply by including a WebAssembly file and loading it. Because the +/// byte-based plugin interface is quite low-level, plugins are typically +/// exposed through wrapper functions, that also live in the same package. +/// +/// # Purity +/// Plugin functions must be pure: Given the same arguments, they must always +/// return the same value. The reason for this is that Typst functions must be +/// pure (which is quite fundamental to the language design) and, since Typst +/// function can call plugin functions, this requirement is inherited. In +/// particular, if a plugin function is called twice with the same arguments, +/// Typst might cache the results and call your function only once. +/// /// # Example /// ```example /// #let myplugin = plugin("hello.wasm")