ajet/typlisp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ideate

Browse Source
This commit is contained in:
Adam Jeniski
2026-01-30 09:45:24 -10:00
parent fd0ec5aabc
commit 97747c6b5c
3 changed files with 167 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dual-mode.md
+11 -11
View File
@@ -85,7 +85,7 @@ Using `~()` - the unquote concept from Clojure's syntax-quote:
#t"The value is ~(expr)." #t"The value is ~(expr)."
;; Hiccup expression returns content ;; Hiccup expression returns content
#t"Click ~([:link {:dest url} label]) to continue." #t"Click ~([:link {:src url} label]) to continue."
;; Conditional ;; Conditional
#t"Status: ~(if done? 'Complete' 'Pending')" #t"Status: ~(if done? 'Complete' 'Pending')"
@@ -128,7 +128,7 @@ Same mental model as macro unquote:
[:block {:inset "1em"} [:block {:inset "1em"}
[:strong name] [:linebreak] [:strong name] [:linebreak]
[:emph affiliation] [:linebreak] [:emph affiliation] [:linebreak]
[:link {:dest (str "mailto:" email)} email]]) [:link {:src (str "mailto:" email)} email]])
(defn results-table [data] (defn results-table [data]
[:table {:columns 2 :align ["left" "right"]} [:table {:columns 2 :align ["left" "right"]}
@@ -171,8 +171,8 @@ Same mental model as macro unquote:
" "
;; Back to hiccup for the technical diagram ;; Back to hiccup for the technical diagram
[:figure {:caption "System architecture overview."} [:figure {:caption "System architecture overview." :label :fig/arch}
[:image {:width "80%"} "architecture.png"]] [:image {:src "architecture.png" :width "80%"}]]
#t" #t"
Our method works by first processing the input through Our method works by first processing the input through
@@ -198,7 +198,7 @@ Same mental model as macro unquote:
" "
;; Bibliography could be generated ;; Bibliography could be generated
[:bibliography "refs.bib"]]) [:bibliography {:src "refs.bib"}]])
;; Compile it ;; Compile it
(compile-to-typst paper "paper.typ") (compile-to-typst paper "paper.typ")
@@ -303,7 +303,7 @@ Build mini-languages for specific domains:
`(do `(do
(register-figure! ~id) (register-figure! ~id)
[:figure {:label ~id :caption ["Figure " (figure-num ~id) ": " ~caption]} [:figure {:label ~id :caption ["Figure " (figure-num ~id) ": " ~caption]}
[:image {:width ~(or width "100%")} ~src]])) [:image {:src ~src :width ~(or width "100%")}]]))
(figure :arch (figure :arch
:src "architecture.png" :src "architecture.png"
@@ -319,15 +319,15 @@ Build mini-languages for specific domains:
;; Shorthand for references ;; Shorthand for references
(defmacro ref [id] (defmacro ref [id]
`[:ref ~(str "@" (name id))]) `[:ref {:target ~id}])
;; Shorthand for citations ;; Shorthand for citations
(defmacro cite [& keys] (defmacro cite [& keys]
`[:cite ~@(map #(str "@" (name %)) keys)]) `[:cite {:keys [~@keys]}])
;; Usage ;; Usage
(ref :fig:arch) ; => @fig:arch (ref :fig/arch) ; => [:ref {:target :fig/arch}]
(cite :smith2020 :jones2021) ; => @smith2020 @jones2021 (cite :smith2020 :jones2021) ; => [:cite {:keys [:smith2020 :jones2021]}]
``` ```
### Template Macros ### Template Macros
@@ -339,7 +339,7 @@ Build mini-languages for specific domains:
~@structure)) ~@structure))
(deftemplate ieee-paper [title authors abstract] (deftemplate ieee-paper [title authors abstract]
[[:set :page {:paper "us-letter" :columns 2}] [[:set {:element :page :paper "us-letter" :columns 2}]
[:heading {:level 1 :align "center"} ~title] [:heading {:level 1 :align "center"} ~title]
(render-authors ~authors) (render-authors ~authors)
(render-abstract ~abstract) (render-abstract ~abstract)
hiccup-prototype.md
+8 -10
View File
@@ -40,26 +40,24 @@ Hiccup represents markup as nested data structures:
;; [1], [2], [3] ;; [1], [2], [3]
;; ) ;; )
;; Raw content blocks ;; Code blocks (use :raw for displayed code)
[:raw "= Direct Typst Markup\nJust passed through"]
;; Code blocks (use :raw with :lang)
[:raw {:lang "python" :block true} "print('hello')"] [:raw {:lang "python" :block true} "print('hello')"]
;; => #raw(lang: "python", block: true, "print('hello')") ;; => #raw(lang: "python", block: true, "print('hello')")
;; Math ;; Math (inline by default)
[:math "x^2 + y^2 = z^2"] [:math "x^2 + y^2 = z^2"]
;; => $x^2 + y^2 = z^2$ ;; => $x^2 + y^2 = z^2$
;; Math (block/display)
[:math {:block true} "sum_(i=0)^n i = (n(n+1))/2"] [:math {:block true} "sum_(i=0)^n i = (n(n+1))/2"]
;; => $ sum_(i=0)^n i = (n(n+1))/2 $ ;; => $ sum_(i=0)^n i = (n(n+1))/2 $
;; Images ;; Images (src in attrs, no children)
[:image {:width "50%"} "diagram.png"] [:image {:src "diagram.png" :width "50%"}]
;; => #image("diagram.png", width: 50%) ;; => #image("diagram.png", width: 50%)
;; Links ;; Links (src in attrs, child is display text)
[:link {:dest "https://typst.app"} "Typst"] [:link {:src "https://typst.app"} "Typst"]
;; => #link("https://typst.app")[Typst] ;; => #link("https://typst.app")[Typst]
``` ```
@@ -85,7 +83,7 @@ Hiccup represents markup as nested data structures:
[:heading {:level 2} "Results"] [:heading {:level 2} "Results"]
"The result is " [:$ "x = 42"] "." "The result is " [:math "x = 42"] "."
[:table {:columns 2} [:table {:columns 2}
[:strong "Input"] [:strong "Output"] [:strong "Input"] [:strong "Output"]
typst-mapping.md
+148 -53
View File
@@ -1,5 +1,84 @@
# Hiccup → Typst Mapping Reference # Hiccup → Typst Mapping Reference
## Hiccup Syntax
All elements follow standard Hiccup:
```clojure
[:tag {attrs} children...]
```
- **tag**: Element type (keyword)
- **attrs**: Optional map of attributes
- **children**: Content (strings, nested elements, or expressions)
### Element Categories
| Category | Examples | Children |
|----------|----------|----------|
| Content elements | `heading`, `strong`, `emph`, `block` | Display content |
| Source elements | `link`, `image`, `bibliography` | `link` has display text; others have none |
| List elements | `list`, `enum`, `table` | Each child = one item/cell |
| Container elements | `figure` | Single content child (compiled as function arg) |
| Math | `math` | Math expression string |
| References | `ref`, `cite` | None |
| Code | `raw` | Code string to display |
| Rules | `set` | None |
| Show rules | `show` | A `set` rule as child |
### Reserved Attributes
| Attr | Used by | Purpose |
|------|---------|---------|
| `:src` | `link`, `image`, `bibliography` | Source URL/path |
| `:label` | Any element | Makes element referenceable |
| `:caption` | `figure` | Figure caption text |
| `:target` | `ref` | Label to reference |
| `:keys` | `cite` | Citation key(s) |
| `:element` | `set`, `show` | Element type to configure |
| `:block` | `math`, `raw` | Display as block (default: inline) |
| `:lang` | `raw` | Code language for syntax highlighting |
### Examples
```clojure
;; Content element
[:heading {:level 2} "Section Title"]
;; Source element with children
[:link {:src "https://example.com"} "Click here"]
;; Source element without children
[:image {:src "diagram.png" :width "80%"}]
;; List element
[:list "First" "Second" "Third"]
;; Container with label
[:figure {:caption "Results" :label :fig/results}
[:image {:src "chart.png"}]]
;; Math (inline and block)
[:math "E = m c^2"]
[:math {:block true} "sum_(i=0)^n i"]
;; Reference and citation
[:ref {:target :fig/results}]
[:cite {:keys [:smith2020 :jones2021]}]
;; Code display
[:raw {:lang "python" :block true} "print('hello')"]
;; Set rule
[:set {:element :page :margin "2cm"}]
;; Show rule (child is the set rule to apply)
[:show {:element :heading}
[:set {:element :text :fill "blue"}]]
```
---
## Audit of Current Tags ## Audit of Current Tags
### ✅ Valid - Direct Typst Functions ### ✅ Valid - Direct Typst Functions
@@ -9,10 +88,10 @@
| `[:heading {:level 2} "Text"]` | `#heading(level: 2)[Text]` | ✅ Works | | `[:heading {:level 2} "Text"]` | `#heading(level: 2)[Text]` | ✅ Works |
| `[:strong "text"]` | `#strong[text]` | ✅ Works | | `[:strong "text"]` | `#strong[text]` | ✅ Works |
| `[:emph "text"]` | `#emph[text]` | ✅ Works | | `[:emph "text"]` | `#emph[text]` | ✅ Works |
| `[:link {:dest "url"} "text"]` | `#link("url")[text]` | ✅ Works | | `[:link {:src "url"} "text"]` | `#link("url")[text]` | ✅ Works |
| `[:image {:width "50%"} "path.png"]` | `#image("path.png", width: 50%)` | ✅ Works | | `[:image {:src "path.png" :width "50%"}]` | `#image("path.png", width: 50%)` | ✅ Works |
| `[:block {:inset "1em"} ...]` | `#block(inset: 1em)[...]` | ✅ Works | | `[:block {:inset "1em"} ...]` | `#block(inset: 1em)[...]` | ✅ Works |
| `[:bibliography "refs.bib"]` | `#bibliography("refs.bib")` | ✅ Works | | `[:bibliography {:src "refs.bib"}]` | `#bibliography("refs.bib")` | ✅ Works |
### ❌ Invalid - Don't Exist in Typst ### ❌ Invalid - Don't Exist in Typst
@@ -34,11 +113,8 @@
|---------|---------|---------| |---------|---------|---------|
| `[:linebreak]` | Function name | `[:linebreak]` → `#linebreak()` ✅ actually works | | `[:linebreak]` | Function name | `[:linebreak]` → `#linebreak()` ✅ actually works |
| `[:h-space "2em"]` | Wrong name | `[:h "2em"]` → `#h(2em)` | | `[:h-space "2em"]` | Wrong name | `[:h "2em"]` → `#h(2em)` |
| `[:figure [:image ...] [:caption ...]]` | Caption isn't a child | See below | | `[:figure [:image ...] [:caption ...]]` | Caption isn't a child | Caption goes in attrs |
| `[:math "x^2"]` | Need to distinguish inline/block | `$x^2$` vs `$ x^2 $` | | `[:code {:lang "py"} "..."]` | Function is `raw` | `[:raw {:lang "python"} "..."]` |
| `[:code {:lang "py"} "..."]` | Function is `raw` | `#raw(lang: "python", "...")` |
| `[:ref :label]` | Takes label not string | `#ref(<label>)` |
| `[:cite :key]` | Takes label | `#cite(<key>)` |
## Corrected Mappings ## Corrected Mappings
@@ -119,12 +195,12 @@ Caption is a named parameter, not a child element:
;; NEW (correct) ;; NEW (correct)
[:figure {:caption "Architecture diagram"} [:figure {:caption "Architecture diagram"}
[:image "arch.png"]] [:image {:src "arch.png"}]]
;; => #figure(image("arch.png"), caption: [Architecture diagram]) ;; => #figure(image("arch.png"), caption: [Architecture diagram])
;; With label for referencing ;; With label for referencing
[:figure {:caption "Architecture" :label :fig:arch} [:figure {:caption "Architecture" :label :fig/arch}
[:image {:width "80%"} "arch.png"]] [:image {:src "arch.png" :width "80%"}]]
;; => #figure(image("arch.png", width: 80%), caption: [Architecture]) <fig:arch> ;; => #figure(image("arch.png", width: 80%), caption: [Architecture]) <fig:arch>
``` ```
@@ -139,17 +215,13 @@ Caption is a named parameter, not a child element:
### Math ### Math
```clojure ```clojure
;; Inline math ;; Inline math (default)
[:$ "x^2 + y^2"] [:math "x^2 + y^2"]
;; => $x^2 + y^2$ ;; => $x^2 + y^2$
;; Block/display math ;; Block/display math
[:$$ "sum_(i=0)^n i"]
;; => $ sum_(i=0)^n i $
;; Or with explicit flag
[:math "x^2"] ;; inline by default
[:math {:block true} "sum_(i=0)^n i"] [:math {:block true} "sum_(i=0)^n i"]
;; => $ sum_(i=0)^n i $
``` ```
### Code/Raw ### Code/Raw
@@ -176,15 +248,15 @@ Caption is a named parameter, not a child element:
```clojure ```clojure
;; Reference a label ;; Reference a label
[:ref :fig:arch] [:ref {:target :fig/arch}]
;; => @fig:arch ;; => @fig:arch
;; Citation ;; Single citation
[:cite :smith2020] [:cite {:keys [:smith2020]}]
;; => @smith2020 ;; => @smith2020
;; Multiple citations ;; Multiple citations
[:cite :smith2020 :jones2021] [:cite {:keys [:smith2020 :jones2021]}]
;; => @smith2020 @jones2021 ;; => @smith2020 @jones2021
``` ```
@@ -197,18 +269,19 @@ Caption is a named parameter, not a child element:
### Page/Document Settings ### Page/Document Settings
`set` rules are special - they affect following content: `set` and `show` rules configure document styling. Use `:element` attr to specify the target:
```clojure ```clojure
;; Set rules (affects everything after) ;; Set rules (affects everything after)
[:set :page {:paper "a4" :margin "2cm"}] [:set {:element :page :paper "a4" :margin "2cm"}]
;; => #set page(paper: "a4", margin: 2cm) ;; => #set page(paper: "a4", margin: 2cm)
[:set :text {:font "New Computer Modern" :size "11pt"}] [:set {:element :text :font "New Computer Modern" :size "11pt"}]
;; => #set text(font: "New Computer Modern", size: 11pt) ;; => #set text(font: "New Computer Modern", size: 11pt)
;; Show rules ;; Show rules (child is the set rule to apply)
[:show :heading {:set {:text {:fill "blue"}}}] [:show {:element :heading}
[:set {:element :text :fill "blue"}]]
;; => #show heading: set text(fill: blue) ;; => #show heading: set text(fill: blue)
``` ```
@@ -235,8 +308,8 @@ Second paragraph.
```clojure ```clojure
(def my-doc (def my-doc
[;; Set rules at top [;; Set rules at top
[:set :page {:paper "a4"}] [:set {:element :page :paper "a4"}]
[:set :text {:font "Linux Libertine"}] [:set {:element :text :font "Linux Libertine"}]
[:heading {:level 1} "My Paper"] [:heading {:level 1} "My Paper"]
@@ -256,22 +329,23 @@ Second paragraph.
[:heading {:level 2} "Results"] [:heading {:level 2} "Results"]
"See " [:ref :fig:results] " and " [:ref :tab:data] "." "See " [:ref {:target :fig/results}] " and " [:ref {:target :tab/data}] "."
[:figure {:caption "Results visualization" :label :fig:results} [:figure {:caption "Results visualization" :label :fig/results}
[:image {:width "80%"} "results.png"]] [:image {:src "results.png" :width "80%"}]]
[:table {:columns 2 :label :tab:data} [:figure {:caption "Data table" :label :tab/data}
[:strong "Input"] [:strong "Output"] [:table {:columns 2}
"1" "1" [:strong "Input"] [:strong "Output"]
"2" "4" "1" "1"
"3" "9"] "2" "4"
"3" "9"]]
"The equation is " [:$ "E = mc^2"] "." "The equation is " [:math "E = m c^2"] "."
[:$$ "integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2"] [:math {:block true} "integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2"]
[:bibliography "refs.bib"]]) [:bibliography {:src "refs.bib"}]])
``` ```
**Compiles to:** **Compiles to:**
@@ -303,28 +377,49 @@ See @fig:results and @tab:data.
caption: [Results visualization], caption: [Results visualization],
) <fig:results> ) <fig:results>
#table( #figure(
columns: 2, table(
[#strong[Input]], [#strong[Output]], columns: 2,
[1], [1], [#strong[Input]], [#strong[Output]],
[2], [4], [1], [1],
[3], [9], [2], [4],
[3], [9],
),
caption: [Data table],
) <tab:data> ) <tab:data>
The equation is $E = mc^2$. The equation is $E = m c^2$.
$ integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2 $ $ integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2 $
#bibliography("refs.bib") #bibliography("refs.bib")
``` ```
## Summary of Changes ## Typst Gotchas
Important Typst behaviors the compiler must handle:
1. **Math variable spacing**: In math mode, adjacent letters like `mc` are parsed as a single variable name. To represent multiplication, add spaces: `$m c^2$` not `$mc^2$`. The compiler should insert spaces between single-letter variables.
2. **Referenceable tables**: Tables cannot have labels directly attached. To make a table referenceable with `@label`, wrap it in a `#figure()`:
```typst
#figure(
table(...),
caption: [...],
) <label>
```
3. **Font availability**: Fonts like "Linux Libertine" may not be installed. The compiler should either bundle fonts or use fallbacks.
## Summary of Design Decisions
1. **Removed**: `:p`, `:item`, `:cell`, `:div`, `:span`, `:aside`, `:section`, `:doc` 1. **Removed**: `:p`, `:item`, `:cell`, `:div`, `:span`, `:aside`, `:section`, `:doc`
2. **Lists/Tables**: Children are direct content, not wrapped in `:item`/`:cell` 2. **Lists/Tables**: Children are direct content, not wrapped in `:item`/`:cell`
3. **Figures**: Caption is an attribute, not a child 3. **Figures**: Caption is an attribute; child element compiles as function argument (no `#`)
4. **Math**: Use `:$` for inline, `:$$` for block 4. **Math**: Use `:math` with optional `:block` attr (not `:$`/`:$$`)
5. **Code**: Use `:raw` not `:code` 5. **Code**: Use `:raw` for displayed code; `#t"..."` for Typst passthrough
6. **Space**: Use `:h`/`:v` not `:h-space` 6. **Space**: Use `:h`/`:v` not `:h-space`
7. **Settings**: `:set` takes element type and attrs 7. **References**: Use `[:ref {:target :label}]` and `[:cite {:keys [...]}]`
8. **Paragraphs**: Use `:parbreak` or just content flow 8. **Settings**: Use `[:set {:element :page ...}]` - attrs first with `:element`
9. **Paragraphs**: Use `:parbreak` or just content flow
10. **Referenceable tables**: Must wrap in `:figure` with `:label` attribute