Obtenir le jeu de cartes¶

Introduction¶

Le projet est hébergé sur un dépôt Git et est publiquement disponible à l'adresse suivante : La Fresque des deux Infinis

Ce dépôt contient tous les fichiers et ressources nécessaires pour construire et contribuer au projet.

Le projet présente l'architecture suivante :

.
├── .vscode # Configuration files for Visual Studio Code
├── cards-fr # Description of the cards in French
├── cards-en # Description of the cards in English
├── illustrations # Directory containing language-independent illustrations for the different themes of the cards
│   ├── kind-electromagnetism-scale
│   ├── kind-information
│   ├── kind-open-question
│   ├── kind-science
│   ├── kind-science-fiction
│   ├── kind-scientific-instrument
│   ├── kind-scientist
│   ├── kind-technology
│   └── kind-universe-scale
├── illustrations-original # Directory containing original illustrations used to create the illustrations on the cards
├── illustrations-tikz # Directory containing the TikZ source code to generate certain illustrations of the cards upstream of the card preparation
├── inputs # Directory containing icons and LaTeX configuration style files
├── join-masters # Directory containing LaTeX files to assemble the cards: printing, language comparisons, etc.
├── src # Useful Python scripts to generate the cards in different formats and generate derived card formats
├── .gitignore
├── main-cards-for-creation.tex # Master file to create the cards: quick compilation of the cards
├── main-cards-to-printer.tex # Master file to prepare the cards in their final format: final appearance of the cards with layout guide lines
├── script-cards-to-printer-fullGame.tex # Master file to prepare the cards for the "fullGame" set
├── script-cards-to-printer-quizGame.tex # Master file to prepare the cards for the "quizGame" set
├── script-install.sh
└── switch-language.sh

Prérequis pour construire le projet¶

Une installation TeX récente (TeX Live), si possible celle de l'année en cours. La compilation fera appel à des packages plutôt récents.
Une installation python (version 3) avec la bibliothèque pypdf. Il vous faudra peut-être créer un environnement virtuel de travail python dans le dossier src/.
Le logiciel gnuplot est utilisé pour générer certaines illustrations.
Le logiciel ImageMagick est utilisé par un script python pour générer des versions bitmap des cartes (optionnel).
Un logiciel d'édition d'images si vous créez des illustrations (optionnel).

Construire le projet¶

Pour construire le projet, suivez ces étapes :

1. Clonez le dépôt en utilisant la commande :

git clone https://gitlab.in2p3.fr/infinitycanvas/infinity-canvas.git

2. Accédez au répertoire du projet :

cd [Insérez le nom du répertoire du projet ici]

3. Vous devez sélectionner la langue que vous souhaitez utiliser pour le projet. Les langues disponibles pour l'instant sont :

Anglais (en)
Français (fr)

Pour changer la langue, vous pouvez utiliser le script python suivant en spécifiant la langue souhaitée :

cd src/
python switch-language.py --lang=[en|fr]

Le script python prépare des dossiers de travail dans la racine du projet.

Il n'est pas nécessaire d'exécuter un de ces scripts à chaque fois que vous construisez le projet, car le paramètre de langue est enregistré dans un fichier de configuration (fichier input/version-cards.tex). Si vous souhaitez changer la langue, vous devez exécuter un de ces scripts à nouveau ou modifier directement ce fichier.

Si aucun argument n'est fourni pour le script shell, ce script essaiera de détecter la langue du système d'exploitation. Si la langue détectée n'est pas prise en charge, il basculera par défaut sur l'anglais.

Le fichier maître main-cards-for-creation.tex est conçu pour travailler sur les textes des cartes : la mise en forme est minimale, ce qui permet une compilation relativement rapide des cartes et donc une production plus rapide.

Le fichier maître main-cards-to-printer.tex permet d'obtenir une mise en forme des cartes, avec des lignes (pointillés rouges) pour montrer les cadres des éléments. Tout débordement peut ainsi être répéré et corrigé.

4. La construction des cartes requière plusieurs étapes.

Toutes les étapes peuvent être exécutées par un seul script

cd src/
python build-project.py --lang=xx [--illustrations=[true|false]] [--to-printer-files=[true|false]] [--crop-versions=[true|false]]

où xx est une des langues données dans la variable AVAILABLE_LANGS du fichier src/configuration.py. Ce script génère tout le contenu des cartes dans la langue xx en utilisant le script create-pdf-files-cards.py.

L'option --illustrations (par défaut true) permet de générer en amont les illustrations TikZ dans la langue en utilisant le script create-tikz-illustrations.py.
L'option --to-printer-files (par défaut true) permet de créer en aval les fichiers prêts à être utilisés pour l'impression, en utilisant le script create-pdf-files-print.py.
L'option --crop-versions (par défaut true) permet de créer en aval des versions pdf des cartes sans marges et traits d'impression, en utilisant le script create-pdf-crop-cards.py.

Les fichiers générés par ces scripts sont regroupés dans des sous dossiers d'un dossier _cards-production-xx.

Attention, ce script prend plusieurs heures pour produire tous les fichiers.

Voici les étapes suivies par ce script, qu'il est possible de lancer les unes après les autres.

Génération des illustrations produites par TikZ.

cd src/
python create-tikz-illustrations.py --lang=[en|fr|all] [--move[true|false]] [--picture name-of-illustration-1 name-of-illustration-2 …]

L'option --lang permet de générer les illustations dans une langue spécifique ou pour toutes les langues (option all).
L'option --move vaut par défaut false. Dans ce cas le script produit les fichiers pdf des illustrations, les renomme correctement (avec les noms utilisés dans les appels de création des cartes) et les regroupe dans le dossier illustrations-tikz/_PRODUCED-IMAGES. Avec la valeur true, le script copie en plus ces fichiers dans les dossiers utilisés pour la création des cartes.

Par défaut, le script prépare toutes les images. Si une liste de noms d'illustrations (nom du dossier, qui est aussi le nom du fichier tex) est fournie grâce à l'option --picture, le script ne génère que ces illustrations. Cela permet de mettre à jour rapidement une ou plusieurs illustrations sans avoir à tout recomposer.

Certaines illustrations nécessitent le logiciel gnuplot, qu'il faut donc installer auparavant.

Le fichier illustrations-tikz/_data.json contient les configurations de création des illustrations : moteur LaTeX utilisé (pdflatexou xelatex), usage de gnuplot ou non, nombre d'illustrations à produire, dossier de destination pour la création des cartes. Ce fichier n'est à modifier que si une nouvelle illustration est ajoutée ou si un changement majeur est effectué sur un fichier tex de création d'une illustration.

Une fois les illustrations produites par TikZ, la création des cartes est possible si les fichiers pdf sont placés correctement dans les dossiers d'appel (automatique avec l'option --move=true).

Construction des fichiers pdf des cartes.

cd src/
python create-pdf-files-cards.py --lang=[en|fr]

Ce script crée les dossiers contenant les fichiers produits : ces dossiers sont nommés en fonction de la langue. Le script lance les compilations LaTeX nécessaires à la création des fichiers pdf des recto et verso des cartes, avec leurs marges et traits de découpe.

Constructions de fichiers pour impression.

cd src/
python create-pdf-files-print.py --lang=[en|fr]

Ce script crée des fichiers d'input et compile des fichiers LaTeX dans le dossier join-masters pour créer des fichiers pdf prêts à être imprimés en recto-verso. Ces fichiers présentent les cartes dans différentes dispositions (une ou plusieurs cartes par page).

Étape optionnelle : autres formats de sortie.

cd src/
python create-pdf-crop-cards.py --lang=[en|fr]

Ce script permet de créer des fichiers pdf des contenus des cartes (recto et verso) sans les marges de découpe.

cd src/
python create-bitmap-cards.py --lang en fr --conversion aaa bbb

Ce script permet de créer des versions bitmap des cartes pour les langues et les types de conversion (voir PIXEL_CONVERTIONS dans configuration_bitmap.py)

Le script src/create-pdf-crop-cards.py utilise la bibliothèque pypdf qu'il faut installer au préalable. Il peut être nécessaire de créer dans src/ un environnement virtuel python. Le script src/create-bitmap-cards.py utilise ImageMagick qu'il faut installer par ailleurs. Le fichier src/config_local_template.py doit être utilisé pour créer un fichier src/config_local.py configurant le chemin à l'exécutable magick.

Le fichier src/configuration.py contient diverses configurations de ces scripts python.

Comment contribuer¶

Contribuer au projet est simple. Suivez ces étapes :

1. Forkez le dépôt
Commencez par forker le dépôt sur votre propre compte Git. Cela vous permet de faire des modifications sans affecter le projet principal. En forkant le dépôt, vous acceptez de respecter l'accord de licence du projet.

2. Apportez vos modifications
Après avoir forké, clonez votre dépôt forké sur votre machine locale :

git clone [Insérez l'URL du dépôt forké ici]

3. Apportez les modifications nécessaires à la base de code.

4. Validez vos modifications
Une fois vos modifications terminées, validez-les dans votre dépôt forké :

git add .
git commit -m "Décrivez vos modifications ici"
git push origin [Insérez le nom de la branche ici]

5. Faire une Merge Request
Soumettez une demande de fusion (pull request) au dépôt principal. Assurez-vous que votre demande de fusion inclut une description claire des modifications apportées et de leur nécessité.

Ajouter de nouvelles langues¶

Pour ajouter une nouvelle langue au projet, suivez ces étapes :

1. Forkez le dépôt
Commencez par forker le dépôt sur votre propre compte Git. Cela vous permet de faire des modifications sans affecter le projet principal. En forkant le dépôt, vous acceptez de respecter l'accord de licence du projet.

2. Processus de traduction des contenus des cartes

Modifiez le fichier src/AI-prompt-example.txt pour demander à l'IA de traduire dans la langue cible. À partir de ce texte modifié, créer un fichier data/AI-prompt-ss-xx.txt où ss est la langue source et xx est la langue cible (codes à deux lettres). Lancer ensuite le script python :

cd src/
python prepare-translation.py --lang-source=ss --lang-target=xx

Le choix de la langue source est libre. Il est préférable d'utiliser l'anglais car les IA sont bien entrainées à traduire à partir de l'anglais. Le script python crée les dossiers nécessaires au processus de traduction et le dossier de destination final cards-xx. Aucun script ne modifiera ce qui sera dans cards-xx, afin de préserver toute modification humaine réalisée à cet endroit. Il est donc possible de lancer plusieurs fois le processus de traduction sans perdre un travail déjà accompli dans cards-xx.

Le dossier _translation-process/1-to-be-translated contient des fichiers txt pour chaque carte. Ces fichiers peuvent être fournis à une IA directement : ils contiennent le prompt défini dans data/AI-prompt-ss-xx.txt et le contenu de la carte courante dans la forme décrite par le prompt.

Une fois que l'IA a produit les traductions, il faut sauver chaque traduction dans le dossier _translation-process/2-translated-texts avec les noms d'origine.

Une fois ces fichiers produits, il faut lancer le script :

cd src/
python create-cards-files-from-translation.py

qui produira dans le dossier _translation-process/3-cards-after-translation les fichiers LaTeX pour la production des cartes. Pour utiliser ces fichiers, il faut les copier dans le dossier cards-xx (le script ne le fera pas, au cas où des fichiers anciens existent déjà dans cards-xx).

Il faut créer aussi dans cards-xx une copie d'un fichier localized-strings.tex(à prendre dans cards-ss). Ce fichier doit être modifié pour la langue xx : option du package babel, options du package siunitx, ajout de macros LaTeX spécifiques à la langue xx si nécessaire, textes pour décrire les types de cartes. Un point important concerne les noms des types des cartes (macros \typeText____) ainsi et surtout que les noms des lots des cartes science (macros \typePack____) car ces noms vont apparaître sur les cartes. La longueur de ces noms peut avoir une influence sur le rendu des cartes.

Il faut ajouter la nouvelle langue xx aux scripts. Modifiez le script switch-language.sh pour inclure l'option de la nouvelle langue. Ajoutez un cas pour la nouvelle langue dans le script afin de gérer correctement le changement de langue. Pour les scripts python de création de cartes et des illustrations, il faut mettre à jour la variable AVAILABLE_LANGS dans src/configuration.py.

Une fois ces fichiers mis en place dans cards-xx, il est possible de compiler les cartes avec les fichiers maîtres main-cards-for-creation.tex et main-cards-to-printer.tex. La traduction fournie par une IA n'est pas toujours optimale en termes de taille des textes sur les cartes et de vocabulaire utilisé. Le traducteur devra donc travailler sur chaque carte pour améliorer la traduction.

La commande \linkWithCard permet de structurer les liens logiques entre les cartes. Le premier argument est une liste de labels de cartes cibles. Le second argument est un texte qui s'insère dans le texte ambiant. Ce texte doit être vérifié de façon attentive par le traducteur, car il doit mentionner au mieux les mots clés utilisés dans les titres des cartes cibles. Après chaque compilation, à la fin du pdf du fichier maître main-cards-to-printer.tex, le traducteur trouvera, pour chaque carte cible, une liste de ces textes utilisés dans des cartes sources. Son devoir est d'uniformiser au mieux ces textes avec le titre de la carte cible. C'est important car les participants à l'atelier vont utiliser ces textes pour repérer par eux-même les liens entre les cartes. Il s'agit donc d'un élément très structurant de l'atelier.

La traduction ne prend pas en compte les données de date des cartes, et il ne modifie pas non plus les appels aux illustrations qui dépendent de la langue (suffixe _xx dans le nom de certaines illustrations). Le traducteur devra donc modifier à la main ces dates et créer les illustrations traduites.

3. Processus de traduction des illustrations

Puisque les appels aux fichiers des illustrations ne sont pas modifiés automatiquement, la compilation LaTeX des cartes à l'aide des fichiers produits jusqu'à présent fonctionnera, mais avec les illustrations de la langue ss. Cela permet de traduire les illustrations les unes après les autres sans bloquer les tests de production.

Tous les fichiers d'illustrations utilisés pour créer les cartes sont dans des sous dossiers de illustrations. C'est donc à cet endroit qu'il faut regarder ce qui nécessite une traduction.

Les illustrations à traduire sont produites en TikZ. La procédure de traduction de ces illustrations est prévue et se déroule dans le dossier illustrations-tikz. Chaque illustration est produite par un fichier LaTeX dans un dossier spécifique (les noms du dossier et du fichier tex doivent être les mêmes). Le dossier COMMONS contient des fichiers des textes des illustrations sous les noms common-texts-ss.tex. Il faut traduire les contenus des macros définies dans ce fichier et créer un fichier common-texts-xx.tex. Certaines illustrations ont un fichier de langue dans leur propre dossier, mosaic-universe-scale et periodic-table-elements, qu'il faut aussi renommer et traduire. La création des illustrations en TikZ a été décrite plus haut.

4. Construisez et testez Générez le jeu de cartes dans la nouvelle langue pour vous assurer que tout fonctionne correctement.

5. Validez vos modifications Une fois vos modifications terminées, validez-les dans votre dépôt forké :

git add .
git commit -m "Ajout du support pour [Nouvelle langue]"
git push origin [Insérez le nom de la branche ici]

6. Faire une demande de Merge Request Soumettez une demande de fusion (pull request) au dépôt principal. Assurez-vous que votre demande de fusion inclut une description claire des modifications apportées et de leur nécessité.

Les scripts python¶

Liste des scripts python et de leurs fonctionnalités. Tous ces fichiers sont dans le dossier src.

Configuration¶

configuration.py

est un fichier de configurations : les langues possibles, les formats de jeux, les dossiers, et diverses autres variables pour créer les éléments divers. La variable AVAILABLE_LANGS contient les langues disponibles.

configuration_bitmap.py

est un fichier de configuration spécifique pour décrire les façons de produire les images bitmap à partir des fichiers pdf. La variable essentielle est le tableau PIXEL_CONVERTIONS dont les clés sont utilisées par le script de production des versions bitmap.

config_local_template.py

est un fichier qui permet de créer un fichier de configuration config_local.py pour désigner le chemin de l'exécutable magick ImageMagick. Si ce fichier n'existe pas, par défaut le chemin est "magick", ce qui signifie que la commande doit être accessible directement par python.

Utilitaires¶

utils.py

est un fichier contenant des fonctions utilisées dans les scripts python.

python switch-language.py --lang=xx

où xx est une des langues données dans AVAILABLE_LANGS. Ce script installe la langue xx pour la compilation directe des fichiers maîtres LaTeX et crée un ensemble de dossiers spécifiques à la langue.

python create-tikz-illustrations.py --lang=[xx|all] [--move=[true|false]] [--picture picture-name-1 picture-name-2 …]

où xx est une langue disponible dans AVAILABLE_LANGS, --move (optionnel, défaut false) permet de déplacer les illustrations produites dans les dossiers utilisés pour produire les cartes, --picture (optionnel) permet de ne produire que les illustrations données. Ce script produit les illustrations TikZ dans la langue sélectionnée xx ou dans toutes les langues avec l'option de langue all. Les fichiers sont regroupés dans le dossier illustrations-tikz/_PRODUCED-IMAGES.

python prepare-translation.py --lang-source=ss --lang-target=xx

où ss est une langue disponible dans AVAILABLE_LANGS et xx une nouvelle langue. Ce script prépare les fichiers pour créer une nouvelle version des cartes dans la langue xx à partir de la langue ss. Le processus est décrit ci-dessus.

python create-cards-files-from-translation.py

Ce script génère les fichiers LaTeX des cartes dans la langue traduite via une IA et dans le format donné par le script prepare-translation.py. Le processus est décrit ci-dessus.

Génération des cartes¶

python build-project.py --lang=xx [--illustrations=[true|false]] [--to-printer-files=[true|false]] [--crop-versions=[true|false]] [--labels label-cards-1 label-cards-2 …]

où xx est une des langues données dans AVAILABLE_LANGS. Ce script génère tout le contenu des cartes dans la langue xx (en utilisant le script create-pdf-files-cards.py).

Les options [true|false] permettent en amont de générer les illustrations TikZ dans la langue (--illustrations, qui utilise le script create-tikz-illustrations.py, valeur par défaut true), de créer en aval les fichiers prêts à être utilisés pour l'impression (--to-printer-files, qui utilise le script create-pdf-files-print.py, valeur par défaut true) et des versions pdf des cartes sans marges et traits d'impression (--crop-versions, qui utilise le script create-pdf-crop-cards.py, valeur par défaut true).
L'option --labels (optionnel) permet de désigner des labels de cartes à produire, et seulement celles là. Les fichiers générés par ces scripts sont regroupés dans des sous dossiers d'un dossier _cards-production-xx.

python create-bitmap-cards.py --lang xx yy … --conversion aaa bbb …

où xx, yy, etc sont des langues disponibles dans AVAILABLE_LANGS et aaa, bbb, etc sont des clés de types de conversions bitmap disponibles dans PIXEL_CONVERTIONS (voir ci-dessus). Attention, les cartes en version pdf dans les langues sélectionnées doivent exister avant l'exécution de ce script. Ce script génère des versions bitmap des cartes dans les langues choisies et dans les formats sélectionnés par l'option --conversion. Ces fichiers sont rangés dans des sous dossiers de _cards-production-xx.

python create-pdf-comparison.py --langL=xx --langR=yy

où xx, yy, etc sont des langues disponibles dans AVAILABLE_LANGS. Attention, les cartes en version pdf dans les langues sélectionnées doivent exister avant l'exécution de ce script. Ce script produit un fichier pdf pour présenter côte à côte sur chaque page les recto et verso des cartes dans les langues sélectionnées (gauche et droite). Le fichier pdf cards-lang-comparison-2.pdf créé est situé dans le dossier join-masters.

python create-pdf-crop-cards.py --lang=xx

où xx est une langue disponible dans AVAILABLE_LANGS. Attention, les cartes en version pdf dans la langue sélectionnée doivent exister avant l'exécution de ce script. Ce script produit des versions pdf des cartes sans marge ni trait d'impression. Les fichiers sont dans un sous dossier de _cards-production-xx.

python create-pdf-files-cards.py --lang=xx [--labels label-cards-1 label-cards-2 …] [--games=[all|fullGame|quizGame]] [--sets set_one set_two …]

où xx est une langue disponible dans AVAILABLE_LANGS. --labels (optionnel) permet de désigner des labels de cartes à produire, et seulement celles là (sans cette option, toutes les cartes sont produites), --games permet de désigner le jeu à composer (sans cette option ou avec all tous les jeux sont composés), et --sets permet de désigner les ensembles de cartes à composer (sans l'option, tous les ensembles de cartes sont composés, voir la variable CARD_SETS dans configuration.py). Ce script produit les cartes en version pdf pour la langue choisie et les options données. Les cartes sont produites dans des sous dossiers du dossier _cards-production-xx. Avant de produire les pdf des cartes, le script vide les dossiers de production. Mais si des labels sont fournis ou si une liste partielle d'ensembles de cartes est fournie, le script ne supprime pas les cartes déjà générées : il considère que c'est une mise à jour partielle des pdf des cartes. Pour produire toutes les cartes de tous les jeux, il est préférable d'utiliser build-project.py qui exécute ce script et utilise la même option --labels.

python create-pdf-files-print.py --lang=xx

où xx est une langue disponible dans AVAILABLE_LANGS. Ce script produit des fichiers pdf regroupant les cartes de différentes façons, afin de les imprimer dans différents formats. Les cartes sont produites dans le sous dossier cards-pdf-print du dossier _cards-production-xx.