ravenous_typst/docs/usage.md

204 lines
5.0 KiB
Markdown

# 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 <ssec:resistances>
Les règles complètes sont décrites ailleurs
#reference(<ssec:resistances>).
```
This renders a clickable reference such as “voir section 3.2 page 18”. For the
long form, use `long: true`:
```typst
#reference(<ssec:resistances>, 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(
<ssec:future-rule>,
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].
```
## Illustrated prose
Use `illustrated` to place a framed image beside prose and let the text flow
around it. Image paths beginning with `/` are relative to the repository root:
```typst
#illustrated(
"/images/illustrations/example_child.jpg",
[
Sur terre, sous la surface des mers et dans les cieux vivent les enfants
des calamités. Le texte se poursuit naturellement autour de l'illustration.
],
)
```
Add a caption, change the image width, or place it on the left when useful:
```typst
#illustrated(
"/images/illustrations/example_child.jpg",
[
Le contenu peut comporter plusieurs paragraphes.
Le texte est présenté à côté de l'image.
],
side: left,
width: 4cm,
caption: [Un Zizfir juvénile.],
)
```
The optional parameters are:
- `side`: `left` or `right`; defaults to `right`;
- `width`: displayed image width; defaults to `4cm`;
- `radius`: corner radius for the image frame; defaults to `3pt`;
- `caption`: content displayed beneath the image; defaults to `none`.
For several nearby illustrations, alternating `side: left` and `side: right`
usually gives the page a more balanced rhythm. Keep headings outside the body
passed to `illustrated` so they remain part of the document outline.
## Rule notation
`ddlvl` displays a difficulty level using the project's notation:
```typst
#ddlvl(3)
#ddlvl(2, plus: true)
```
`marques` formats a number of status marks and pluralizes “marque” automatically:
```typst
#marques([@al_saignement], 1, 2) // 1 marque de saignement (difficulty 2)
#marques([@al_saignement], 3, 2) // 3 marques de saignement (difficulty 2)
```
`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
```