Merge pull request 'v0.2.0: updates and minor fixes' (#4) from dev into main

Reviewed-on: #4

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [v0.2.0] - 2025-02-23
+- updated CeTZ to 0.3.2
+- updated to Typst 0.13.0
+- fixed missing bit index on dependencies
+- updated docs (Tidy, codelst -> codly)
+
+## [v0.1.0] - 2024-10-02
+- prepared for publication in Typst Universe
+
 ## [v0.0.2] - 2024-06-15
 ### Added
 - `width` parameter to `schema.render` for easier integration

README.md

@@ -31,14 +31,11 @@ It is based on the [homonymous Python script](https://git.kb28.ch/HEL/rivet/)
 *Click on the example image to jump to the code.*
 
 ## Usage
-For information, see the [manual](manual.pdf)
+For more information, see the [manual](manual.pdf)
 
-To use this package, simply import `schema` [src/lib.typ](src/lib.typ) and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+To use this package, simply import `schema` from [rivet](https://typst.app/universe/package/rivet) and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
 ```typ
-#import "src/lib.typ": schema
+#import "@preview/rivet:0.2.0": schema
 #let doc = schema.load("path/to/schema.yaml")
 #schema.render(doc)
 ```
-
-## Installing
-> TODO

docs/config.typ

@@ -1,7 +1,7 @@
 /// Creates a dictionary of all configuration parameters
 ///
 /// - default-font-family (str): The default font family
-/// - default font-size (length): The absolute default font size
+/// - default-font-size (length): The absolute default font size
 /// - italic-font-family (str): The italic font family (for value descriptions)
 /// - italic-font-size (length): The absolute italic font size
 /// - background (color): The diagram background color
@@ -15,7 +15,7 @@
 /// - dash-length (float): The length of individual dashes (for dashed lines)
 /// - dash-space (float): The space between two dashes (for dashed lines)
 /// - arrow-size (float): The size of arrow heads
-/// - margins (tuple[float]): TODO -> remove
+/// - margins (tuple): TODO -> remove
 /// - arrow-margin (float): The margin between arrows and the structures they link
 /// - values-gap (float): The gap between individual values
 /// - arrow-label-distance (float): The distance between arrows and their labels
@@ -55,9 +55,9 @@
 ) = {}
 
 /// Dark theme config
-/// - ..args (any): see #doc-ref("config.config")
+/// - ..args (any): see @@config()
 #let dark(..args) = {}
 
 /// Blueprint theme config
-/// - ..args (any): see #doc-ref("config.config")
+/// - ..args (any): see @@config()
 #let blueprint(..args) = {}

docs/examples.typ

@@ -1,4 +1,3 @@
-#import "@preview/cetz:0.2.2": draw
 #import "../src/lib.typ": schema
 #import "../src/util.typ"
 
@@ -14,7 +13,7 @@
       box(
         stroke: black + 1pt,
         radius: .5em,
-        fill: if fill {yellow.lighten(80%)} else {none},
+        fill: if fill {orange.lighten(95%)} else {none},
         if show-src {
           let src-block = align(left, raw(src, lang: "typc"))
           table(

docs/schema.typ

@@ -2,15 +2,18 @@
 /// This function returns a dictionary of structures
 /// 
 /// Supported formats: #schema.valid-extensions.map(e => raw("." + e)).join(", ")
-/// - path-or-schema (str, raw, dictionary): If it is a string, defines the path to load. \
-///   If it is a raw block, its content is directly parsed (the block's language will define the format to use) \
-///   If it is a dictionary, it directly defines the schema structure
+/// - path-or-schema (str, raw, dictionary):
+///   #list(
+///     [If it is a string, defines the path to load.\ #emoji.warning Warning: this will only work if this package is part of your project, as packages installed in the `@local` or `@preview` namespace cannot access project files],
+///     [If it is a raw block, its content is directly parsed (the block's language will define the format to use)],
+///     [If it is a dictionary, it directly defines the schema structure]
+///   )
 /// -> dictionary
 #let load(path-or-schema) = {}
 
 /// Renders the given schema
 /// This functions
-/// - schema (dictionary): A schema dictionary, as returned by #doc-ref("schema.load")
+/// - schema (dictionary): A schema dictionary, as returned by @@load()
 /// - config (auto, dictionary): The configuration parameters, as returned by #doc-ref("config.config")
 /// - width (ratio, length): The width of the generated figure
 #let render(schema, config: auto, width: 100%) = {}

gallery.bash

@@ -1,40 +0,0 @@
-#!/bin/bash
-
-PDFS=false
-
-while getopts "p" flag
-do
-    case "${flag}" in
-        p) PDFS=true;;
-    esac
-done
-
-echo "Generating gallery images"
-
-set -- ./gallery/example*.typ
-cnt="$#"
-i=1
-for f
-do
-    f2="${f/typ/png}"
-    echo "($i/$cnt) $f -> $f2"
-    typst c --root ./ "$f" "$f2"
-    i=$((i+1))
-done
-
-if [ "$PDFS" = true ]
-then
-    echo
-    echo "Generating gallery PDFs"
-
-    set -- ./gallery/*.typ
-    cnt="$#"
-    i=1
-    for f
-    do
-        f2="${f/typ/pdf}"
-        echo "($i/$cnt) $f -> $f2"
-        typst c --root ./ "$f" "$f2"
-        i=$((i+1))
-    done
-fi

justfile

@@ -0,0 +1,12 @@
+# Local Variables:
+# mode: makefile
+# End:
+gallery_dir := "./gallery"
+set shell := ["bash", "-uc"]
+
+manual:
+  typst c manual.typ manual.pdf
+
+gallery:
+  for f in "{{gallery_dir}}"/*.typ; do typst c --root . "$f" "${f/typ/pdf}"; done
+  for f in "{{gallery_dir}}"/example*.typ; do typst c --root . "$f" "${f/typ/png}"; done

manual.typ

@@ -1,22 +1,24 @@
-#import "@preview/tidy:0.3.0"
-#import "@preview/codelst:2.0.1": sourcecode
-#import "@preview/showybox:2.0.1": showybox
+#import "@preview/tidy:0.4.1"
+#import "@preview/codly:1.2.0": codly-init, codly
+#import "@preview/codly-languages:0.1.7": codly-languages
+#import "@preview/showybox:2.0.4": showybox
 #import "src/lib.typ"
 #import "src/schema.typ"
 #import "docs/examples.typ"
 
+#show: codly-init
+
+#codly(languages: codly-languages)
+
 #set heading(numbering: (..num) => if num.pos().len() < 4 {
   numbering("1.1", ..num)
 })
-#{
-  outline(indent: true, depth: 3)
-}
 
 #set page(numbering: "1/1", header: align(right)[rivet #sym.dash.em v#lib.version])
 
 #let doc-ref(target, full: false, var: false) = {
   let (module, func) = target.split(".")
-  let label-name = module + func
+  let label-name = module + "-" + func
   let display-name = func
   if full {
     display-name = target
@@ -25,7 +27,7 @@
     label-name += "()"
     display-name += "()"
   }
-  link(label(label-name))[#display-name]
+  link(label(label-name), raw(display-name))
 }
 
 #let note(it) = showybox(
@@ -43,6 +45,37 @@
 
 #show link: set text(blue)
 
+#let sch = schema.load(```yaml
+structures:
+  main:
+    bits: 5
+    ranges:
+      4:
+        name: R
+        description: Register
+      3:
+        name: I
+        description: Instruction
+      2:
+        name: V
+        description: Visualizer
+      1:
+        name: E
+        description: Explainer
+      0:
+        name: T
+        description: Tool
+```)
+#align(center, schema.render(sch, width: 50%, config: lib.config.config(left-labels: true)))
+#v(1fr)
+#box(
+  width: 100%,
+  stroke: black,
+  inset: 1em,
+  outline(indent: auto, depth: 3)
+)
+#pagebreak(weak: true)
+
 = Introduction
 
 This package provides a way to make beautiful register diagrams using the CeTZ package. It can be used to document Assembly instructions or binary registers
@@ -53,7 +86,7 @@ This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python s
 
 Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
 #pad(left: 1em)[```typ
-#import "src/lib.typ": schema
+#import "@preview/rivet:0.1.0": schema
 #let doc = schema.load("path/to/schema.yaml")
 #schema.render(doc)
 ```]
@@ -70,7 +103,7 @@ A schema contains a dictionary of structures. The must be at least one defined s
 
 It can also optionnaly contain a "colors" dictionary. More details about this in #link(<format-colors>)[Colors]
 
-#sourcecode[```json
+```json
 {
   "structures": {
     "main": {
@@ -85,7 +118,7 @@ It can also optionnaly contain a "colors" dictionary. More details about this in
     ...
   }
 }
-```]
+```
 
 #pagebreak(weak: true)
 
@@ -95,7 +128,7 @@ A structure has a given number of bits and one or multiple ranges. Each range of
 
 The range name (or key) defines the left- and rightmost bits (e.g. `7-4` goes from bit 7 down to bit 4). Bits are displayed in big-endian, i.e. the leftmost bit has the highest value.
 
-#sourcecode[```json
+```json
 "main": {
   "bits": 8,
   "ranges": {
@@ -113,7 +146,7 @@ The range name (or key) defines the left- and rightmost bits (e.g. `7-4` goes fr
     }
   }
 }
-```]
+```
 
 == Range <format-range>
 
@@ -125,7 +158,7 @@ For values depending on other ranges, see #link(<format-dependencies>)[Dependenc
   In YAML, make sure to wrap values in quotes because some values can be interpreted as octal notation (e.g. 010 #sym.arrow.r 8)
 ]
 
-#sourcecode[```json
+```json
 "3-2": {
   "name": "op",
   "description": "Logical operation",
@@ -136,7 +169,7 @@ For values depending on other ranges, see #link(<format-dependencies>)[Dependenc
     "11": "NAND"
   }
 }
-```]
+```
 
 #pagebreak(weak: true)
 
@@ -146,7 +179,7 @@ The structure of one range may depend on the value of another. To represent this
 
 Then, in its values, indicate which structure to use. A description can also be added (displayed above the horizontal dependency arrow)
 
-#sourcecode[```json
+```json
 "7-4": {
   ...
   "depends-on": "0",
@@ -161,11 +194,11 @@ Then, in its values, indicate which structure to use. A description can also be
     }
   }
 }
-```]
+```
 
 Finally, add the sub-structures to the structure dictionary:
 
-#sourcecode[```json
+```json
 {
   "structures": {
     "main": {
@@ -182,7 +215,7 @@ Finally, add the sub-structures to the structure dictionary:
     ...
   }
 }
-```]
+```
 
 #pagebreak(weak: true)
 
@@ -190,7 +223,7 @@ Finally, add the sub-structures to the structure dictionary:
 
 You may want to highlight some ranges to make your diagram more readable. For this, you can use colors. Colors may be defined in a separate dictionary, at the same level as the "structures" dictionary:
 
-#sourcecode[```json
+```json
 {
   "structures": {
     ...
@@ -199,11 +232,11 @@ You may want to highlight some ranges to make your diagram more readable. For th
     ...
   }
 }
-```]
+```
 
 It can contain color definitions for any number of ranges. For each range, you may then define a dictionary mapping bit ranges to a particular color:
 
-#sourcecode[```json
+```json
 "colors": {
   "main": {
     "31-28": "#ABCDEF",
@@ -213,7 +246,7 @@ It can contain color definitions for any number of ranges. For each range, you m
     "19-10": [12, 34, 56]
   }
 }
-```]
+```
 
 Valid color formats are:
 - hex string starting with `#`, e.g. `"#23fa78"`
@@ -223,7 +256,7 @@ Valid color formats are:
 
 #note[
   The XML format implements colors a bit differently. Instead of having a "colors" dictionary, color definitions are directly put on the same level as structure definitions. For this, you can use a `color` node with the attributes "structure", "color", "start" and "end", like so:
-  #sourcecode[```xml
+  ```xml
   <schema>
     <structure id="main" bits="8">
       ...
@@ -232,7 +265,7 @@ Valid color formats are:
     <color structure="main" color="#FF0000" start="4" end="7" />
     <color structure="main" color="255,0,0" start="0" end="3" />
   </schema>
-  ```]
+  ```
 ]
 
 #pagebreak(weak: true)
@@ -254,6 +287,7 @@ Aside from the default config, some example presets are also provided:
 #let doc-config = tidy.parse-module(
   read("docs/config.typ"),
   name: "config",
+  old-syntax: true,
   scope: (
     doc-ref: doc-ref
   )
@@ -265,6 +299,7 @@ Aside from the default config, some example presets are also provided:
 #let doc-schema = tidy.parse-module(
   read("docs/schema.typ"),
   name: "schema",
+  old-syntax: true,
   scope: (
     schema: schema,
     doc-ref: doc-ref

src/lib.typ

@@ -1,4 +1,4 @@
-#let version = version((0,0,2))
+#let version = version(0,2,0)
 
 #import "config.typ"
 #import "schema.typ"

src/renderer.typ

@@ -1,4 +1,4 @@
-#import "@preview/cetz:0.2.2": canvas, draw
+#import "@preview/cetz:0.3.2": canvas, draw
 
 #import "range.typ" as rng
 #import "structure.typ"
@@ -373,7 +373,7 @@
   // Draw rectangle around structure
   shapes += draw-rect(border-col, bits-x, bits-y, bits-width, bit-h, thickness: 2)
 
-  let indices = range(struct.bits)
+  let indices = range(struct.start, struct.start + struct.bits)
   if not config.all-bit-i {
     indices = ()
     for r in struct.ranges.values() {

src/schema.typ

@@ -25,7 +25,7 @@
 
 #let parse-raw(schema) = {
   let lang = schema.lang
-  let content = schema.text
+  let content = bytes(schema.text)
   if not lang in valid-extensions {
     let fmts = valid-extensions.join(", ")
     fmts = "(" + fmts + ")"
@@ -33,11 +33,11 @@
   }
 
   if lang == "yaml" {
-    return yaml.decode(content)
+    return yaml(content)
   } else if lang == "json" {
-    return json.decode(content)
+    return json(content)
   } else if lang == "xml" {
-    return xml-loader.parse(xml.decode(content).first())
+    return xml-loader.parse(xml(content).first())
   }
 }
 

typst.toml

@@ -1,7 +1,7 @@
 [package]
 name = "rivet"
-version = "0.0.2"
-compiler = "0.11.0"
+version = "0.2.0"
+compiler = "0.13.0"
 repository = "https://git.kb28.ch/HEL/rivet-typst"
 entrypoint = "src/lib.typ"
 authors = [
@@ -11,4 +11,4 @@ categories = [ "visualization" ]
 license = "Apache-2.0"
 description = "Register / Instruction Visualizer & Explainer Tool with Typst, using CeTZ"
 keywords = [ "assembly", "instruction", "binary" ]
-exclude = [ "/gallery/*" ]
+exclude = [ "gallery", "justfile", "docs" ]