diff --git a/examples/allocations_logement/arrete_2019-09-27.catala_fr b/examples/allocations_logement/arrete_2019-09-27.catala_fr
index ec58f9f1..b7cbee64 100644
--- a/examples/allocations_logement/arrete_2019-09-27.catala_fr
+++ b/examples/allocations_logement/arrete_2019-09-27.catala_fr
@@ -58,6 +58,11 @@ Nota: Conformément au I de l’article 3 de l’arrêté du 23 septembre 2021,
 pour les prestations dues à compter du 1er octobre 2021.
 
 ```catala-metadata
+# Dans la suite de l'arrêté, il n'est pas fait référence à la situation
+# familiale dans toute sa complexité (voir énumération SituationFamiliale)
+# mais uniquement à la distinction entre une personne seule, un couple et
+# un nombre de personnes à charge. Pour ne pas avoir à répéter du code
+# nous définissons donc cette situation familiale simplifiée ici.
 déclaration énumération SituationFamilialeCalculAPL:
   -- PersonneSeule
   -- Couple
@@ -441,7 +446,7 @@ Personne seule ou couple ayant :
 
 ```catala
 champ d'application CalculAidePersonnelleLogementLocatif
-  sous condition date_courante >=@ |2021-10-01|:
+  sous condition date_courante >=@ |2022-01-01|:
   définition abattement_forfaitaire_d823_17 égal à
     si nombre_personnes_à_charge = 0 alors
       selon situation_familiale_calcul_apl sous forme
@@ -2609,7 +2614,9 @@ Le coefficient relatif au calcul de la dépense nette minimale prévu par l'arti
 1° 0,0172 dans le cas des logements améliorés par leur propriétaire occupant ;
 
 2° Dans les autres cas :
+
 a) 0,0226 pour les prêts souscrits avant le 1er octobre 1998 ;
+
 b) 0,0234 pour les prêts souscrits à compter de cette dernière date.
 
 ```catala
diff --git a/examples/allocations_logement/code_construction_legislatif.catala_fr b/examples/allocations_logement/code_construction_legislatif.catala_fr
index 1e8f1882..6fc02c63 100644
--- a/examples/allocations_logement/code_construction_legislatif.catala_fr
+++ b/examples/allocations_logement/code_construction_legislatif.catala_fr
@@ -16,9 +16,13 @@ aux bénéficiaires de ces aides afin qu'ils déménagent pour s'assurer
 des conditions de logement plus adaptées sont régies par le présent livre.
 
 Les aides personnelles au logement comprennent :
+
 1° L'aide personnalisée au logement ;
+
 2° Les allocations de logement :
+
 a) L'allocation de logement familiale ;
+
 b) L'allocation de logement sociale.
 
 ```catala-metadata
@@ -277,6 +281,7 @@ l'action sociale et des familles.
 # donne le même résultat, on ne devrait pas avoir à les prioriser les unes par
 # rapport aux autres. On pourrait rajouter un sucre syntaxique pour activer
 # ça en vérifiant que les conséquences sont syntaxiquement les mêmes.
+# Voir https://github.com/CatalaLang/catala/issues/208
 champ d'application ÉligibilitéAidePersonnelleLogement:
   exception l822_5_2 définition patrimoine_pris_en_compte
   sous condition ménage.logement.est_ehpad_ou_maison_autonomie_l313_12_asf
@@ -327,7 +332,7 @@ logement. Cette condition est appréciée pour chacun des membres du ménage.
 
 
 ```catala
-# todo juridique: la condition, si elle est vérifiée par un membre du ménage
+# TODO juridique: la condition, si elle est vérifiée par un membre du ménage
 # enlève-t-elle le droit aux APL pour l'ensemble des membres du ménage ?
 
 # Pour l'instant l'interpretation est que aucun membre du ménage ne doit être
@@ -346,8 +351,6 @@ l'article 6 de la loi n° 89-462 du 6 juillet 1989 tendant à améliorer les rap
 locatifs et portant modification de la loi n° 86-1290 du 23 décembre 1986.
 
 ```catala
-# TODO informatique: structure inverse de la structure avec des conditions
-# chainées
 champ d'application ÉligibilitéAidePersonnelleLogement:
   règle condition_non_ouverture_l822_9_decence_logement
   sous condition non ménage.logement.logement_decent_l89_462
@@ -371,8 +374,6 @@ L'attribution d'une aide personnelle au logement est subordonnée au
 respect de conditions de peuplement des logements.
 
 ```catala
-# TODO informatique: structure inverse de la structure avec des conditions
-# chainées
 champ d'application ÉligibilitéAidePersonnelleLogement:
   règle condition_non_ouverture_l822_10_peuplement_logement
   sous condition condition_peuplement_logement_l822_10
@@ -631,7 +632,8 @@ par le chapitre III du titre V du livre III ;
 
 ```catala
 champ d'application ÉligibilitéAidePersonnelleLogement:
-  # TODO: citer cet exemple intéréssant d'un point de vue computationel.
+  # TODO recherche: citer cet exemple intéréssant d'un point de vue
+  # computationel.
   # Ici attention à la structure d'exception! Le 2°) est le cas de base, le
   # 4°) est une exception au 2°) plus permissive que le cas de base, tandis
   # que le 3°) est une exception plus stricte que le cas de base. Si 3°) et
@@ -709,8 +711,6 @@ mentionné au 1° ou au 6° de l'article L. 831-1 signé après le 31 décembre
 n'ouvrent pas droit à l'aide personnalisée au logement.
 
 ```catala
-# TODO informatique: vérifier que cette exception a un groupe lui même
-# exception a un groupe est bien encodé dans le calcul par défaut.
 champ d'application ÉligibilitéAidePersonnelleLogement:
   étiquette l831_2_base règle condition_logement_prêt rempli
   # Cas de base implicite
@@ -1017,5 +1017,3 @@ logement pour l'application des articles L. 843-1 à L. 843-4.
 
 
 
-#### Titre VI : Dispositions particulières à l'outre-mer
-
diff --git a/examples/allocations_logement/code_construction_reglementaire.catala_fr b/examples/allocations_logement/code_construction_reglementaire.catala_fr
index f7839e84..ceae4f9d 100644
--- a/examples/allocations_logement/code_construction_reglementaire.catala_fr
+++ b/examples/allocations_logement/code_construction_reglementaire.catala_fr
@@ -68,7 +68,7 @@ Lorsque les conditions d'ouverture du droit à l'aide personnalisée au logement
 sont remplies au titre d'un logement, seule cette aide est attribuée pour ce logement.
 
 ```catala
-# TODO: quelles autres aides aux logements pourraient concurrencer les APL?
+# TODO juridique: quelles autres aides aux logements pourraient concurrencer les APL?
 ```
 
 ####### Article R821-6 | LEGIARTI000038879011
@@ -514,7 +514,8 @@ il est opéré sur ses ressources un abattement de :
 champ d'application RessourcesAidePersonnelleLogement:
   définition abattement_r_822_10 égal à
     selon situation_familiale sous forme
-    # TODO: améliorer avec https://github.com/CatalaLang/catala/issues/203 ou
+    # TODO informatique: améliorer avec
+    # https://github.com/CatalaLang/catala/issues/203 ou
     # https://github.com/CatalaLang/catala/issues/199
     -- Célibataire:
       (si nombre de personnes_à_charge = 0 alors 0 €
@@ -851,7 +852,7 @@ champ d'application RessourcesAidePersonnelleLogement:
      demandeur_poursuit_des_études
   conséquence égal à ressources_forfaitaires_r822_20
 
-# Le montant minoré sera défini plus tard, et donc constituera une définition
+# Le montant minoré sera défini plus tard, et donc constituera une exception
 # au cas de base de ressources_forfaitaires_r822_20
 ```
 
@@ -1025,7 +1026,7 @@ plus.
 
 ```catala
 champ d'application ÉligibilitéAidePersonnelleLogement:
-  # TODO : remplacer par variables locales
+  # TODO informatique : remplacer par variables locales
   définition nombre_personnes_logement égal à
     (selon ménage.situation_familiale sous forme
       -- Célibataire: 1
@@ -1802,7 +1803,7 @@ La participation personnelle du ménage, mentionnée au 4° de l'article D. 823-
 la somme d'une participation minimale et d'une participation au titre des ressources
 du ménage, calculée selon la formule suivante :
 
-" Pp = P0 + Tp* (R-R0) "
+$$\text{Pp} = \text{P0} + \text{Tp}* (\text{R}-\text{R0})$$
 
 ```catala
 champ d'application CalculAidePersonnelleLogementLocatif:
@@ -1845,7 +1846,7 @@ champ d'application CalculAidePersonnelleLogementLocatif:
 ```catala
 champ d'application CalculAidePersonnelleLogement:
   définition ressources_ménage état avec_arrondi égal à
-    # Cette formule arrondit à la centaine d'euros supérieure. Essayer quelques
+    # Cette formule arrondit à la centaine d'euros supérieure. Essayez quelques
     # exemples pour vous en convaincre, dont 100 et 150.
     arrondi_argent de ((ressources_ménage +€ 49,99€) *€ 1%) *€ 100,0
 ```
@@ -3111,13 +3112,15 @@ II du présent livre et arrondies à la centaine d'euros supérieure ;
 
 4° " N " représente le nombre de parts déterminé selon le barème suivant :
 
-bénéficiaire isolé                                             |     1,4    |
-ménage sans personne à charge                                  |     1,8    |
-bénéficiaire isolé ou ménage ayant une personne à charge       |     2,5    |
-bénéficiaire isolé ou ménage ayant deux personnes à charge     |     3,0    |
-bénéficiaire isolé ou ménage ayant trois personnes à charge    |     3,7    |
-bénéficiaire isolé ou ménage ayant quatre personnes à charge   |     4,3    |
-majoration par personne à charge supplémentaire                |     0,5    |
+------------------------------------------------------------ ---
+bénéficiaire isolé                                           1,4
+ménage sans personne à charge                                1,8
+bénéficiaire isolé ou ménage ayant une personne à charge     2,5
+bénéficiaire isolé ou ménage ayant deux personnes à charge   3,0
+bénéficiaire isolé ou ménage ayant trois personnes à charge  3,7
+bénéficiaire isolé ou ménage ayant quatre personnes à charge 4,3
+majoration par personne à charge supplémentaire              0,5
+------------------------------------------------------------ ---
 
 ```catala
 champ d'application CalculAidePersonnelleLogementAccessionPropriété:
@@ -3297,6 +3300,8 @@ champ d'application CalculAidePersonnelleLogement:
     catégorie_calcul_apl sous forme AccessionPropriété
   conséquence égal à faux
 
+  # TODO recherche: citer cette structure de calcul comme un bon cas d'usage
+  # de la fonctionnalité "contexte" de Catala.
   définition accession_propriété.équivalence_minimale_loyer égal à
     logement_foyer.équivalence_minimale_loyer
 
diff --git a/examples/allocations_logement/code_sécurité_sociale.catala_fr b/examples/allocations_logement/code_sécurité_sociale.catala_fr
index 33cb8b8a..ca74de0c 100644
--- a/examples/allocations_logement/code_sécurité_sociale.catala_fr
+++ b/examples/allocations_logement/code_sécurité_sociale.catala_fr
@@ -250,7 +250,8 @@ champ d'application ÉligibilitéAidePersonnelleLogement:
   conséquence égal à 10 838,40€
 
 # TODO juridique: trouver les décrets définissant les montants pour
-# 2021 et 2022
+# 2021 et 2022. Pour l'instant nous n'avons trouvé qu'une circulaire de
+# la CNAV, voir autres_sources.catala_fr.
 ```
 
 b) Lorsque les deux conjoints, concubins ou partenaires liés par un pacte civil
diff --git a/examples/allocations_logement/prologue.catala_fr b/examples/allocations_logement/prologue.catala_fr
index 490f5e13..687f5eb3 100644
--- a/examples/allocations_logement/prologue.catala_fr
+++ b/examples/allocations_logement/prologue.catala_fr
@@ -1,5 +1,11 @@
 # Prologue
 
+Avant de présenter les textes réglementaires qui régissent le calcul des
+allocations logement, il est nécessaire de définir les structures de données
+informatiques qui modélisent la situation dont parlent ces textes législatifs.
+Vous pouvez passer cette section pour aller directement au textes législatifs
+dans les sections suivantes.
+
 ## Types de données manipulées par le programme
 
 ### Calcul et éligibilité de l'aide personnelle au logement