Starts reference work
This commit is contained in:
parent
692e739205
commit
d28b546fa9
11
Readme.md
11
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.
|
||||
|
|
|
|||
|
|
@ -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(<sssec:couches_protections>, 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
|
||||
|
|
|
|||
|
|
@ -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(<sec:sangressence>, 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
|
||||
|
|
|
|||
|
|
@ -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 <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].
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
|
@ -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,
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,15 @@
|
|||
#import "/setup/prelude.typ": reference
|
||||
|
||||
#set page(numbering: "1")
|
||||
#set heading(numbering: "1.1")
|
||||
|
||||
= Chapitre
|
||||
== Cible <sec:cible>
|
||||
|
||||
#reference(<sec:cible>)
|
||||
|
||||
#reference(<sec:cible>, long: true)
|
||||
|
||||
#reference(<sec:absente>, fallback: [Section de repli])
|
||||
|
||||
#reference(<sec:absente>, long: true, fallback: [Section de repli])
|
||||
Loading…
Reference in New Issue