szcharlesji/tikz-explorer-book

Livre explorateur TikZ

Vous créez un livre que quelqu’un va explorer : une seule page web dont l’accueil est une carte conceptuelle de tout le domaine, et dont les chapitres rendent chacun une idée visible avec des figures TikZ soigneusement calculées. Le lecteur veut d’abord voir le paysage, relier les points, puis approfondir là où il le souhaite.

La visualisation est la priorité. Un chapitre, ce sont ses figures. Le texte amène à une figure et en tire la conclusion ; il ne remplace jamais une figure qui pourrait montrer la même chose. Lorsque vous arbitrez le temps, privilégiez la qualité des figures et réduisez la prose.

Cette compétence orchestre ; la réalisation des figures vit dans deux compétences sœurs qui partagent un langage visuel commun (dlviz.sty, couleur = rôle). Elles voyagent ensemble et se trouvent à côté du dossier de cette compétence ; ci-dessous, <skills> désigne le dossier qui contient les trois (le dossier parent de cette compétence, où qu’elle soit installée) :

• tikz-dl-visualizer (<skills>/tikz-dl-visualizer/) : figures statiques. Son fichier de style, ses archétypes et son script de rendu définissent ce qu’est une bonne figure. La plupart des figures d’un livre sont statiques.
• tikz-live (<skills>/tikz-live/) : figures vivantes. Un squelette TikZ compilé par pdflatex plus une petite spécification JS qui dessine la partie mobile, afin que le lecteur puisse faire glisser un point de départ, coulisser une température ou survoler un jeton tandis que chaque étiquette reste du vrai TeX. Le livre les intègre et elles suivent son thème clair/sombre.

Lisez les deux fichiers SKILL.md une fois avant de planifier, afin de savoir ce qu’est une bonne figure et quand l’interaction mérite sa place.

Ce que vous livrez

<book>/
├── book.json            titre, parties, identifiants de chapitres, rôles de couleurs, paramètres de carte
├── SPEC.md              le contrat que tout auteur de chapitre suit
├── chapters/00-front.html   hero, emplacement de la carte, mode d’emploi, conventions, légende
├── chapters/<cid>.html  un <section class="chapter"> par chapitre
├── figs/<cid>-<slug>.tex/.png/-light.png/.pdf
├── figs/<cid>-<slug>.js     figures vivantes uniquement : la spécification ; fig.sh écrit aussi
│                            .live.html (intégré par la construction), .html (autonome)
│                            et <slug>.<snapshot>.png (pour révision)
├── scripts/<cid>-<slug>.py  le Python derrière chaque nombre d’une figure
├── map/data.json        carte conceptuelle : familles, concepts, travaux clés, liens, visite
├── tools/               build.py, shell.html (conception de la page), fig.sh, dllive.js (exécution des figures vivantes)
└── index.html, preview.html   page construite (publier index.html)

Prérequis : une installation TeX avec TikZ/pgfplots (pdflatex), Ghostscript ou poppler pour les PNG, ImageMagick pour les planches contact, uv (ou Python avec numpy/scipy) pour les nombres des figures, et pour les figures vivantes node plus PyMuPDF (uv run --with pymupdf, ce que fig.sh fait pour vous). La page charge MathJax (jsDelivr) et d3 (cdnjs). Vérifiez which pdflatex gs magick uv node tôt ; si des paquets TeX manquent, dites à l’utilisateur la commande tlmgr install au lieu d’installer.

Flux de travail

1. Comprendre la source et le lecteur

Lisez la source (récupérez le calendrier du cours ou le syllabus, listez les lectures). Ensuite, ciblez le lecteur : ce qu’il sait déjà (sautez les bases qu’il connaît, mais dessinez bien les fondamentaux) et ce qu’il vise (un emploi, un examen, une direction de recherche). L’objectif détermine la forme du livre :

• La partie I suit la source, un chapitre par session ou unité. Chaque chapitre approfondit une idée plutôt que de tout résumer.
• La partie II est une boîte à outils pour l’objectif du lecteur, par exemple « ce qu’un chercheur en génération vidéo doit savoir » : les fondamentaux transversaux que la source suppose ou omet, pratiques et actuels, avec des chiffres réels. Omettez la partie II si le lecteur n’a pas d’objectif au-delà de la source.
• La page d’accueil est une carte conceptuelle : la vue d’ensemble avant toute profondeur.

Ne demandez à l’utilisateur que lorsque l’objectif est vraiment flou ; sinon, énoncez votre interprétation en une ligne et continuez.

2. Planifier les chapitres autour des figures

Pour chaque chapitre, rédigez un brief : le fil conducteur profond (une phrase), 2–3 figures avec ce que chacune doit rendre visible, quel archétype, et quoi calculer. C’est l’étape la plus importante. Les briefs qui nomment le mécanisme donnent d’excellentes figures ; les briefs qui nomment un sujet donnent des diagrammes en boîte.

• Faible : « figure sur le guidance sans classifieur ».
• Fort : « mélange à deux classes en 1D ; intégrer l’ODE guidée avec des vitesses exactes pour w = 0, 1, 2, 4 ; petites multiples des densités résultantes contre p(x|c) et la densité inclinée, montrant que le guidance dépasse l’inclinaison. »

Bons sujets de figures : un mécanisme en action (chemins, flux, mises à jour), un avant/après, une comparaison de deux méthodes sur des entrées identiques, des formes et des comptes (formes de tenseurs, nombres de jetons, FLOPs), une expérience numérique dont le résultat est le point. Chacune doit être calculable : l’auteur produira chaque nombre en Python.

Décidez quelles figures sont vivantes. Une figure mérite l’interaction lorsque le lecteur apprend en changeant quelque chose et en regardant le mécanisme répondre, d’une manière qu’une image statique ou de petites multiples ne peuvent pas aussi bien montrer. Écrivez sa phrase d’interaction dans le brief : « le lecteur fait glisser X / coulisse Y / survole Z et voit W ». Budget : environ une figure vivante par chapitre, pour le mécanisme phare du chapitre ; tout le reste est statique. Bons candidats : chemins d’optimiseur (faire glisser le départ, coulisser β), attention ou convolution (survoler une ligne ou une cellule), un balayage du poids de guidance ou de la température, une application linéaire (faire glisser les vecteurs de base), des étapes d’échantillonnage (jouer). Mauvais : pipelines, diagrammes d’architecture, tout ce que de petites multiples montrent déjà la tendance.

• Brief vivant : « mélange à deux classes en 1D ; le lecteur coulisse le poids de guidance w de 0 à 6 et voit la densité guidée dépasser la cible inclinée ; un bouton play intègre l’ODE pas à pas ; nombres : KL par rapport à la cible, en direct. »

Décidez aussi, une fois pour tout le livre : les rôles de couleurs (quelle couleur signifie quoi ; mettez-les dans book.json pour que figures, maths en prose et légende s’accordent), les conventions sur lesquelles le domaine est en désaccord (direction du temps, signes, notation et symboles qui signifient des choses différentes selon les chapitres, comme (v) pour la vitesse du momentum et le second moment d’Adam), et les identifiants de chapitres (w01…, v01… ; la lettre devient le préfixe des étiquettes de figures, W3.2, V5.1).

3. Générer la structure

python3 <skill>/scripts/init_book.py <book> --title "Titre du livre" --sub "Source · Terme"

Modifiez book.json (parties, identifiants de chapitres, rôles) et chapters/00-front.html ; lisez chacun d’abord, car les outils de fichiers refusent d’écraser un fichier que vous n’avez pas lu. Les rôles du modèle sont génériques pour l’apprentissage profond (entrée, caché, latent…) : remplacez-les par ceux du domaine (pour les optimiseurs : itération, gradient, vitesse, perte…). Écrivez <book>/SPEC.md à partir de references/author-spec.md, en remplissant chaque bloc «…» : lecteur, parties, tableau des rôles, conventions, carte des chapitres. Les auteurs ne voient que SPEC.md et leur brief, donc SPEC.md doit se suffire à lui-même. Écrivez-le même lorsque vous êtes l’auteur du livre vous-même : c’est là que vivent les conventions pour les chapitres ultérieurs et les sessions suivantes.

Avant de lancer quiconque, faites le rendu d’une figure jetable via bash <book>/tools/fig.sh pour prouver que le pipeline TeX fonctionne, et, si le plan comporte des figures vivantes, une figure vivante aussi : copiez <skills>/tikz-live/assets/examples/momentum/momentum.{tex,js} dans figs/_test/, lancez bash <book>/tools/fig.sh figs/_test/momentum.tex, puis rm -rf <book>/figs/_test (ses fichiers intermédiaires vivent dans figs/_test/.dllive/, donc il ne reste rien). Cela prouve que node et PyMuPDF fonctionnent et place tools/dllive.js au bon endroit. Un pipeline cassé découvert par neuf auteurs parallèles coûte neuf fois plus cher.

4. Déléguer les chapitres

Pour un cours complet (10+ chapitres), lancez des sous-agents généralistes en parallèle, chacun possédant 2–4 chapitres connexes (environ 5–7 figures). Chaque prompt dit : lisez <book>/SPEC.md d’abord et suivez-le ; les identifiants de chapitres qu’il possède ; par chapitre, les métadonnées de session, les articles, le fil conducteur profond et les briefs de figures ; faites le rendu, regardez, corrigez, puis rapportez selon la section 5 de SPEC. Groupez les chapitres connexes sous un même auteur pour que les figures partagées restent cohérentes (par exemple, OT dynamique avec couplages OT).

Les limites d’utilisation sont réelles : neuf auteurs à la fois peuvent épuiser une limite de session en cours de route. Si les agents s’arrêtent avec une erreur de limite de débit, leurs fichiers sont conservés. Reprenez chacun avec SendMessage (« continuez là où vous vous êtes arrêté ; vérifiez ce que vous avez déjà fait ») une fois la limite réinitialisée, au lieu de lancer de nouveaux agents. Pour les gros livres, envisagez de lancer en deux vagues.

Pour un petit livre (un sujet, 3–5 chapitres), sautez les sous-agents et écrivez-le vous-même, en suivant toujours SPEC.md.

5. Pendant que les auteurs dessinent : pages de garde et carte

Écrivez chapters/00-front.html (hero, mode d’emploi, conventions, la légende <!--ROLES-->, éventuellement un tableau reflétant la source, par exemple le calendrier du cours avec les liens des chapitres) et map/data.json. Lisez references/concept-map.md pour le schéma et comment choisir les familles, les nœuds, les relations et la visite. La carte est une vue d’ensemble : ce qu’est chaque idée, où elle se situe, comment elle se relie, et quel chapitre approfondit. N’expliquez pas les mécanismes ici.

6. Réviser au fur et à mesure que les rapports arrivent

Chaque rapport liste les phrases d’une idée de ses figures et ses affirmations non vérifiées. Ouvrez vous-même les figures les plus importantes (la comparaison phare, tout ce que l’utilisateur a demandé nommément) et vérifiez-les par rapport aux faits que vous connaissez. Envoyez des corrections concrètes à l’auteur qui les a dessinées.

7. Assembler, vérifier, lire

python3 <book>/tools/build.py
python3 <skill>/scripts/check_book.py <book> --sheet

Ensuite, suivez references/qa-and-publish.md : coup d’œil sur la planche contact, vérifications dans le navigateur (erreurs mathématiques, débordement largeur téléphone, carte, mode clair, figures vivantes : toutes montées, glisser et survoler fonctionnent, le bouton de thème les recolorie), et lisez le texte de chaque chapitre avant de publier. Corrigez les erreurs de métadonnées (numéros de session, dates) que les auteurs héritent de vos briefs.

Ne sautez pas la vérification dans le navigateur. Les vérifications statiques ne peuvent pas exécuter le JavaScript de la page, et les échecs les plus importants sont silencieux : une carte qui ne s’affiche jamais, des maths qui cessent de composer. Si vous ne pouvez vraiment pas ouvrir un navigateur, indiquez-le dans la passation et listez les vérifications navigateur comme non effectuées.

8. Publier

Publiez <book>/index.html comme un Artifact avec chaque PNG de figure comme fichier d’accompagnement (check_book.py --files-json imprime la liste ; les figures vivantes sont intégrées dans la page, donc leurs PNG sont exclus), ou remettez le dossier si aucun outil Artifact n’existe. Dites à l’utilisateur ce qu’il y a dans chaque partie, ce qui n’est pas vérifié, quelles figures sont des illustrations plutôt que des résultats calculés, et comment reconstruire (python3 tools/build.py) ou refaire le rendu d’une figure.

Demandes ultérieures

Modifiez le même dossier et republiez le même chemin de fichier, pour que le lien reste le même : ajoutez un chapitre (ajoutez son identifiant dans book.json), étendez la carte (modifiez map/data.json), ou refaites le style (modifiez tools/shell.html). Conservez les corrections listées dans references/qa-and-publish.md §3 lorsque vous touchez au shell ou à map.js.

Fichiers de référence

• references/author-spec.md — le modèle pour SPEC.md, le contrat des auteurs de chapitres (règles des figures, format des fragments HTML, règles de citation).
• references/concept-map.md — le schéma de map/data.json et comment écrire une carte qui relie les points.
• references/qa-and-publish.md — vérifications, extraits de navigateur, pièges connus déjà corrigés dans le modèle, publication.
• assets/template/ — le squelette du livre que init_book.py copie.