Part. III, ch. 6 • Macros avancées • Sommaire

Outils Lua et automatisation de ConTeXt

Objectifs de cette section
Cette page présente les outils permettant d’automatiser ConTeXt grâce à Lua et aux utilitaires intégrés. Elle explique :

comment utiliser les scripts mtxrun et les outils ConTeXt ;
comment créer des scripts Lua “externes” associés à un projet ;
comment automatiser la compilation d’un document ;
comment gérer des traitements avancés (pré-processeurs, extraction de données, nettoyage de projets) ;
comment structurer un projet ConTeXt orienté automatisation.

Outils Lua et automatisation

Lua intervient dans ConTeXt pour simplifier des tâches que TeX ne sait pas faire confortablement : calculer, analyser, transformer, filtrer ou organiser des données. Avant Lua, ces opérations devaient être effectuées soit à la main, soit avec des scripts extérieurs, sans lien direct avec la composition du document.

L’arrivée de LuaTeX a changé la situation : la version du moteur ConTeXt utilisée ici intègre Lua à l’intérieur même du processus de composition. On peut donc appeler du code Lua au moment précis où les pages se construisent. Cette proximité permet d’enrichir le document en lui donnant un certain degré d’« intelligence ».

On peut ainsi :

lire ou générer des informations pendant la compilation ;
automatiser des tâches répétitives ;
analyser des données avant de les mettre en forme ;
générer du contenu typographié depuis des fichiers externes ;
préparer des tableaux, des listes, des index, etc.

Le but de Lua n’est donc pas de remplacer TeX, mais de l’accompagner. TeX s’occupe de la mise en page ; Lua s’occupe du raisonnement. C’est cette combinaison qui permet à ConTeXt de traiter des documents complexes avec une grande souplesse.

Pourquoi Lua dans ConTeXt ?

ConTeXt s’appuie sur Lua pour une raison simple : le langage TeX n’a jamais été conçu pour gérer le calcul, la logique conditionnelle, la lecture de données, ou l’automatisation avancée. Lua devient donc le complément naturel de TeX à l’intérieur de LuaTeX.

Pour comprendre concrètement le rôle de Lua dans ConTeXt, il faut distinguer deux niveaux d’utilisation. On peut d’abord écrire du code Lua directement dans un document, pour effectuer un calcul ou produire du texte au moment de la composition. On peut aussi placer du code Lua dans des scripts externes, qui préparent ou transforment des données avant la mise en page. Dans les deux cas, Lua est relié à ConTeXt par des commandes simples : \ctxlua{...} pour insérer un résultat dans le texte, et \startluacode ... \stopluacode pour rédiger des blocs plus importants.

Cette double approche — interne et externe — explique pourquoi Lua peut servir à la fois à automatiser des projets complets et à enrichir une simple macro à l’intérieur d’un document.

Pourquoi Lua plutôt que Python, Perl ou Ruby ?

Lua a été choisi parce qu’il répond à quatre conditions déterminantes :

léger : le moteur Lua tient dans une très petite empreinte mémoire, idéale pour être embarquée directement dans TeX ;
rapide : il s’exécute sans lancer de processus externes ni ouvrir de canaux de communication ;
intégré : Lua est inclus au cœur de LuaTeX et peut manipuler directement la compilation ;
simple : syntaxe minimale, langage clair, très accessible.

Des langages comme Python ou Perl exigent des installations externes, des bibliothèques, des dépendances et des mécanismes de communication entre programmes. Lua, lui, est nativement interne à ConTeXt.

Qu’apporte Lua ?

Lua permet de :

lire, trier et transformer des données (XML, JSON, CSV, TEI) ;
automatiser des tâches (listes, index, références croisées, numérotation) ;
analyser des fichiers complets avant ou pendant la composition ;
calculer des résultats réutilisables dans des macros ;
générer dynamiquement du code ConTeXt.

Autrement dit, TeX compose, Lua organise.

Lien avec les macros ConTeXt

Les macros servent à nommer et contrôler la mise en forme. Lorsque ces macros doivent aussi décider, calculer ou analyser, Lua prend le relais. Une macro peut donc :

appeler Lua pour générer un résultat,
insérer ce résultat dans la composition,
continuer le traitement typographique.

Ce modèle rend ConTeXt particulièrement adapté aux projets complexes : éditions savantes, polyglottes, fichiers structurés, ou documents pilotés par données.

ConTeXt MkIV et LMTX reposent sur Lua. De ce fait, ConTeXt offre un environnement unique où l’on peut :

exécuter du Lua directement dans un document ;
exécuter du Lua dans un module ;
appeler des scripts Lua externes via mtxrun ;
automatiser la compilation, le nettoyage, la génération d’index ou d’annexes.

Cette page présente ces outils de manière concrète.

1. Le rôle central de mtxrun

mtxrun est le lanceur universel de ConTeXt. Il permet d’exécuter :

ConTeXt (mkiv, lmtx)
des scripts Lua internes
des scripts Lua utilisateur
des utilitaires intégrés (cache, fontloader, outils divers)

Exemples courants :

mtxrun --script context monfichier.tex
mtxrun --script cache --erase
mtxrun --script font --list --all

Pour exécuter un script Lua externe :

mtxrun --script monscript.lua

ConTeXt détecte automatiquement les scripts nommés sous la forme mtx-nom.lua, mais tout fichier Lua peut être exécuté.

2. Organisation d’un projet automatisé

Pour un projet sérieux, on recommande l’organisation suivante :

mon-projet/
│
├── tex/                      (documents maîtres, environnements, chapitres)
│   ├── main.tex              (fichier principal)
│   ├── environment.mkiv      (styles globaux du projet)
│   └── chapitre1.tex
│
├── lua/                      (scripts Lua pour automatiser le projet)
│   ├── nettoyer.lua          (suppression des fichiers temporaires)
│   ├── statistiques.lua      (analyse du texte)
│   └── exporter-tableaux.lua (génération automatique de tables)
│
├── modules/                  (modules personnalisés)
│   └── m-produit.mkiv        (définitions de commandes métiers)
│
├── data/                     (sources : CSV, JSON, TXT…)
│   └── tableau.csv
│
├── images/
│   └── schema1.pdf
│
└── outils/                   (scripts pour compiler ou automatiser ConTeXt)
    ├── compile.sh            (Linux / macOS)
    └── compile.bat           (Windows)

Ainsi :

les fichiers Lua sont regroupés ;
les modules personnalisés sont isolés ;
les scripts de compilation sont centralisés.

3. Écrire un script Lua externe pour un projet

Un script Lua externe est utile pour :

nettoyer les fichiers générés ;
analyser des logs ;
extraire des métadonnées ;
convertir des données sources (CSV → TeX) ;
générer automatiquement des tableaux ConTeXt ;
préparer une édition critique.

Exemple simple : un script qui compte les mots d’un fichier texte.

Créer lua/compteur.lua :

local f = io.open(arg[1], "r")
local texte = f:read("*all")
f:close()

local n = 0
for _ in string.gmatch(texte, "%S+") do
  n = n + 1
end

print("Nombre de mots :", n)

Exécution :

mtxrun --script compteur.lua texte.txt

4. Appeler Lua depuis ConTeXt pour automatiser une tâche

Exemple : générer une liste de fichiers présents dans un dossier.

\startluacode
local d = lfs.currentdir()
for f in lfs.dir("data") do
  if f:find("%.txt$") then
    context("Fichier trouvé : "..f.."\\par")
  end
end
\stopluacode

Explication :

lfs est LuaFileSystem, inclus dans ConTeXt ;
context() imprime le résultat dans le PDF.

C’est une manière puissante d’automatiser des rapports.

5. Utiliser Lua pour générer du code ConTeXt

Exemple : générer un tableau automatiquement.

\startluacode
local fruits = { "Pomme", "Banane", "Orange", "Fraise" }

context("\\starttabulate[|l|]")
for i, f in ipairs(fruits) do
  context("\\NC "..f.." \\NC "..i.." \\NR")
end
context("\\stoptabulate")
\stopluacode

Lua sert ici de moteur de génération.

6. Automatiser la compilation d’un document ConTeXt

Voici un script commun (Linux / macOS) :

Fichier : outils/compile.sh

#!/bin/sh
echo "Compilation du projet..."
mtxrun --script context main.tex
echo "Nettoyage..."
mtxrun --script cache --erase
echo "Terminé."

Même logique pour un fichier Windows :

compile.bat

@echo off
echo Compilation du projet...
mtxrun --script context main.tex
echo Nettoyage du cache...
mtxrun --script cache --erase
pause

Cela permet :

de compiler en un clic,
de nettoyer le cache,
d’automatiser des étapes intermédiaires.

7. Combiner un script externe et ConTeXt

Exemple plus élaboré : générer un fichier `.tex` via Lua, puis le compiler.

Script lua/genrapport.lua :

local out = io.open("rapport.tex", "w")
out:write("\\starttext\n")
out:write("Rapport généré automatiquement.\\par\n")
out:write("\\stoptext\n")
out:close()
print("Fichier rapport.tex généré.")

Puis :

mtxrun --script genrapport.lua
mtxrun --script context rapport.tex

C’est le principe des "pipelines" ConTeXt.

 
 Astuce

Placez tous vos scripts automatisés dans un dossier lua/ ou outils/. ConTeXt reconnaît automatiquement les chemins relatifs dans mtxrun.

 
 Problème courant

Si un script Lua échoue à accéder à un fichier :

vérifiez le chemin relatif (ConTeXt se place souvent dans le dossier du fichier maître) ;
vérifiez les permissions (Linux / macOS) ;
vérifiez l’encodage (UTF-8 recommandé).

 
 Avertissement

Certains scripts mtx-* de ConTeXt évoluent régulièrement. Il est recommandé d’utiliser une version LMTX récente pour les outils avancés.

◀ Page précédente : macros