Crafting Interpreters : un livre de 640 pages achevé en 15 mois
(journal.stuffwithstuff.com)- Même après la fin de la publication en ligne, Crafting Interpreters a nécessité 15 mois de travail supplémentaires pour devenir un vrai livre, et a finalement été publié en version imprimée, en ebook et en PDF
- Pour transformer un ensemble de fichiers Markdown et PNG en livre, il a fallu mettre en place de nouveaux outils : système de build en Dart, import XML dans InDesign, automatisation en JavaScript et vérification de la composition
- Le résultat final fait 8×10 pouces, 640 pages, plus de 200 000 mots, 1 133 extraits de code et des centaines d’illustrations, avec des contraintes de mise en page bien plus strictes que pour du contenu web classique
- Il a ensuite fallu 5 mois de relecture complète, un copy editing professionnel, 2 mois de composition, 2 semaines de travail sur l’index, ainsi que la vérification des épreuves et l’automatisation de la comparaison des PDF
- Un livre technique autoédité ne se résume pas à l’écriture : build, mise en page, validation et automatisation de la distribution déterminent directement sa qualité et son niveau de finition
Le travail restant après la fin du contenu web
- Le texte de Crafting Interpreters était déjà terminé, mais le résultat existait alors sous la forme de fichiers Markdown et PNG convertis en site web par du code Python
- L’objectif, depuis le début, était d’en faire un vrai livre papier, et après la mise en ligne du dernier chapitre, l’auteur a pris environ un mois de pause
- Après avoir écrit presque chaque jour pendant près de 4 ans, il était épuisé, et le contexte du début de l’année 2020 ne rendait pas non plus la poursuite du travail facile
Un système de build refait en Dart
- L’auteur a d’abord corrigé les coquilles et erreurs signalées par les lecteurs via des issues GitHub
- Il a ensuite réécrit tout le système de build du livre en Dart
- Le script de build du premier livre était un simple script Python qui rendait les fichiers Markdown de chaque chapitre en HTML et y insérait des fragments de code
- Crafting Interpreters devait construire progressivement deux implémentations complètes d’interpréteur sur 30 chapitres, ce qui exigeait un build plus complexe
- Le nouveau système de build pouvait produire par programme le code de l’interpréteur jusqu’à un chapitre donné, ou même jusqu’à un point précis dans un chapitre, puis le compiler et l’exécuter dans des tests automatiques
- Les outils basés sur Python étaient, selon le niveau de maîtrise de l’auteur, plus lourds à maintenir et plus lents
- La version Dart générait exactement le HTML et le code de coloration syntaxique souhaités, tout en étant 10 fois plus rapide que l’ancienne version Python
- Le contrôle accru sur le traitement du Markdown s’est aussi révélé utile plus tard pour l’export XML destiné à InDesign
Design du livre et choix du format
- Concevoir le livre ressemblait davantage au développement web ou au développement de jeux : il fallait d’abord créer un framework, puis y verser le contenu
- Dans InDesign, on définit des masters qui fixent les marges et la grille des pages, ainsi que des styles qui déterminent polices, styles de texte, objets et couleurs
- Crafting Interpreters comportait de nombreux éléments rendant le design difficile
- beaucoup de texte principal
- de longs apartés expliquant immédiatement une phrase, un extrait de code ou une illustration à côté
- beaucoup de code, avec pour chaque extrait une indication de son emplacement dans le programme final
- La largeur devait prendre en compte à la fois les longues lignes de code, la zone réservée aux apartés et la marge intérieure nécessaire à un livre épais
- Les manuels classiques d’informatique présents dans la bibliothèque de l’auteur faisaient souvent 7,5 pouces de large, mais ce format ne laissait pas assez de place pour le code, les apartés et les marges ; le choix s’est donc porté sur 8 pouces de large
- En autoédition, il fallait utiliser les formats limités pris en charge par KDP et IngramSpark, et à cette largeur, le choix raisonnable était 8×10 pouces
- Sur la verticale, le texte était aligné sur une baseline grid classique de 12 pt
Un pipeline XML pour passer à InDesign
- InDesign ne comprenait ni Markdown ni le système de build de l’auteur, ce qui rendait un copier-coller manuel irréaliste
- InDesign prend en charge l’import XML et l’application automatique de styles selon les balises
- En revanche, sa gestion du XML avait des limites sur les balises imbriquées, et ne traitait pas correctement, par exemple, des balises en italique imbriquées dans un titre comme en HTML
- Comme il contrôlait directement le système de build, l’auteur a écrit un exporteur XML personnalisé produisant des balises plus faciles à accepter pour InDesign
L’automatisation JavaScript d’InDesign et ses limites
- L’import XML créait dans InDesign une “story”, c’est-à-dire un flux continu unique de texte principal traversant les blocs de texte
- Le corps du texte et les extraits de code entraient dans ce flux principal, mais les apartés et les marqueurs d’emplacement devaient être déplacés sur le côté
- Dans le livre précédent, l’auteur découpait les apartés manuellement pour les coller dans de nouveaux blocs de texte, mais ici il y avait 1 133 extraits de code, rendant cette méthode impossible
- InDesign prend en charge le scripting JavaScript, mais la documentation et l’environnement de débogage étaient extrêmement pauvres
- pas de débogueur
- pas de stack trace
- pas de debug print classique
- seulement
alert(), qui interrompt le script à chaque appel
- Les scripts JavaScript repéraient les apartés et les marqueurs d’emplacement, les retiraient du flux principal et les plaçaient dans des blocs de texte séparés
- L’automatisation du positionnement n’a toutefois jamais été complètement finalisée
- l’auteur a essayé d’utiliser la fonction d’ancrage d’InDesign et les Object Styles pour le placement, mais dans certains cas cela faisait disparaître les bordures de certains extraits de code voisins
- il a donc finalement dû positionner manuellement certaines balises d’emplacement
Révision et copy editing
- L’auteur a effectué une passe éditoriale en relisant tout le texte du début à la fin
- Chaque chapitre avait déjà traversé trois drafts pendant l’écriture, mais il fallait une nouvelle relecture pour juger le flux de l’ensemble du livre
- Ce travail a pris 5 mois, et la plupart des blagues répétées ont été corrigées
- Il a ensuite engagé la copy editor professionnelle Kari Somerton
- Le workflow éditorial classique repose souvent sur Microsoft Word et Track Changes, mais l’auteur voulait conserver un workflow fondé sur du texte brut et Git
- Kari Somerton a appris à utiliser Git et le système de build personnalisé, puis a relu l’intégralité du livre et repéré des centaines d’erreurs
- Malgré quatre drafts déjà réalisées et des centaines d’issues remontées par les lecteurs, une copy editor professionnelle a encore trouvé de nombreux problèmes
Les contraintes de composition sur 640 pages
- Une fois les mots suffisamment peaufinés, l’auteur est passé à la composition chapitre par chapitre dans InDesign
- Le travail sur chaque chapitre suivait le flux suivant
- créer un nouveau fichier InDesign
- exporter le XML
- importer le XML dans InDesign
- extraire les apartés et les marqueurs d’emplacement avec JavaScript
- définir les ancrages des éléments de sidebar
- ajuster les blancs en bas de page
- Les cinq premières étapes prenaient environ 30 minutes par chapitre, mais le dernier ajustement des blancs était de loin le plus difficile
- La composition d’un livre est soumise à diverses contraintes de placement vertical
- on ne peut pas couper une illustration au milieu d’une page
- il est plus facile à comprendre qu’un aparté tienne sur une seule page
- il vaut mieux aussi éviter, autant que possible, qu’un extrait de code soit coupé sur deux pages
- il faut éviter qu’un titre reste seul en bas de page
- il vaut mieux aussi éviter les widows and orphans
- Dans ce type de situation, InDesign repousse le contenu à la page suivante, mais cela laisse alors de grands espaces blancs en bas de page
- Les illustrations et extraits de code se comportaient comme un problème de bin-packing fortement entremêlé, ce qui a porté la composition de l’ensemble des chapitres à 2 mois
- Pour réduire ces blancs, il a fallu parfois scinder un extrait de code en deux, ajuster les marges autour d’une image ou modifier la hauteur d’une illustration
Illustrations, index et éléments liminaires/finals
- Les illustrations ont été choisies comme des dessins à l’encre noir et blanc adaptés à l’impression, et ont d’abord été numérisées en 1200 DPI
- Exporter des bitmaps haute résolution était simple, mais leur intégration dans la mise en page était difficile
- Le texte ne disait pas “voir figure 123” : il pointait directement vers l’illustration voisine, ce qui imposait de placer l’image à proximité immédiate
- Au lieu d’engager un indexeur professionnel, l’auteur a passé 2 semaines à reparcourir tous les chapitres pour construire lui-même l’index
- La fonction d’index d’InDesign permettait de transformer un texte sélectionné en entrée d’index puis de générer l’index complet, mais l’ajout des entrées restait une tâche répétitive et fastidieuse
- À la fin du livre se trouvait l’index, et au début la page de titre, la page de copyright, la dédicace, les remerciements et la table des matières générée par InDesign
Design de couverture
- L’auteur estimait que la dimension artistique d’une couverture de livre technique n’était peut-être pas aussi cruciale que pour un roman, mais comme il ne pouvait pas compter sur un statut de professeur pour imposer l’achat du livre, il y a consacré beaucoup de temps
- Il pensait d’abord utiliser une photo qu’il avait prise lui-même, mais n’a pas trouvé d’image adaptée
- Il a finalement choisi de reprendre le langage visuel du livre, à savoir les illustrations à la plume et à l’encre
- Il a redessiné en plus grand et avec davantage de détails l’illustration de montagne expliquant le processus de compilation, et a aussi recréé le lettrage du titre dans un style manuscrit
- Le titre a été basé sur Acumin Pro Extra Condensed, imprimé puis retracé à la main pour lui donner un aspect imparfait, avec une palette de couleurs évoquant les manuels scouts ronéotypés des années 1950
Épreuves et vérification des changements dans le PDF
- L’auteur a téléversé le PDF sur KDP et commandé des épreuves, puis a reçu une lourde boîte une semaine plus tard
- Ce n’est qu’en voyant le livre physique qu’il a vraiment pris la mesure du projet, non plus comme un ensemble de fichiers mais comme un objet concret
- Comme la composition impliquait beaucoup d’interventions manuelles, il a relu les épreuves papier lui-même, en repérant les erreurs et en les marquant avec des notes autocollantes
- Les fichiers InDesign étaient placés dans un dépôt Git, mais comme il s’agissait de gros fichiers binaires opaques, il était impossible d’y voir des diff comme avec du code source
- InDesign modifiait parfois les fichiers même lorsqu’aucun changement réel n’était visible, ce qui rendait difficile l’identification de ce qui avait bougé
- L’auteur a écrit un script Dart qui extrayait toutes les pages du PDF du livre et les assemblait en une grande image PNG en tuiles
- À chaque commit, il exportait le PDF, générait cette image en tuiles, puis utilisait une action Photoshop pour entourer en rouge les pixels différents entre deux images afin de repérer les pages modifiées
- Cette méthode n’indiquait pas directement le détail des modifications, mais elle montrait quelles pages devaient être vérifiées visuellement et permettait de confirmer que seules les modifications prévues avaient été introduites
Ebook et sortie
- Une fois les corrections sur les épreuves papier terminées, l’auteur a aussi produit les versions Kindle et EPUB
- Il a modifié son système de build pour pouvoir exporter le vieux XHTML, les métadonnées et le manifest exigés par l’EPUB
- Après quelques commandes en ligne de commande, il obtenait les ebooks Kindle et EPUB, qu’il testait ensuite sur plusieurs lecteurs tout en ajustant le CSS
- Une fois les fichiers finaux prêts, il a mis à jour la première page du site du livre pour renvoyer vers les points de vente, et a aussi retravaillé les photos et la mise en page responsive
- Après l’upload sur les stores, la mise à jour du site et l’annonce à la mailing list, le livre était enfin “vraiment” terminé
Et ensuite ?
- Même après la fin du dernier chapitre, les gens lui demandaient quel serait son prochain projet ou le sujet de son prochain livre
- Après avoir consacré 6 ans à un seul projet, l’auteur ne prévoit pas de commencer un nouveau livre de sitôt
- Il avait aussi accumulé beaucoup de choses repoussées pendant la pandémie, et comptait donc se reposer un temps sans décider immédiatement de la suite
- Il évoque des possibilités comme faire de la musique, pêcher, passer du temps avec ses amis et sa famille, ou travailler sur un projet de roguelike, sans vouloir choisir tout de suite
- Il pense qu’il pourra un jour avoir de nouveau envie de se lancer dans un grand projet, mais précise qu’il ne souhaite pas y consacrer à nouveau 6 ans
1 commentaires
Avis sur Hacker News
Cette page contient à la fois un lien pour acheter le livre et un lien vers la version en ligne gratuite : https://craftinginterpreters.com/
Ce livre vaut clairement la peine d’être acheté. Rien que le soin apporté par Nystrom à la conception du livre papier suffit pour les amateurs d’ouvrages imprimés, et avec les illustrations dessinées à la main et l’excellente écriture, je le trouve meilleur que 99 % des livres techniques.
C’est l’un des meilleurs livres techniques que j’aie lus jusqu’ici. La structure où chaque chapitre laisse derrière lui du code qui progresse par étapes et un programme exécutable est une idée remarquable, et je suis admiratif que l’auteur ait réellement réussi à la mener à bien.
Comme j’avais déjà écrit quelque chose de similaire auparavant, j’ai parcouru assez rapidement la partie sur l’interpréteur par parcours d’arbre, et j’ai appris bien davantage en suivant l’interpréteur en bytecode basé sur C.
J’ai cru que l’article était récent et qu’une deuxième édition était sortie.
J’aimerais féliciter l’auteur. Ce livre est une excellente ressource, non seulement pour sa profondeur technique dans le domaine des langages, mais aussi pour les petits détails de mise en page et de graphisme qui donnent envie de continuer à lire. Il donne l’impression d’être un livre qui restera pertinent longtemps.
J’ai commencé à suivre Crafting Interpreters en 2017, et en avançant dans la première moitié du livre, j’ai écrit mon implémentation de lox en Scala plutôt qu’en Java ; au passage, les tokenizers/analyseurs lexicaux/parseurs/interpréteurs ont totalement cessé d’être mystérieux pour moi.
Avant, je voyais ça comme un domaine presque visionnaire réservé à une certaine catégorie de programmeurs, mais je pense que cela tient à l’excellente écriture de Nystrom et à sa compréhension profonde du sujet. J’ai commencé à écrire le second interpréteur en Rust, mais la vie est devenue chargée, je n’ai pas beaucoup avancé et je ne l’ai jamais terminé. Il est sans doute temps d’y revenir. Cet article date de quelques années, mais je ne savais pas qu’il avait été publié en livre papier ; même si ce n’est pas le format optimal pour ma manière d’apprendre, j’ai envie d’en acheter un exemplaire pour le posséder et soutenir l’auteur.
C’est l’un des meilleurs livres d’informatique que j’aie lus. J’ai vraiment pris énormément de plaisir à le lire et j’ai appris beaucoup de choses.
En plus de son excellent contenu technique, il est bien écrit, drôle, et les illustrations sont réussies. Je le vois comme un accomplissement monumental.
Une excellente interview où Bob parle de ce livre, qui vaut l’écoute : https://corecursive.com/032-bob-nystrom-on-building-an-inter...
Ironiquement, il m’a fallu 15 mois pour lire le livre jusqu’au bout :). Je comprends très bien la situation de l’auteur. C’est un excellent livre, écrit par un auteur sérieux et brillant, et je m’y suis tellement attaché que j’ai même créé une page à partir de ce que j’ai appris : https://hexmos.com/compiler
L’auteur est donc passé de graphiste à ingénieur compilateur ? C’est étonnant et impressionnant.
Ce livre est dans ma bibliothèque. Ce sera mon prochain livre sur les interpréteurs après “Writing an interpreter in Go”, qui fait environ 200 pages et que j’aime vraiment beaucoup.
Je viens de terminer l’analyseur lexical en Rust au lieu de Java, et j’ai hâte de lire la suite. Jusqu’ici, c’est un excellent livre.