diff --git a/Readme.md b/Readme.md index 9c89241..361147b 100644 --- a/Readme.md +++ b/Readme.md @@ -34,6 +34,17 @@ typst compile main.typ main.pdf - `setup/` contains shared styles, models, and macros. - `images/` and `data/` contain supporting assets and game data. +## Writing chapters + +Import the chapter-authoring prelude to access the shared macros and styles: + +```typst +#import "/setup/prelude.typ": * +``` + +See [the Typst usage guide](docs/usage.md) for the available helpers, section +references, examples, and guidance on when to use a more specific import. + ## Contributing and conduct Contributions, corrections, and suggestions are welcome. Keep changes focused, make sure the book still compiles, and explain non-obvious decisions in your pull request or commit message. diff --git a/data/src/origines/behemoth_2.yaml b/data/src/origines/behemoth_2.yaml index f9aea2e..7fdf2bf 100644 --- a/data/src/origines/behemoth_2.yaml +++ b/data/src/origines/behemoth_2.yaml @@ -31,7 +31,7 @@ stades: L'extérieur de votre peau est désormais partiellement couvert de rocs formant une armure naturelle #footnote[#mecaniquejeu[Shistederme] et votre armure réduisent l'une comme l'autre les dégâts d'une attaque, mais leur intégrité est perdue séparément - \reference sssec:couches_protections Multiples couches de protections..] Cette + #reference(, fallback: [Multiples couches de protections]).] Cette armure offre une protection de deux points avec une intégrité de 1 et se régénère à la fin de chaque combat. La première fois que vous devriez subir des dégâts létaux lors d'un combat, régénérez votre Shistederme sur toutes vos localisations diff --git a/data/src/origines/djieien_1.yaml b/data/src/origines/djieien_1.yaml index 1bb0071..f9a80f7 100644 --- a/data/src/origines/djieien_1.yaml +++ b/data/src/origines/djieien_1.yaml @@ -38,7 +38,7 @@ stades: vous laissez une mue possédant votre apparence, votre essence et votre odeur à la place et vous repositionnez sur n'importe quelle surface dans un rayon de 10 mètre à l'aide d'un _Filin Sangressence_ - #footnote[_Filin Sangressence_ : Il s'agit d'un filin fait à l'aide de la même sangressence que celle issue des calamités. \reference[sec:sangressenceLa Sangressence.]] + #footnote[_Filin Sangressence_ : Il s'agit d'un filin fait à l'aide de la même sangressence que celle issue des calamités. #reference(, fallback: [La Sangressence.])] Cette mue possède autant de points d'intégrité que votre _Psyché_, un point de protection et se désagrège naturellement au début de votre prochain tour. Si elle venait à être détruite, une multitude d'arachnides jailliront de cette dernière tissant autant diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..ecee574 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,154 @@ +# Writing Ravenous content with Typst + +This guide covers the shared helpers intended for ordinary chapters and rules. +For the overall repository structure and build commands, see the +[project README](../Readme.md). + +## Import the prelude + +Start a chapter with: + +```typst +#import "/setup/prelude.typ": * +``` + +The leading `/` makes the path relative to the project root. The prelude is the +recommended authoring interface: it exposes common helpers without importing +document configuration or specialized models into every chapter. + +When compiling a chapter or test directly, keep the repository as Typst's root: + +```sh +typst compile --root . chapters/my_chapter.typ chapter.pdf +``` + +## Section references + +Give the destination heading a label, then pass that label to `reference`: + +```typst +== Résistances + +Les règles complètes sont décrites ailleurs +#reference(). +``` + +This renders a clickable reference such as “voir section 3.2 page 18”. For the +long form, use `long: true`: + +```typst +#reference(, long: true) +``` + +This renders “Pour plus de détails, se référer à la section 3.2 page 18”. Both +`long` and `fallback` are optional and default to `false` and `none`. + +If a label is optional or temporarily unavailable, provide a section name as a +fallback: + +```typst +#reference( + , + fallback: [Règle à venir], +) +``` + +Without a matching label or a `fallback`, compilation fails deliberately so +broken references are not silently published. + +## Prose boxes + +The prelude provides themed boxes for common editorial content: + +```typst +#ravhelp[Une règle ou information importante.] + +#ravhelp(title: "Conseil")[Un conseil avec un titre personnalisé.] + +#ravex[Un exemple d'application de la règle.] + +#ravtwoex[ + Premier exemple. +][ + Second exemple, séparé visuellement du premier. +] + +#ravbox[Une boîte sans titre.] +``` + +Use `inline_help` for a short parenthetical aside: + +```typst +Le personnage agit immédiatement #inline_help[sauf indication contraire]. +``` + +## Rule notation + +`ddlvl` displays a difficulty level using the project's notation: + +```typst +#ddlvl(3) +#ddlvl(2, plus: true) +``` + +`kw` emphasizes a rules keyword: + +```typst +L'action affecte l'#kw[acteur]. +``` + +The prelude also exposes: + +- `hunbal`, for shared rule constants; +- `symbols`, for the project's symbol collection; +- `macros`, for less common helpers from `setup/core/macros.typ`. + +Prefer a directly exported helper such as `ddlvl` over `macros.ddlvl` when both +are available. + +## Tables and CSV data + +Use `st` to access the shared table styles: + +```typst +#show table: st.set-table-style + +#table( + columns: (1fr, auto), + [Nom], [Valeur], + [Exemple], [3], +) +``` + +Use `csv-table` for data-backed tables: + +```typst +#csv-table( + "/data/src/example.csv", + columns: (1fr, auto), +) +``` + +CSV cells are treated as plain text by default. Set `evaluate: "markup"` or +`evaluate: "code"` only when the source is trusted and needs Typst evaluation. + +## Specialized imports + +The prelude intentionally stays small. Import from `/setup/setup.typ` or the +relevant implementation module when working with document configuration, +warnings, build metadata, domain models, report generation, or theme internals. +Keep those imports explicit so a chapter's unusual dependencies remain visible. + +For example: + +```typst +#import "/setup/prelude.typ": * +#import "/setup/setup.typ": gls, nogls +``` + +Before submitting a change, compile the relevant target. For changes to shared +macros or styles, also compile the complete rulebook: + +```sh +typst compile main.typ main.pdf +``` diff --git a/setup/core/macros.typ b/setup/core/macros.typ index aa20830..3ee71d8 100644 --- a/setup/core/macros.typ +++ b/setup/core/macros.typ @@ -111,6 +111,38 @@ emph[( #content )] } +//----- Cross-references to sections ----- +#let reference(target, long: false, fallback: none) = context { + let sections = query(target) + + if sections.len() == 0 { + if fallback == none { + panic("reference: label " + repr(target) + " not found and no fallback was provided") + } + + if long { + [Pour plus de détails, se référer à la section #fallback] + } else { + [voir section #fallback] + } + } else { + let section = sections.first() + let location = section.location() + let section-number = numbering( + section.numbering, + ..counter(heading).at(location), + ) + let page-number = numbering("1", ..counter(page).at(location)) + let destination = link(target)[section #section-number page #page-number] + + if long { + [Pour plus de détails, se référer à la #destination] + } else { + [voir #destination] + } + } +} + #let noop(..text) = { text } #let mecaniquejeu(text) = { [ _ #text _ ] } @@ -142,7 +174,7 @@ inline_help: inline_help, hunbal: hunbal, footnote: footnote, - reference: noop, + reference: reference, mecaniquejeu: mecaniquejeu, symbols: symbols, ) diff --git a/setup/prelude.typ b/setup/prelude.typ index b5fa791..73d83ad 100644 --- a/setup/prelude.typ +++ b/setup/prelude.typ @@ -15,6 +15,7 @@ // Common prose helpers. #let ravhelp = setup.ravhelp #let inline_help = setup.inline_help +#let reference = setup.reference #let ravex = boxes.ravex #let ravtwoex = boxes.ravtwoex #let ravbox = boxes.ravbox diff --git a/setup/setup.typ b/setup/setup.typ index 95c4068..98031ae 100644 --- a/setup/setup.typ +++ b/setup/setup.typ @@ -38,6 +38,7 @@ //----- Alias for the project's help box ----- #let ravhelp = macros.memo_box #let inline_help = macros.inline_help +#let reference = macros.reference //----- Configure warnings for the project namespace ----- #import "@preview/uniwarn:0.1.1" as uwarn diff --git a/test/reference-macro-test.typ b/test/reference-macro-test.typ new file mode 100644 index 0000000..3aaa022 --- /dev/null +++ b/test/reference-macro-test.typ @@ -0,0 +1,15 @@ +#import "/setup/prelude.typ": reference + +#set page(numbering: "1") +#set heading(numbering: "1.1") + += Chapitre +== Cible + +#reference() + +#reference(, long: true) + +#reference(, fallback: [Section de repli]) + +#reference(, long: true, fallback: [Section de repli])