Aller au contenu

ConTeXt/Modules externes

Ajouter des liens
Un livre de Wikilivres.
En travauxlink={{{link}}}

Cette page est en travaux. Tant que cet avis n'aura pas disparu, veuillez en considérer le plan et le contenu encore incomplets, temporaires et sujets à caution. Si vous souhaitez participer, il vous est recommandé de consulter sa page de discussion au préalable, où des informations peuvent être données sur l'avancement des travaux.

Objectifs de cette section
Cette page explique comment utiliser les modules externes dans ConTeXt. Elle présente :

  • ce qu’est un module dans ConTeXt ;
  • où trouver les modules officiels et tiers ;
  • comment charger un module via \usemodule ;
  • comment organiser ses modules dans un projet ;
  • comment écrire un module simple (exemple complet) ;
  • comment s’appuyer sur les modules pour étendre ConTeXt.

Modules externes dans ConTeXt

[modifier | modifier le wikicode]

Les modules ConTeXt permettent d’étendre les fonctionnalités du système en ajoutant des commandes, des environnements, des styles ou des mécanismes automatisés. Ils se présentent sous forme de fichiers .mkiv ou .mkxl, parfois accompagnés de fichiers Lua.

Les modules sont un des outils principaux pour personnaliser ou enrichir ConTeXt.

1. Qu’est-ce qu’un module ConTeXt ?

[modifier | modifier le wikicode]

Un module est un fichier externe contenant :

  • des définitions de commandes,
  • des styles,
  • des environnements,
  • parfois du code Lua,
  • des réglages pré-emballés pour un usage récurrent.

Ils sont habituellement nommés selon la convention :

  • m-xxx.mkiv → module "normal",
  • t-xxx.mkiv → module “third” (communauté).

Exemples de modules bien connus :

  • t-filter : exécuter du code externe (Python, R…)
  • m-chart : graphiques simples
  • m-bind : publication numérique
  • t-letter : style de lettre

2. Où trouver des modules ?

[modifier | modifier le wikicode]

ConTeXt reconnaît trois sources principales :

2.1 Modules officiels (intégrés dans la distribution)

[modifier | modifier le wikicode]

Ils se trouvent dans l’arborescence : tex/texmf-context/modules/

Ils sont toujours disponibles et maintenus.

2.2 Modules “third” (contributions communautaires)

[modifier | modifier le wikicode]

Ils sont disponibles sur : https://modules.contextgarden.net

Ils se chargent de la même manière qu’un module officiel.

2.3 Modules utilisateur

[modifier | modifier le wikicode]

Dans un projet, vous pouvez placer vos propres modules dans :

  • un sous-dossier modules/
  • ou au même niveau que votre environment

ConTeXt les détectera automatiquement s’ils sont dans le chemin du projet.

3. Charger un module : la commande \usemodule

[modifier | modifier le wikicode]

La commande générale est : 

\usemodule[<nom>]

Exemples : 

\usemodule[t-filter]
\usemodule[m-chart]

ConTeXt cherche automatiquement :

1. dans le projet courant 2. dans les modules utilisateur 3. dans les modules “third” 4. dans les modules officiels

4. Organisation recommandée dans un projet

[modifier | modifier le wikicode]

Pour maintenir un projet proprement on respectera une arborescence du type ci-dessous : 

mon-projet/
   modules/
      m-messtyles.mkiv
      m-figuresperso.mkiv
   environnement.mkiv
   chapitres/
   images/
   main.tex

Dans main.tex : 

\environment environnement
\usemodule[messtyles]
\usemodule[figuresperso]

5. Écrire un module simple : structure, logique et fonctionnement

[modifier | modifier le wikicode]

L’objectif de cette section est de montrer :

  • la structure interne d’un module ConTeXt,
  • comment définir des commandes et environnements réutilisables,
  • comment ConTeXt charge et active un module,
  • comment l’utiliser dans un document.

Nous allons créer un module minimal qui fournit : 1) une commande personnalisée ; 2) un environnement encadré.

Ce module n’a pas pour but d’être utile EN SOI, mais de montrer comment fonctionne le mécanisme modulaire.

5.1 Structure d’un fichier module

[modifier | modifier le wikicode]

Un module ConTeXt est un fichier nommé :

m-exemple.mkiv

Il commence par : 

\startmodule[exemple]

et se termine par : 

\stopmodule

Ces deux lignes servent à :

  • déclarer le module auprès de ConTeXt ;
  • encapsuler son contenu (définitions, réglages, Lua, etc.) ;
  • éviter que les commandes ne soient exécutées au moment du chargement des modules internes de ConTeXt.

5.2 Exemple complet de module

[modifier | modifier le wikicode]

Voici un module minimal et fonctionnel : 

\startmodule[exemple]

% 1. Une commande simple
\def\bonjour#1{Bonjour, #1 !}

% 2. Définition d'un environnement "cadre"
\definestartstop
  [cadre]
  [before={\startframed[frame=on]},
   after={\stopframed}]

\stopmodule

5.3 Pourquoi est-ce codé ainsi ?

[modifier | modifier le wikicode]
    • 1. La commande \bonjour

Elle sert simplement à illustrer une commande personnalisée. 

\def\bonjour#1{Bonjour, #1 !}

Ici :

  • \def crée une nouvelle commande ;
  • #1 représente l’argument ;
  • "Bonjour, X !" est inséré tel quel dans le texte.

Le module sert donc de réservoir de commandes.

---

    • 2. L’environnement "cadre"
\definestartstop
  [cadre]
  [before={\startframed[frame=on]},
   after={\stopframed}]

Cet environnement permet d’écrire : 

\startcadre
Du texte dans un cadre simple.
\stopcadre

Ce mécanisme repose sur :

  • \definestartstop, l’interface ConTeXt pour créer des environnements ;
  • before= : ce qui est exécuté au début ;
  • after= : ce qui est exécuté à la fin.

Ici, l’environnement encapsule son contenu dans un cadre visuel.

5.4 Comment ConTeXt « active » le module ?

[modifier | modifier le wikicode]

Lorsqu’un module est appelé par : 

\usemodule[exemple]

ConTeXt :

  • 1. recherche un fichier nommé m-exemple.mkiv
  • 2. charge le fichier, mais n’exécute rien en dehors des définitions
  • 3. met à disposition les commandes définies dans ce module
  • 4. prévient les autres composants que ce module est actif

ConTeXt reconnaît automatiquement la syntaxe `m-` et `t-` comme des préfixes de module.

5.5 Comment utiliser ce module dans un document ?

[modifier | modifier le wikicode]
\usemodule[exemple]

\bonjour{Hans}

\startcadre
Voici un texte encadré grâce au module.
\stopcadre

Le résultat :

  • “Bonjour, Hans !” est affiché
  • un cadre apparaît autour du texte entre \startcadre ... \stopcadre

5.6 Quel est le but d’un tel module ?

[modifier | modifier le wikicode]

Cet exemple est volontairement simple, mais il illustre la logique réelle d’un module ConTeXt :

  • factoriser des commandes, styles ou environnements récurrents ;
  • organiser des outils propres à un projet (microsyntaxe, styles graphiques, structures) ;
  • rendre un projet plus propre, plus lisible, mieux structuré ;
  • séparer la logique (module) du contenu (document) ;
  • réutiliser facilement les mêmes mécanismes dans plusieurs documents.

Ce modèle est le même que pour :

  • les modules officiels (`m-…`)
  • les modules communautaires (`t-…`)
  • les modules utilisateur dans un dossier `modules/`

6. Modules combinant ConTeXt et Lua : logique, structure et fonctionnement

[modifier | modifier le wikicode]

Les modules ConTeXt peuvent également contenir du code Lua. C’est une des forces de ConTeXt MkIV/LMTX : Lua est intégré nativement et permet d’automatiser ou d'étendre le langage TeX.

L’idée générale est simple :

  • Lua sert à calculer, traiter, analyser, transformer ;
  • ConTeXt sert à mettre en page et afficher le résultat.

Par exemple, Lua peut :

  • lire et écrire des fichiers ;
  • générer du texte automatiquement ;
  • manipuler des listes, tableaux, dates, données ;
  • préparer des index ou glossaires ;
  • produire des structures que ConTeXt composera ensuite.

Nous allons construire un module minimal qui illustre ce mécanisme. Ce module n’a pas d’utilité pratique : son rôle est de montrer la mécanique interne TeX → Lua → TeX.

6.1 Structure du module combinant Lua et ConTeXt

[modifier | modifier le wikicode]

Créez un fichier nommé :

m-moutil.mkiv

avec le contenu suivant : 

\startmodule[moutil]

% --- Partie Lua du module ---
\startluacode
-- Le tableau 'outil' sert d'espace de noms
outil = outil or {}

-- Une fonction Lua simple : renverser une chaîne de caractères
function outil.reverse(s)
  return string.reverse(s)
end
\stopluacode

% --- Partie ConTeXt du module ---
% Une commande ConTeXt qui utilise la fonction Lua
\def\Reverse#1{%
  \ctxlua{context(outil.reverse("#1"))}%
}

\stopmodule

Ce module contient deux éléments importants :

1. Une fonction Lua 

  `outil.reverse(s)` renverse une chaîne de caractères.

2. Une commande ConTeXt 

  `\Reverse{...}` appelle cette fonction Lua et affiche le résultat.

6.2 Explication détaillée du code

[modifier | modifier le wikicode]

Voici comment fonctionne chaque composant.

a) Le bloc Lua

[modifier | modifier le wikicode]
\startluacode
outil = outil or {}
function outil.reverse(s)
  return string.reverse(s)
end
\stopluacode
  • \startluacode / \stopluacode
 exécutent du Lua au moment du chargement du module.
  • outil = outil or {}
 crée un tableau Lua qui joue le rôle d’"espace de noms" (comme un module Lua interne).
  • function outil.reverse(s)
 définit une fonction prenant une chaîne `s` en argument.
  • string.reverse(s)
 renvoie la chaîne `s` renversée (fonction Lua standard).

b) La commande ConTeXt qui appelle Lua

[modifier | modifier le wikicode]
\def\Reverse#1{%
  \ctxlua{context(outil.reverse("#1"))}%
}

Ici :

  • \Reverse{texte}
 est la commande que l’utilisateur invoquera dans le document.
  • \ctxlua{...}
 permet d’exécuter du Lua en insérant le résultat dans la page.
  • context(...)
 est la manière dont Lua “imprime” du texte dans la sortie PDF.

Autrement dit :

  • → ConTeXt passe une valeur à Lua,
  • → Lua la transforme,
  • → Lua renvoie le résultat à ConTeXt,
  • → ConTeXt l’insère dans le document.

---

6.3 Utilisation du module dans un document

[modifier | modifier le wikicode]
\usemodule[moutil]

\Reverse{ConTeXt}   % Produit : txeTnoC

Explication :

  • \usemodule[moutil]
 charge le fichier `m-moutil.mkiv`.
  • \Reverse{ConTeXt}
 appelle Lua → exécute `outil.reverse("ConTeXt")` → affiche `txeTnoC`.

Ce mécanisme est le même que dans les modules plus complexes utilisés pour :

  • générer des tableaux automatiquement,
  • lire un fichier de données CSV,
  • créer des index personnalisés,
  • transformer du texte selon des règles,
  • automatiser des traitements lourds.

---

💡 Astuce
Toujours grouper les fonctions Lua dans une table (comme outil). Cela évite les conflits de noms et permet de réutiliser facilement le même espace de fonctions dans d’autres documents.

⚠ Problème courant
Si vous obtenez une erreur du type : attempt to index a nil value (outil) Cela signifie que :

  • la table outil n’a pas été créée,
  • ou que Lua a été exécuté avant la définition du module.

Assurez-vous que votre fonction Lua est bien dans un bloc \startluacode.

⚠ Avertissement
Dans un module, évitez d’utiliser des variables Lua globales sans les ranger dans une table dédiée. Cela pourrait provoquer des conflits avec d’autres modules ou avec ConTeXt lui-même.


⚠ Avertissement
Les modules communautaires “third” sont parfois anciens et non maintenus. Testez-les dans un petit projet avant de les intégrer dans un document important.

Récupérée de "https://fr.wikibooks.org/w/index.php?title=ConTeXt/Modules_externes&oldid=755104"