julien/lescarnetsdakkadien.netig.net

0 Fork 0

Files

T

julien 4c9e1f5f66 Python to Ruby

2026-09-30 14:27:05 +02:00

15 KiB

Raw Blame History

Guide de rédaction

Ce guide décrit la création, la mise à jour et la publication des fiches du site Les Carnets d’Akkadien.

Le principe est le suivant :

le front matter TOML contient les données courtes et structurées ;
le corps Markdown contient les explications, exemples, tableaux et commentaires ;
tous les champs prévus par le modèle restent présents, même lorsqu’ils sont vides ;
les valeurs vides sont généralement omises du rendu.

Toutes les commandes sont exécutées depuis la racine du dépôt.

Périmètre des outils

Les fiches se trouvent dans cinq sections :

Type	Répertoire	Taxonomie
Article	`src/content/articles/`	aucune
Grammaire	`src/content/grammaire/`	`themes`
Signe	`src/content/signes/`	`lectures`
Texte	`src/content/textes/`	`genres`
Vocabulaire	`src/content/vocabulaire/`	`natures`

Les fichiers _index.md définissent les sections et restent maintenus manuellement. Les pages autonomes placées directement dans src/content/, comme la bibliographie et les mentions légales, ne sont ni créées, ni horodatées, ni validées par les scripts de fiches.

Les commandes publiques sont :

new-content.rb : création d’un brouillon ;
update-content.rb : mise à jour de l’horodatage updated ;
check-content.rb : validation des noms et de la structure des fiches.

schema.rb est leur module commun et ne se lance pas directement.

Cycle de rédaction

créer un brouillon avec new-content.rb ;
compléter les données et le corps Markdown ;
contrôler son rendu avec les brouillons ;
passer draft à false lorsqu’il est prêt ;
exécuter les validations et construire la version publique ;
après une modification substantielle ultérieure, actualiser updated.

Pendant la rédaction :

zola --root src serve --drafts

Avant publication :

./scripts/check-content.rb
zola --root src check --drafts
zola --root src build --drafts
zola --root src build

zola check contrôle le chargement du site et ses liens. Les deux constructions suivantes vérifient réellement le rendu de tous les brouillons, puis celui de la version publique. En l’absence d’accès réseau, ajouter --skip-external-links à la commande zola check.

Créer une fiche

Syntaxe générale :

./scripts/new-content.rb SECTION IDENTIFIANT [--nature NATURE] [--title TITRE]

Exemples :

./scripts/new-content.rb vocabulaire šarrum --nature nom
./scripts/new-content.rb vocabulaire epēšum --nature verbe
./scripts/new-content.rb vocabulaire --nature particule -- -ma
./scripts/new-content.rb signes 113 --title BE
./scripts/new-content.rb grammaire suffixes-pronominaux
./scripts/new-content.rb textes lettre-au-marchand
./scripts/new-content.rb articles nouvel-article

Pour le vocabulaire, les natures reconnues sont :

nom, adjectif, verbe, pronom, préposition,
adverbe, conjonction, particule, numéral

Pour une fiche de vocabulaire, --nature est obligatoire. Ce choix explicite garde le générateur simple et prévisible.

Le générateur :

normalise l’identifiant et le titre en Unicode NFC ;
crée tous les champs prévus par le modèle ;
initialise la fiche comme brouillon ;
refuse d’écraser un fichier existant ;
ne renseigne aucune donnée linguistique et ne rédige pas le corps Markdown.

Le titre est déduit de l’identifiant pour les articles, la grammaire et les textes. Pour le vocabulaire, il reprend l’identifiant. Pour un signe, il reste vide sauf si --title est fourni.

Conventions générales

Période et terminologie

Le site est principalement consacré au paléo-babylonien. Toute forme, graphie ou analyse relevant d’une autre période ou d’un autre dialecte est signalée dans la fiche concernée.

Les clés du front matter sont en anglais. Les taxonomies portent des noms français. Les lectures conservent exactement leur translittération.

Unicode et translittération

Les sources sont enregistrées en UTF-8 et utilisent la normalisation Unicode NFC. Les lemmes, lectures et formes akkadiennes conservent leurs diacritiques :

bītum
parāsum
aš
ṭim

Dans le corps Markdown, les formes linguistiques sont généralement écrites en italique. Le code en ligne sert aux commandes, chemins et noms de champs.

Identifiants et noms de fichiers

Pour les articles, la grammaire, les textes et le vocabulaire, l’identifiant devient le nom du fichier. Il doit être fourni sans extension et respecter les règles suivantes :

minuscules uniquement ;
aucun espace ni underscore ;
lettres Unicode, chiffres et tirets seulement ;
aucun double tiret ni tiret final.

Exemples :

src/content/vocabulaire/bītum.md
src/content/vocabulaire/parāsum.md
src/content/grammaire/forme-liee.md
src/content/articles/les-carnets-sont-en-ligne.md

Un tiret initial est accepté uniquement pour le vocabulaire, par exemple -ma.md.

Les signes utilisent un numéro MZL compris entre 1 et 999. Le générateur produit automatiquement un nom sur trois chiffres :

src/content/signes/mzl-001.md
src/content/signes/mzl-113.md
src/content/signes/mzl-167.md

Zola utilise la stratégie de slugification safe, afin de conserver notamment la distinction entre tim et ṭim.

Taxonomies

Les taxonomies publiques sont :

natures pour le vocabulaire ;
lectures pour les signes ;
themes pour la grammaire ;
genres pour les textes.

Une fiche de vocabulaire contient exactement une nature reconnue, car elle détermine son modèle de champs. Les autres taxonomies peuvent contenir plusieurs termes.

Dans themes et genres, les termes composés utilisent des tirets :

natures = ["préposition"]
lectures = ["tim", "ṭim"]
themes = ["morphologie-nominale"]
genres = ["inscription-commémorative"]

Conserver la syntaxe simple générée pour les tableaux de taxonomie : une seule ligne, avec les chaînes entre guillemets doubles. Le validateur minimal lit notamment natures sous cette forme (natures = ["nom"]).

Les templates rétablissent les espaces à l’affichage, tandis que les URL restent sans espace :

/themes/morphologie-nominale/
/genres/inscription-commémorative/

La graphie d’un terme doit rester stable après sa publication.

Front matter commun

Chaque fiche créée par le générateur commence par :

title = "Titre"
date = 2026-08-06T12:30:00+02:00
# updated = YYYY-MM-DDTHH:MM:SS+HH:MM
description = ""
draft = true

title : titre affiché ;
date : horodatage initial et date de publication ;
updated : dernière modification substantielle ;
description : résumé court facultatif ;
draft : état de publication.

date et updated sont des horodatages TOML sans guillemets, produits dans le fuseau Europe/Paris. Chaque fiche doit conserver exactement une ligne updated, commentée ou active.

Pour actualiser une fiche :

./scripts/update-content.rb src/content/vocabulaire/bītum.md

La forme relative à src/content/ est également acceptée :

./scripts/update-content.rb vocabulaire/bītum.md

Le script refuse les index, les pages autonomes et les chemins extérieurs aux cinq sections. Il remplace l’unique ligne updated par l’heure courante :

updated = 2026-08-06T16:47:00+02:00

Sur la page d’accueil, updated prime sur date pour le classement des trois fiches récentes. Il ne doit donc être activé qu’après une modification substantielle.

Descriptions automatiques

Lorsque description reste vide :

une fiche de vocabulaire affiche un résumé construit à partir de sa nature, de son genre et de son sens ;
une fiche de signe affiche son titre et son numéro MZL ;
les autres fiches n’affichent pas de résumé de remplacement dans leur contenu.

Les mêmes résumés automatiques servent de métadescription aux fiches de vocabulaire et de signes. Pour les autres pages sans description spécifique, le template utilise la description générale du site.

Une description manuelle reste préférable lorsqu’elle apporte une information plus précise, notamment pour les articles, la grammaire et les textes.

Brouillons

Un brouillon peut conserver des valeurs vides, mais tous les champs de son modèle restent présents. Pour publier une fiche :

compléter les informations disponibles ;
rédiger le corps Markdown ;
vérifier la date souhaitée ;
remplacer draft = true par draft = false ;
exécuter les contrôles du cycle de rédaction.

Une fiche publiée peut repasser temporairement à draft = true.

Modèles de contenu

Les tables suivantes viennent après les champs communs, dans le même front matter délimité par +++.

Vocabulaire

Toutes les fiches lexicales contiennent au minimum :

[extra]
meaning = ""
logograms = []

[taxonomies]
natures = ["nature"]

meaning contient le sens principal ou une courte série de sens. logograms est toujours un tableau de chaînes :

logograms = ["LUGAL"]

Chaque nature ajoute les champs suivants :

Nature	Champs supplémentaires
Nom	`gender`, `bound`, `plural`
Adjectif	`bound`, `feminine`, `masculine_plural`, `feminine_plural`, `predicative`
Verbe	`root`, `stem`, `verb_class`, `vowel_class`, `preterite`, `durative`, `perfect`, `imperative`, `participle`, `verbal_adjective`
Pronom	`pronoun_type`, `person`, `gender`, `number`
Préposition	`governs`
Adverbe	`function`
Conjonction	`function`
Particule	`function`
Numéral	`numeral_type`, `value`, `gender`, `feminine`

Tous les champs simples sont des chaînes, même lorsqu’ils sont vides. Pour un verbe, le titre fournit déjà l’infinitif et celui-ci n’est pas répété dans [extra].

Principaux champs :

gender : genre grammatical ;
bound : forme liée ;
plural : pluriel lexical ;
predicative : forme affichée comme « Prédicatif (3 m. s.) » ;
root : racine, par exemple p-r-s ;
stem : thème verbal, par exemple G, D, Š ou N ;
verb_class : classe morphologique, par exemple fort, I-n ou III-faible ;
vowel_class : classe vocalique, par exemple a/u ;
pronoun_type : type de pronom ;
governs : cas régi par une préposition ;
function : fonction d’un adverbe, d’une conjonction ou d’une particule ;
numeral_type : cardinal, ordinal ou autre type ;
value : valeur numérique.

Le corps Markdown reste libre. Rubriques possibles :

## Emploi
## Morphologie
## Déclinaison
## Thèmes dérivés
## Occurrences
## Voir aussi
## Sources

Signes

Commande :

./scripts/new-content.rb signes 113 --title BE

Champs propres :

[extra]
sign = ""
mzl = "113"

[taxonomies]
lectures = []

le fichier est nommé mzl-113.md ;
title contient le nom usuel du signe ;
sign contient le caractère cunéiforme Unicode ;
mzl contient les trois chiffres du numéro ;
lectures contient les lectures translittérées.

Le validateur vérifie la présence et le type de ces champs, mais ne compare pas mzl au nom du fichier.

Rubriques possibles :

## Valeurs syllabiques
## Emplois logographiques
## Emploi comme déterminatif
## Variantes graphiques
## Notes

Le corps peut rester vide lorsque le front matter suffit.

Grammaire

[taxonomies]
themes = []

themes regroupe les fiches par notion grammaticale. Le corps est organisé librement selon le sujet.

Textes

[taxonomies]
genres = []

genres décrit le type documentaire, par exemple lettre ou inscription-commémorative.

Structure possible :

## Présentation
## Translittération
## Normalisation
## Traduction
## Commentaire philologique
## Vocabulaire

Articles

[extra]
banner = ""
banner_alt = ""
banner_credit = ""

description est affichée dans la liste des articles, sur l’accueil et dans la page ;
banner est un chemin relatif à src/static/, par exemple images/articles/article.webp ;
banner_alt contient le texte alternatif ;
banner_credit contient une attribution ou une légende facultative.

Lorsque banner est vide, aucune image n’est générée. Lorsqu’il est renseigné, le template lit les dimensions du fichier avec Zola et les ajoute au HTML. Une image informative doit avoir un texte alternatif utile ; une image purement décorative peut utiliser une chaîne vide.

Markdown et ressources

Liens internes

Les liens vers d’autres contenus utilisent la syntaxe interne de Zola :

[Voir bītum](@/vocabulaire/bītum.md)
[Voir la forme liée](@/grammaire/forme-liee.md)

Ils sont ajoutés lorsqu’ils apportent un contexte réel : occurrence dans un texte, exemple grammatical, signe observé ou relation lexicale utile.

Blocs de code

Un bloc délimité par trois accents graves et associé à une langue reçoit automatiquement la coloration syntaxique :

```ruby
puts "šulmu"
```

Zola génère giallo.css, tandis que le HTML rendu utilise les classes correspondantes. Cette feuille est produite pendant la construction et ne doit pas être modifiée ou ajoutée aux sources.

Ce que contrôle le validateur

check-content.rb contrôle uniquement les fiches des cinq sections. Il ignore les fichiers _index.md et les pages placées directement dans src/content/.

Pour chaque fiche, il vérifie :

le nom de fichier en Unicode NFC ;
les identifiants en minuscules avec lettres Unicode, chiffres et tirets ;
la forme mzl-NNN.md pour les signes ;
la présence d’un front matter délimité par +++ ;
la présence des champs communs title, date, description et draft ;
exactement une ligne updated, commentée ou active ;
pour le vocabulaire, une nature grammaticale reconnue et les champs [extra] attendus ;
pour les autres sections, les champs propres à leur modèle.

Le validateur Ruby reste volontairement simple : il ne réimplémente pas un parseur TOML et ne contrôle pas les types de toutes les valeurs. Zola reste responsable de la syntaxe TOML, des liens, des taxonomies et des templates. Cette séparation évite toute dépendance Ruby supplémentaire.

Le générateur et le validateur appliquent les mêmes conventions de nommage. Le générateur produit des squelettes complets ; le validateur vérifie surtout qu’aucun champ structurel n’a disparu.

Vérification avant publication

Avant de publier ou déployer :

conserver tous les champs du modèle, même vides ;
conserver exactement une ligne updated ;
utiliser draft = false uniquement pour un contenu prêt ;
utiliser des tirets dans les thèmes et genres composés ;
éviter les rubriques vides et les textes d’attente ;
lancer update-content.rb seulement après une modification substantielle ;
exécuter le validateur, zola check, la construction avec brouillons, puis la construction publique.

15 KiB Raw Blame History Unescape Escape