Meta

Conventions transverses de documentation Catnip, destinées aux lecteurs humains comme aux agents IA.

Conventions dans les snippets

• # → ... : assertion attendue sur le résultat d'une expression dans un exemple.
• # ← ... : entrée utilisateur (input) dans un simulateur de terminal.

Exemples :

2 + 2
# → 4

# ← 1 + 1
2
# → 2

Notes :

• Ce ne sont pas des instructions exécutées, mais des marqueurs de validation visuelle.
• Garder la forme courte et factuelle.
• En cas de résultat long, préférer un extrait représentatif plutôt qu'un dump complet.
• # RUN: ... est un tag documentaire et de validation, pas un shebang ; il peut être exploité hors shell (ex: validateur/doc runner).
• # FILE: ..., /* FILE: ..., # TAGS: ... métadonnées de catalogage internes, sans sémantique langage.

Typographie

Le deux-points est précédé d'une espace insécable (U+00A0), comme le veut la typographie française. Ce n'est pas qu'une question de justesse : le reformatage replie les paragraphes à 120 colonnes, et une espace ordinaire l'autorise à couper juste avant le deux-points. La ligne suivante commence alors par :, ce qui est la syntaxe des listes de définition — le renderer lit la ligne d'au-dessus comme un terme au lieu de poursuivre la phrase.

Rien à faire à la main : dev/doc_format.py pose l'espace, sur docs/ comme sur wip/, et il tourne avant le reformatage. Les blocs de code et le code inline en sont exclus, une annotation de type (x : int) n'étant pas de la prose.

Intention

• Réduire les ambiguïtés de lecture.
• Expliciter les choix documentaires volontaires.
• Donner un référentiel unique pour toute la doc.

Scope

• S'applique à l'ensemble de docs/, sauf mention contraire dans une page locale.
• La règle typographique porte plus loin, l'outil qui l'applique couvrant aussi les notes internes.