19 style guide
vicky edited this page 2026-08-16 22:32:49 +02:00
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Tools

Following is the list of "tools" that we will use for every thing Ravenous. More precise uses and nomenclatures will be added as they are decided and created.

Each entry must have distinctive stylings allowing the reader to distinguish between them at a glance.

Glossary

  • Deprecated keywords

Keywords used in development. Must be replaced with proper glossary entries down the line.

  • Keywords

As exhaustive as possible, every important or recurrent concept should be made into a glossary entry.

  • Glossary categories:
    • Element/types/etc.
    • Rules/terminology/etc.
    • Alterations
  • Sangressence

A single entry describing bloodessence powers and their implications on the material world (and the rules).

Admonitions

  • Help, master-help, examples
  • Important for player/master
  • Summary/TLDR
  • Example crafts

Addendums

  • Alternative rules
  • Alternative rulings
  • Ideas
  • Simplified rules (if you want to skip this section...)
  • Advenced rules

Misc

  • Centralise colour chart (module)
  • Toggle for B&W mode

Style decisions

Every style decision will be listed here for future reference, as well as Typst how-to when applicable.

Code

Code should be commented as much as possible when other contributors should be aware of any kind of information. Do not assume Tomorrow You will be able to remember (nor understand) Today You.

When code cannot be split into several sub-files, use comments to categorise when relevent, following this style:

5 dashes before and after
// ----- FULL CAPS -----

Code should be formatted using the Prettypst formatter before every commit. Here’s a reformulated version that matches the new YAML-based glossary system and explains the behavior more clearly:

Glossary

Entries

Glossary entries are defined as YAML files under /data/src/glossaries/. These files are loaded by /setup/glossary.typ through the #let glossary = read-glossary((...)) declaration. Add each entry to the appropriate glossary file/category.

A basic entry has the following structure:

- key: el_celestial
  short:
    typst: 'box(height: 0.75em, baseline: 1.1pt, inset: 0pt, image("../images/icons/sun-solid-full.svg"))'
  long: Céleste
  description: "Type de dégât élémentaire majeur."
  group: Dégâts élémentaires complexes

Fields

  • key — Unique shorthand used to reference the glossary entry.

  • custom — Optional custom metadata. The entire object is preserved and made available to the glossary system.

    • icon — If true, the glossary treats the entry's short representation as an icon and renders it using the special icon formatting.
    • Other custom fields may be added when needed.
    • alts — Optional list of alternative names or terms for the entry.
  • short — Optional short representation, typically a symbol or icon.

    • If omitted, null is inserted automatically.
    • Explicitly use short: null when you want to ensure that no short representation is used.
    • A typst field is interpreted as Typst code with the appropriate glossary context available.
    • A direct short value can also be provided; it is evaluated with eval without additional context.
  • long — Full, human-readable name of the entry. This is also the default field used for sorting.

  • description — Full description of the term, including rules or other relevant information.

  • group — Category in which the entry should appear.

  • sort — Optional manual sort key. If omitted, entries are sorted by their long value.

For example:

- key: el_celestial
  custom:
    icon: true
    alts:
      - Métabolos
  short:
    typst: 'box(height: 0.75em, baseline: 1.1pt, inset: 0pt, image("../images/icons/sun-solid-full.svg"))'
  long: Céleste
  description: "Type de dégât élémentaire majeur."
  group: Dégâts élémentaires complexes

By default, glossary entries are sorted alphabetically by their long value. Use the optional sort field when a different ordering is required.

The custom object is copied in its entirety and can therefore contain additional metadata. Some fields have special meaning to the glossary renderer; for example, custom.icon: true enables the dedicated icon rendering behavior.

Glossary files

Glossary YAML files are registered in /setup/glossary.typ through the read-glossary call:

#let glossary = read-glossary((
  "../data/src/glossaries/general.yml",
  // ...
))

To add a new glossary source, add its YAML file to this list. Entries should be placed in the YAML file corresponding to their intended glossary/category.

Shorthand

glossary shorthands should be determined thus:

a two-letter identifier of the category + _ + the full term in english
example: 
         el _ fire (el_fire)
         al _ poison (al_poison)

See the glossary categories article for help with categories identifiers.

Typography

Semicolons and other double-sign punctuation

No need to worry about them, Typst deals with the leading space correctly as non-breakable.

Lists

Lists must use the French em dash: — before every item, and end with ; until the last entry, which gets a .

Typst auto-replaces --- with —, and lists can be set up to use dashes via:

todo

Bonuses and maluses

Everywhere apart from shorthand formulas, try to clarify bonuses and maluses by repeating it explicitely, e.g. "un bonus de +2 au seuil", "malus de +1dd"

Plus and minus characters

  • + and - when used for bonuses and maluses must respectively be + (without math mode) and – (tiret semi-quadratin) typst: --
    • "Gain an additional number of dice" → +1d
    • "Threshold gets harder or easier" → malus de --2 au seuil or bonus de +5 au seuil
    • "Test gets easier" → bonus de --3dd