diff --git a/docs/config.typ b/docs/config.typ index 3023224..2046f8c 100644 --- a/docs/config.typ +++ b/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) = {} \ No newline at end of file diff --git a/docs/examples.typ b/docs/examples.typ index 5e1c362..1e6c99b 100644 --- a/docs/examples.typ +++ b/docs/examples.typ @@ -13,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( diff --git a/docs/schema.typ b/docs/schema.typ index 4a56136..48d539e 100644 --- a/docs/schema.typ +++ b/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%) = {} \ No newline at end of file diff --git a/gallery.bash b/gallery.bash deleted file mode 100755 index 16e91db..0000000 --- a/gallery.bash +++ /dev/null @@ -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" - - files=$(find ./gallery -type f -name "*.typ") - cnt=$(echo "$files" | wc -l) - i=1 - for f in $files - do - f2="${f%.typ}.pdf" - echo "($i/$cnt) $f -> $f2" - typst c --root ./ "$f" "$f2" - i=$((i+1)) - done -fi \ No newline at end of file diff --git a/gallery/example1.pdf b/gallery/example1.pdf index ea70a46..ca2330e 100644 Binary files a/gallery/example1.pdf and b/gallery/example1.pdf differ diff --git a/gallery/example2.pdf b/gallery/example2.pdf index 64c014f..20678da 100644 Binary files a/gallery/example2.pdf and b/gallery/example2.pdf differ diff --git a/gallery/example3.pdf b/gallery/example3.pdf index d54338a..d5156f4 100644 Binary files a/gallery/example3.pdf and b/gallery/example3.pdf differ diff --git a/gallery/test.pdf b/gallery/test.pdf index b017b16..aa076ba 100644 Binary files a/gallery/test.pdf and b/gallery/test.pdf differ diff --git a/justfile b/justfile new file mode 100644 index 0000000..f0c0b97 --- /dev/null +++ b/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 diff --git a/manual.pdf b/manual.pdf index 90cf0d5..8597825 100644 Binary files a/manual.pdf and b/manual.pdf differ diff --git a/manual.typ b/manual.typ index 566dd28..a97b449 100644 --- a/manual.typ +++ b/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 @@ -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()[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 @@ -125,7 +158,7 @@ For values depending on other ranges, see #link()[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()[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 ... @@ -232,7 +265,7 @@ Valid color formats are: - ```] + ``` ] #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 diff --git a/src/schema.typ b/src/schema.typ index 5c1f650..7028273 100644 --- a/src/schema.typ +++ b/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()) } } diff --git a/typst.toml b/typst.toml index d949c29..a0c5417 100644 --- a/typst.toml +++ b/typst.toml @@ -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", "gallery.bash", "docs" ] \ No newline at end of file +exclude = [ "gallery", "justfile", "docs" ] \ No newline at end of file