ravenous_typst/docs/usage.md

379 lines
9.8 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
```
## Common creature names
Use `#creature-name[Baloth Briséchine]` for common creature names in prose:
`un #creature-name[Baloth Briséchine]`, `un jeune #creature-name[Zizfir]`.
The helper applies emphasis (italics). Keep articles and incidental age or size
descriptions outside it. Do not use it for Greater Calamities' proper names,
school or technique names, or inside tables (including ingredients and mounts).
Apply it explicitly at prose call sites; do not format database names globally.
## Create a themed document
For a new document that uses the same theme and document model as the Ravenous
handbooks, create a Typst file at the repository root with this structure:
```typst
#import "/setup/setup.typ": config_main
#import "/setup/prelude.typ": *
#show: config_main
#set document(
title: "Mon document",
author: "Mon nom",
)
= Mon document
Le contenu commence ici.
```
`config_main` applies the theme selected by `document.color_scheme` in
`data/config/build.yaml`, along with the shared page styles, text styles,
glossary support, and complete glossary output.
Compile it from the repository root:
```sh
typst compile mon_document.typ mon_document.pdf
```
To select another existing theme for one build, pass the shared `theme` input:
```sh
typst compile --input theme=steel mon_document.typ mon_document-steel.pdf
```
Available theme names are defined in `setup/theme/themes.typ`.
## 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
#rav-help[Une règle ou information importante.]
#rav-help(title: "Conseil")[Un conseil avec un titre personnalisé.]
#rav-example[Un exemple d'application de la règle.]
#rav-example(
[
Premier exemple.
],
[
Second exemple, séparé visuellement du premier.
],
[
Troisième exemple ; le nombre d'éléments est arbitraire.
],
)
#rav-box[Une boîte sans titre.]
```
For quieter examples inside a dense rules section, use `rav-muted-example`.
It adds a small inline label and a discreet left rule instead of a full box:
```typst
#rav-muted-example[
Un exemple secondaire qui ne doit pas interrompre la lecture.
]
#rav-muted-example(title: [Cas limite])[
Le titre peut être personnalisé.
]
#rav-muted-example(
[Premier exemple discret.],
[Second exemple, séparé du premier par un filet horizontal.],
[Le nombre d'éléments est arbitraire.],
)
```
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)
```
Two shortcuts cover the most common variants:
```typst
#ddplus(2) // equivalent to #ddlvl(2, plus: true)
#ddshort(4) // equivalent to #ddlvl(4, max_number: 3)
```
`ddshort` also accepts `plus: true`. Craft tables use its compact three-symbol
limit automatically when evaluating `ddlvl` calls from their source data.
`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.
## Glossary definitions
Use `show_definition` to display a glossary term followed by its complete
definition:
```typst
#show_definition("rl_channel")
```
This is equivalent to writing `#gls("rl_channel") :
#gls-description("rl_channel")`, while keeping repeated definitions consistent
with their glossary entry.
## Forge effect macros
Forge material and finishing effects should use the structured helpers below.
Besides producing consistent text, these calls allow the cookbook and balance
report to include the modifiers in their calculations.
Use `change` for a direct statistic modifier:
```typst
#change("integrity", "+2")
#change("torque", "-10")
```
The effect must include its sign. An optional `of_type` condition associates a
damage modifier with a particular element or physical damage type:
```typst
#change("elemental_damage", "+1", of_type: [@el_ice])
#change("physical_damage", "+5", of_type: [@el_blunt])
```
These render in the form “Dégâts de type Glace +1”.
Use `change-resist` for elemental or physical resistance changes in craft data:
```typst
#change-resist([@el_ice], 2)
#change-resist([@el_water], -3)
```
These render as “Résistance Glace (++)” and “Résistance Eau (---)”. The value
must be an integer and the element must be passed as content.
Use `resist-category` to grant resistance to every alteration associated with
an elemental or physical type:
```typst
#resist-category([@el_ice], 1)
```
This renders as “Résistance à toutes les altérations de type Glace
(#ddlvl(1, plus: true))”.
Use `tearing-resist` for resistance against attempts to tear an item away:
```typst
#tearing-resist(2)
```
This renders as “Résistance à l'arrachement (#ddlvl(2, plus: true))”.
Use `drawback-reduction` when an effect reduces existing penalties from other
compounded forge elements. It only affects negative values and never turns a
penalty into a bonus:
```typst
#drawback-reduction(("dodge", "parry"), "2")
#drawback-reduction(("damage",), "4")
```
Use `bonus-reduction` for the inverse operation. It reduces existing positive
bonuses and never turns a bonus into a penalty:
```typst
#bonus-reduction(("damage", "rmax"), "-2")
#bonus-reduction(("p_damage",), "-1")
```
Both reduction macros accept one or more statistic names. Damage per success
may be written as either `p_damage` or `damage_p`.
Inside trusted forge TSV cells, the quotes around statistic names and integer
amounts are optional. For example, the following is equivalent to the first
`bonus-reduction` example above:
```typst
#bonus-reduction((damage, rmax), -2)
```
## 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
```