diff --git a/manual.pdf b/manual.pdf index a1e8469..2031103 100644 Binary files a/manual.pdf and b/manual.pdf differ diff --git a/manual.typ b/manual.typ index 8124525..214fdfe 100644 --- a/manual.typ +++ b/manual.typ @@ -1,4 +1,6 @@ #import "@preview/tidy:0.3.0" +#import "@preview/codelst:2.0.1": sourcecode +#import "@preview/showybox:2.0.1": showybox #import "src/lib.typ" #import "src/schema.typ" #import "docs/examples.typ" @@ -26,13 +28,26 @@ link(label(label-name))[#display-name] } +#let note(it) = showybox( + title: "Note", + title-style: ( + color: white, + weight: "bold" + ), + frame: ( + title-color: blue.lighten(30%), + border-color: blue.darken(40%) + ), + it +) + #show link: set text(blue) = 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 -This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst. For more information on the schema format, please check out the original project's #link("https://git.kb28.ch/HEL/rivet/src/branch/main/format.md")[format.md] +This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst. = Usage @@ -43,6 +58,185 @@ Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse #schema.render(doc) ```] += Format + +This section describes the structure of a schema definition. The examples given use the JSON syntax. For examples in different formats, see #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.yaml")[test.yaml], #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.json")[test.json] and #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.xml")[test.xml]. You can also directly define a schema using Typst dictionaries and arrays. + +Since the XML format is quite different from the other, you might find it helpful to look at the examples on GitHub to get familiar with it. + +== Main layout + +A schema contains a dictionary of structures. The must be at least one defined structure named "main". + +It can also optionnaly contain a "colors" dictionary. More details about this in #link()[Colors] + +#sourcecode[```json +{ + "structures": { + "main": { + ... + }, + "struct1": { + ... + }, + "struct2": { + ... + }, + ... + } +} +```] + +#pagebreak(weak: true) + +== Structure + +A structure has a given number of bits and one or multiple ranges. Each range of bits can have a name, a description and / or values with special meaning (see #link()[Range]). A range's structure can also depend on another range's value (see #link()[Dependencies]). + +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 +"main": { + "bits": 8, + "ranges": { + "7-4": { + ... + }, + "3-2": { + ... + }, + "1": { + ... + }, + "0": { + ... + } + } +} +```] + +== Range + +A range represents a group of consecutive bits. It can have a name (displayed in the bit cells), a description (displayed under the structure) and / or values. + +For values depending on other ranges, see #link()[Dependencies]. + +#note[ + 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 +"3-2": { + "name": "op", + "description": "Logical operation", + "values": { + "00": "AND", + "01": "OR", + "10": "XOR", + "11": "NAND" + } +} +```] + +#pagebreak(weak: true) + +== Dependencies + +The structure of one range may depend on the value of another. To represent this situation, first indicate on the child range the range on which it depends. + +Then, in its values, indicate which structure to use. A description can also be added (displayed above the horizontal dependency arrow) + +#sourcecode[```json +"7-4": { + ... + "depends-on": "0", + "values": { + "0": { + "description": "immediate value", + "structure": "immediateValue" + }, + "1": { + "description": "value in register", + "structure": "registerValue" + } + } +} +```] + +Finally, add the sub-structures to the structure dictionary: + +#sourcecode[```json +{ + "structures": { + "main": { + ... + }, + "immediateValue": { + "bits": 4, + ... + }, + "registerValue": { + "bits": 4, + ... + }, + ... + } +} +```] + +#pagebreak(weak: true) + +== Colors + +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 +{ + "structures": { + ... + }, + "colors": { + ... + } +} +```] + +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 +"colors": { + "main": { + "31-28": "#ABCDEF", + "27-20": "12,34,56" + }, + "registerValue": { + "19-10": [12, 34, 56] + } +} +```] + +Valid color formats are: +- hex string starting with `#`, e.g. `"#23fa78"` +- array of three integers (only JSON, YAML and Typst), e.g. `[35, 250, 120]` +- string of three comma-separated integers (useful for XML), e.g. `"35,250,120"` +- a Typst color (only Typst), e.g. `colors.green` or `rgb(35, 250, 120)` + +#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 + + + ... + + ... + + + + ```] +] + +#pagebreak(weak: true) + = Config presets Aside from the default config, some example presets are also provided: