Notebooks et literate programming

principes et historique

gt notebook

Hugues Pecout (CNRS, UMR Géographie-Cités)

Sébastien Rey-Coyrehourcq (université de Rouen Normandie, UMR IDEES)

Raphaëlle Krummeich (université de Rouen Normandie, UMR IDEES)

mercredi 25 juin 2025

Pourquoi ces paradigmes & technologies ?

La programmation lettrée et “le notebook” pour

1. produire des données ou fichiers lisibles et interopérables
2. pratiquer une écriture numérique nouvelle & partagée
3. évoluer au sein de tendances et faits historiques
4. contribuer à l’édition ou la publication scientifique “ouverte”
5. choisir son langage et environnement de travail
6. adopter des pratiques émergentes

1. produire des données ou fichiers lisibles et interopérables

Pourquoi changeriez-vous de paradigme d’écriture ?

Voyons ce qu’il en est, par exemple, d’un fichier Word :

1. prenons le docx de l’AAP Énergie@CNRS 2025
2. modifions le .docx en archive .zip
3. décompressons ce format du document word
4. découvrons ce que contient l’archive

Le paradigme des fenêtres vues de la machine

Comment procéder avec un shell Unix ?

1. copier le ficher .docx vers le même fichier avec l’extension .zip

2. décompresser l’archive .zip dans data/docx

3. compter le nombre de dossiers dans data/docx

find data/docx/. -type d | wc -l

9

4. compter le nombre de fichiers dans data/docx

find data/docx/. -type f | wc -l

26

Comment est “fabriqué” le fichier .docx ?

document aux formats docx, txt et zip

contenu du répertoire docx

Un document au format .docx vu de la machine

Que contient cette archive ?

ls -hsR data/docx

data/docx:
total 20K
4.0K [Content_Types].xml
4.0K customXml
4.0K docProps
4.0K _rels
4.0K word

data/docx/customXml:
total 12K
4.0K item1.xml
4.0K itemProps1.xml
4.0K _rels

data/docx/customXml/_rels:
total 4.0K
4.0K item1.xml.rels

data/docx/docProps:
total 8.0K
4.0K app.xml
4.0K core.xml

data/docx/_rels:
total 0

data/docx/word:
total 456K
204K document.xml
4.0K endnotes.xml
4.0K fontTable.xml
4.0K footer1.xml
8.0K footer2.xml
4.0K footer3.xml
4.0K footnotes.xml
4.0K header1.xml
8.0K header2.xml
4.0K header3.xml
4.0K media
104K numbering.xml
4.0K _rels
 16K settings.xml
 52K styles.xml
4.0K theme
 24K webSettings.xml

data/docx/word/media:
total 112K
112K image1.jpg

data/docx/word/_rels:
total 12K
4.0K document.xml.rels
4.0K footer2.xml.rels
4.0K header2.xml.rels

data/docx/word/theme:
total 8.0K
8.0K theme1.xml

Quelle est la structure de son contenu ?

1. compter le nombre de lignes du document xml

wc -l data/docx/word/document.xml

1 data/docx/word/document.xml

2. compter le nombre de caractères du document xml

wc -c data/docx/word/document.xml

206464 data/docx/word/document.xml

Un document au format .docx vu de la machine

Visualiser le document “mis en forme” et…

première page du document word

seconde page du document word

Un document au format .docx vu de la machine

… comment la machine le voit

Le contenu figure sur 1 seule ligne qui contient plus de 200 000 caractères

le nombre de balises ouvrantes

grep -io "<" data/docx/word/document.xml | wc -l

7878

le nombre de fois que la mention “Arial” apparaît

grep -io Arial data/docx/word/document.xml | wc -l

1443

2. pratiquer une écriture numérique nouvelle & partagée

Balisage léger et document partagé

… et comment une forge peut être utilisée

data/doc.md déployé par la forge logicielle

Parser et “pandoc”

langage structuré ou pivot au sein de formats de documents

Écrire à plusieurs et versionner : l’exemple hackmd

langage et éciture partagée

Écrire et décrire du code vs le literate programming

Do not disturb programmers

Tim Daly’s Axiom Website

The first reaction is that this is a new, painful form of documentation.
It is not.
Documentation is a how construct. It is a way of explaining how a program works or how an application interface should be used.

Literate programming is about why.[…]

The why becomes important when you have to maintain and modify a program. You can perfectly understand how a subroutine, module, or class works. You can explain its input and outputs. What you don’t understand is why it exists. Nobody writes that down. […]

Notebook : réduire la dualité texte & code

Écrire du texte, décrire l’écriture du code, pourquoi ?

• Donner au code un sens littéraire, écire le récit de l’écriture du code
• NON réduire le code à une fonction computationnelle ou un rôle subalterne à “LA” science
• Expliciter (peut-être) le processus conduisant à une Architecture.md en plus du Readme.md au sein de la forge

Notebook : réduire la dualité texte & code

La pensée ne peut être abstraite, Marcello Vitali-Rosati, novembre 2023

Toucher l’abstraction ?

echo -e "---\ntitle: Libres écritures\n---\n## Introduction\n Voici ma belle intro, adaptée \
librement de la proposition de Marcello Vitali Rosati^[Et une note qui précise que cette \
expérimentation a été réalisée à Lyon le 16 novembre 2023]" | pandoc -s -o title.html

“Anatomie” des notebooks R ou Python

Notebook Jupyter notebook .ipynb (format json peu lisible)

Notebook Jupyter myst .md (Markdown)

Notebook R .qmd ( Quarto)

“Anatomie” d’un notebook & Programmation Lettrée

Sans Literate programming

“Anatomie” d’un notebook & Programmation Lettrée

Avec Literate programming

3. évoluer au sein de tendances et faits historiques

Notebook, Literate programming

Les premiers “notebooks”

• 1970 : Scratchpad (Axiom)
• 1986 : MathCad (First WYSIWYG, Dos)
• 1988 : Mathematica
• 1989 : Maple
• 2011 : IPython

Notebook, Literate programming

Émergence du Literate Programming

Le concept de programmation lettrée est conçu et opérationnalisé (Web, Tex) par Donald Knuth en 1977-78.

Ce paradigme de programmation met en avant non plus l’ordonnancement imposé par l’ordinateur mais autorise l’utilisation d’un ordre propre à la logique et au fil de la pensée.

« Nous devons changer notre attitude traditionnelle envers la construction des programmes : au lieu de considérer que notre tâche principale est de dire à un ordinateur ce qu’il doit faire, appliquons-nous plutôt à expliquer à des êtres humains ce que nous voulons que l’ordinateur fasse (…)» Knuth (1984)

« Programs must be written for people to read, and only incidentally for machines to execute. » Abelson et al. (1985)

Notebook, Literate programming

Literate programming “BONUS”

La documentation EST le programme

• Inform
• Axiom

Le livre EST le programme (The book is a program)

• (Pascal) Computers & Typesetting
• (C++) https://www.pbr-book.org/
• (Racket) Pollen Scribble
• (Python/R) Geocompx project
• 3. A Retargetable C Compiler
• …

Notebook, Literate programming

Notebook de type documentation, i.e. "How" : lire le fil linéaire du programme

Notebook, Literate programming

Notebook en programmation lettrée, i.e. “Why” & "How" : reconstruire le fil du récit d’écriture du code

Notebook, Literate programming

Literate Programming et Knitr/RMarkdown

Exemple 1

Source

Résultat

Notebook, Literate programming

Literate Programming et Knitr/RMarkdown

Exemple 2

Source

Résultat

Notebook, Literate programming

Literate Programming et Knitr/RMarkdown

You can write arbitrary incomplete code in code chunks, and compose code chunks freely. This, I believe, is the true spirit of literate programming, but is often overlooked by software authors who implement software products using the idea of literate programming. Literate programming is a programming technique. It does not simply mean mixing code and text in a linear order. « The First Notebook War - Yihui Xie 谢益辉 » (s. d.)

Notebook, Literate programming et reproductibilité

Émergence de la recherche reproductible computationnelle

Jon Claerbout est l’un des premiers chercheurs à exprimer le fait que les méthodes de calcul menacent la reproductibilité de la recherche si l’on ne donne pas un accès libre aux données et aux logiciels qui la sous-tendent.

En 1976, il publie un ouvrage référence en traitement de signal Claerbout (1985). Cette 1ère version - non-reproductible - sera le début d’une recherche sur la reproductibilité qui démarre en 1985

… Via des “Active documents and reproducible results”,Claerbout J.J. Sep 67

A revolution in education and technology transfer will follow from the marriage of word processing and software command scripts. In this marriage, here being called an active document (a-doc), an author attaches to every figure caption a pushbutton or a name tag usable to recalculate the figure from from all its data, parameters, and programs. An a-doc provides a concrete definition of reproducibility in computational oriented research.

Notebook, Literate programming et reproductibilité

Reproductibilité, répétabilité, réplicabilité ?

Notre focus est la reproductibilité computationelle

Notebook, Literate programming et reproductibilité

Reproductibilité, répétabilité, réplicabilité ?

• polysémie des termes Dellaiera (2025)
• harmonisation des définitions par l’ACM / NSF en 2020 : reproductible ~= répétable ?
• en SHS, d’autres questions émergent :
  • Ben Marwick Associate Editor of R.,
  • Marwick (2017), Marwick B (2018)
  • Rey-Coyrehourcq et al. (2017)
• en lectures croisées, consulter
  • le blog de Konrad Hinsen,
  • le site du réseau français de recherche reproductible RFRR,
• pour le calcul intensif (HPC), voir Antunes et Hill (2024) etc.

Notebook, Literate programming et reproductibilité

Reproductibilité, répétabilité, réplicabilité ?

Convergence et harmonisation de définition (non exhaustive)

Reproducibility (Different team, same experimental setup): The measurement can be obtained with stated precision by a different team using the same measurement procedure, the same measuring system, under the same operating conditions, in the same or a different location on multiple trials. For computational experiments, this means that an independent group can obtain the same result using the author’s own artifacts.

Replicability (Different team, different experimental setup): The measurement can be obtained with stated precision by a different team, a different measuring system, in a different location on multiple trials. For computational experiments, this means that an independent group can obtain the same result using artifacts which they develop completely independently.

Repeatability (Same team, same experimental setup): The measurement can be obtained with stated precision by the same team using the same measurement procedure, the same measuring system, under the same operating conditions, in the same location on multiple trials. For computational experiments, this means that a researcher can reliably repeat his own computation.

Dans notre cadre, on retiendra les termes Reproductibles et Répétables comme interchangeable, car pour obtenir la Reproductibilité, il est évident que la Répétabilité est nécessaire.

4. contribuer à la production de la publication scientifique “ouverte”

Notebook, Literate programming et reproductibilité

Articuler les 3 problématiques : enjeux de la première couche logicielle

Le notebook

• n’est pas synonyme de programmation lettrée, contrairement à ce que l’on lit souvent

• ne garantit pas la reproductibilité computationnelle

Notebook et publication scientifique

Pratiques & interprétations disciplinaires

Du FAIR(E) d’un objet technique proteïforme, halshs-04019870

Notebook, Literate programming et reproductibilité

Réflexivité(s) & SHS

La lunette de vue & position critique

Notebook et publication scientifique

Balisage léger & langage informatique

Notebook et publication scientifique

Les revues en SHS

• Rzine, collection sur la pratique de R en SHS

• Computo, revue de statistique de la SFdS

• Programming Historian, tutoriels méthodes & outils

• Notebooks Now!, initiative communautaire financée

Notebook et publication scientifique

Écosystèmes

• HumaNum (initiative “Callisto”)
• Ateliers de la donnée
• MSH CNRS
• Software carpentries
• etc.

5. choisir son langage et environnement de travail

Focus Jupyter & Quarto

• Fernando Perez, utilisateur Mapple/Mathematica, 2001 console IPython
• 2011 Notebook IPython (multiples échecs précédemment), passage au web
• Naissance de l’organisation Jupyter en 2014, évolution de la gouvernance et BigSplit
• ACM Awards en 2017, consolidation de la gouvernance : université, gouvernement, secteur privé avec pour glue le mouvement open-source.
• Jupyter Lab 2016, vers un IDE
• Jupycon 2018 : I don’t like Notebook (Joel Grus)
• Jupyter Book , premier commit (2018); Notebook to Jekyll ?
• Myst (extension Markdown )+ Sphynx
• Myst to MystMd
• Jupyter Book devient un sous projet Jupyter (2024)

Source : Schultz (2023), #1, #2, #3

Focus Jupyter & Quarto

• Sweave 2002 (Friedrich L)
• Yihui Xie / Sweave / 2007
• format Rmd / Knitr (agnostique) 2011 / First book 2013
• package Markdown 2013 => RMarkdown + Pandoc 2014
• Rstudio 2010
• Yihui Xie => RStudio 2014
• Bookdown 2016 & Blogdown 2017
• Yihui Xie 2018 => First Notebook War
• Quarto 2022 => Ecosystème, vise l’Agnostique
• Licenciement Yui 2024
• Litedown 2025 => minimalisme !

Focus Jupyter & Quarto

Nombreuses fonctionnalités

• Équivalent à LaTeX (+ langage de programmation)
• Bibliographie, note bas de page, TOC, TOF…
• Feuille de style CSS & nombreux templates
• Interactivité (html, javascript)
• Et bien plus avec Quarto !

Différents type de publication

• Article
• Diaporama
  
• Livre
• Manuel
• Cours & Exercice
• Tutoriel interactif
  
• Blog & Site web
• Rapport statistique
• curriculum vitae
• Poster
• …

Jupyter VS Quarto ?

• Quarto agnostique ? il inclut V8 / Deno / etc.

=> mauvais élève pour la reproductibilité.

=> Quarto supporte les moteurs knitr et jupyter, quid de l’inverse ?

• Jupyter est en structuration

=> son écosystème peut être plus intégré

=> ses qualités sont inégales dans les fonctionalités proposées (thèmes, diversités de formats, documentation, etc.)

Outsiders ?

• Blogdown{_target=“blank”}

• Bookdown: exemple{_target=“blank”}

• Litedown{_target=“blank”}

  • Slide1{_target=“blank”}

  • Slide2{_target=“blank”}

Yihui Xie

Recall : Why do we use Markdown ? for Simplicity.
What was Markdown invented for ? HTML
Make Markdown Html Again, do one thing and do it well.

6. adopter des pratiques émergentes

Des réseaux : gt notebook, inachevé d’imprimer, rfrr etc.

Annexes

Polymorphisme, multiplicité et plurilinguisme

Définir le document computationnel ?

Ré-écriture WC Knuth avec noweb qui ajoute du html

Il s’agit d’une autre forme de LP (utilisant les liens hypertextes) pour rendre la lecture du code intelligible.

Polymorphisme, multiplicité et plurilinguisme

Retour sur le literate programming

Une culture ? L’exemple de la commande shell Unix word count wc

Knuth : came from algorithms

McIlroy : came from Unix.

tr -cs A-Za-z '\n' |
tr A-Z a-z |
sort |
uniq -c |
sort -rn |
sed ${1}q

• Make one-word lines by transliterating the complement (-c) of the alphabet into newlines (note the quoted newline), and squeezing out (-s) multiple newlines.
• Transliterate upper case to lower case.
• Sort to bring identical words together.
• Replace each run of duplicate words with a single representative and include a count (-c).
• Sort in reverse (-r) numeric (-n) order.
• Pass through a stream editor; quit (q) after printing the number of lines designated by the script’s first parameter (${1})

Polymorphisme, multiplicité et plurilinguisme

Quelques exemples : entre récits dominants et marginaux

Polymorphisme, multiplicité et plurilinguisme

Cultures scientifiques : humanités numériques, data sciences et méthodes en SHS etc.

Préalable au Focus Jupyter & Quarto

Pour du logiciel :

• NoWeb 1989, agnostic (Norman Ramsey)
• Web / CWeb , Pascal & C
• Inform

Pour du Notebook :

• RMarkdown, Litedown (2025), Yihui Xie
• org-mode & org-babel (Eric Schulte & al.)

Abelson, Harold, Gerald Jay Sussman, Julie Sussman, et Alan Jay Préfacier Perlis. 1985. Structure and interpretation of computer programs. Cambridge (Mass.), Etats-Unis d’Amérique, Royaume-Uni de Grande-Bretagne et d’Irlande du Nord.

Antunes, Benjamin, et David R. C. Hill. 2024. « Reproducibility, Replicability and Repeatability: A survey of reproducible research with a focus on high performance computing ». Computer Science Review 53: 100655. https://doi.org/https://doi.org/10.1016/j.cosrev.2024.100655.

Barba, Lorena A. 2018. « Terminologies for Reproducible Research ». https://arxiv.org/abs/1802.03311.

Claerbout, J F. 1985. Fundamentals of Geophysical Data Processing. Pennwell Books,Tulsa, OK. https://www.osti.gov/biblio/5783154.

Dellaiera, Pol. 2025. « Reproducibility in Software Engineering ». Zenodo. https://doi.org/10.5281/zenodo.15315531.

Hernández, José Armando, et Miguel Colom. 2023. « Repeatability, Reproducibility, Replicability, Reusability (4R) in Journals’ Policies and Software/Data Management in Scientific Publications: A Survey, Discussion, and Perspectives ». https://arxiv.org/abs/2312.11028.

Knuth, D. E. 1984. « Literate Programming ». The Computer Journal 27 (2): 97‑111. https://doi.org/10.1093/comjnl/27.2.97.

Marwick B, Mullen L., Boettiger C. 2018. « Packaging data analytical work reproducibly using R (and friends) ». PeerJ. https://doi.org/https://doi.org/10.7287/peerj.preprints.3192v2.

Marwick, Ben. 2017. « Marwick, B. Computational Reproducibility in Archaeological Research: Basic Principles and a Case Study of Their Implementation. » Journal of Archaeolical Method Theory 24. https://doi.org/https://doi.org/10.1007/s10816-015-9272-9.

Rey-Coyrehourcq, Sébastien, Robin Cura, Laure Nuninger, Julie Gravier, Lucie Nahassia, et Ryma Hachi. 2017. « Peupler la terre, édité par Léna Sanders, Vers une recherche reproductible dans un cadre interdisciplinaire ». In. Presses universitaires François-Rabelais. https://doi.org/https://doi.org/10.4000/books.pufr.10647.

Schultz, Emilien. 2023. « Du laboratoire à Jupyter : La trajectoire d’un instrument logiciel libre de la science ouverte ». https://hal.science/hal-04316428.

« The First Notebook War - Yihui Xie 谢益辉 ». s. d. Consulté le 24 juin 2025. https://yihui.org/en/2018/09/notebook-war/#11-notebooks-make-it-hard-to-teach-well.