completed README.md

README.md

@@ -1,3 +1,44 @@
 # rivet-typst
 
-Register / Instruction Visualizer & Explainer Tool with Typst, using CeTZ
+RIVET _(Register / Instruction Visualizer & Explainer Tool)_ is a [Typst](https://typst.app) package for visualizing binary instructions or describing the contents of a register, using the [CeTZ](https://typst.app/universe/package/cetz) package.
+
+It is based on the [homonymous Python script](https://git.kb28.ch/HEL/rivet)
+
+## Examples
+<table>
+  <tr>
+    <td>
+      <a href="./gallery/example1.typ">
+        <img src="./gallery/example1.png" width="500px">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>A bit of eveything</td>
+  </tr>
+  <tr>
+    <td>
+      <a href="./gallery/example2.typ">
+        <img src="./gallery/example2.png" width="500px">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>RISC-V memory instructions (blueprint)</td>
+  </tr>
+</table>
+
+*Click on the example image to jump to the code.*
+
+## Usage
+For 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à !
+```typ
+#import "src/lib.typ": schema
+#let doc = schema.load("path/to/schema.yaml")
+#schema.render(doc)
+```
+
+## Installing
+> TODO

gallery/example1.typ

@@ -0,0 +1,6 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example1.yaml")
+#schema.render(example, config: config.config(
+  full-page: true
+))

gallery/example1.yaml

@@ -0,0 +1,73 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-28:
+        name: cond
+      27:
+        name: 0
+      26:
+        name: 1
+      25:
+        name: I
+      24:
+        name: P
+        description: pre / post indexing bit
+        values:
+          0: post, add offset after transfer
+          1: pre, add offset before transfer
+      23:
+        name: U
+        description: up / down bit
+        values:
+          0: down, subtract offset from base
+          1: up, addition offset to base
+      22:
+        name: B
+        description: byte / word bit
+        values:
+          0: transfer word quantity
+          1: transfer byte quantity
+      21:
+        name: W
+        description: write-back bit
+        values:
+          0: no write-back
+          1: write address into base
+      20:
+        name: L
+        description: load / store bit
+        values:
+          0: store to memory
+          1: load from memory
+      19-16:
+        name: Rn
+        description: base register
+      15-12:
+        name: Rd
+        description: source / destination register
+      11-0:
+        name: offset
+        depends-on: 25
+        values:
+          0:
+            description: offset is an immediate value
+            structure: immediateOffset
+          1:
+            description: offset is a register
+            structure: registerOffset
+  immediateOffset:
+    bits: 12
+    ranges:
+      11-0:
+        name: 12-bit immediate offset
+        description: unsigned number
+  registerOffset:
+    bits: 12
+    ranges:
+      11-4:
+        name: shift
+        description: shift applied to Rm
+      3-0:
+        name: Rm
+        description: offset register

gallery/example2.typ

@@ -0,0 +1,7 @@
+#import "../src/lib.typ": schema, config
+
+#let example = schema.load("/gallery/example2.yaml")
+#schema.render(example, config: config.blueprint(
+  full-page: true,
+  left-labels: true
+))

gallery/example2.yaml

@@ -0,0 +1,78 @@
+structures:
+  main:
+    bits: 32
+    ranges:
+      31-20:
+        name: src
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: srcImmediate
+          1:
+            description:
+            structure: srcRegister
+      19-15:
+        name: rs1
+      14-12:
+        name: funct3
+        description: function modifier
+        values:
+          000: byte
+          001: half-word
+          "010": word
+          100: upper byte (load only)
+          101: upper half (load only)
+      11-7:
+        name: dst
+        depends-on: 5
+        values:
+          0:
+            description:
+            structure: dstRegister
+          1:
+            description:
+            structure: dstImmediate
+      6:
+        name: 0
+      5:
+        name: I
+      4:
+        name: 0
+      3:
+        name: 0
+      2:
+        name: 0
+      1:
+        name: 1
+      0:
+        name: 1
+
+  srcImmediate:
+    bits: 12
+    ranges:
+      11-0:
+        name: src
+        description: source memory address
+  srcRegister:
+    bits: 12
+    ranges:
+      11-5:
+        name: dstU
+        description: destination address upper bits
+      4-0:
+        name: rs2
+        description: source register
+
+  dstImmediate:
+    bits: 5
+    ranges:
+      4-0:
+        name: destL
+        description: destination address lower bits
+  dstRegister:
+    bits: 5
+    ranges:
+      4-0:
+        name: rd
+        description: destination register

manual.typ

@@ -39,7 +39,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
-#let doc = schema.load("path/to/schema.typ")
+#let doc = schema.load("path/to/schema.yaml")
 #schema.render(doc)
 ```]