Documentation: cheat sheet and tutorial

doc/syntax/syntax.tex

@@ -13,7 +13,7 @@
 \newcommand{\li}[1]{\texttt{#1}}
 \begin{document}
 \begin{center}
-  2022-02-09
+  2022-02-28
   \hfill
   {\Huge\bfseries\sffamily
     Catala Syntax Cheat Sheet}
@@ -109,8 +109,8 @@
   \section*{Metadata declaration}
   \begin{tabular}{p{0.22\columnwidth}p{0.3\columnwidth}p{0.425\columnwidth}}
     \toprule
-    Feature                 & English syntax & French syntax \\\midrule
+    Feature                       & English syntax & French syntax \\\midrule
-    Structure declaration   &
+    Structure declaration         &
     \vspace*{-1.75em}
     \begin{minted}{catala_en}
 ```catala
@@ -120,7 +120,7 @@ declaration structure Foo:
 ```
 \end{minted}
     \vspace*{-1.75em}
-                            &
+                                  &
     \vspace*{-1.75em}
     \begin{minted}{catala_fr}
 ```catala
@@ -131,7 +131,7 @@ déclaration structure Foo:
 \end{minted}
     \vspace*{-1.75em}
     \\
-    Enumeration declaration &
+    Enumeration declaration       &
     \vspace*{-1.75em}
     \begin{minted}{catala_en}
 ```catala
@@ -141,7 +141,7 @@ declaration enumeration Foo:
 ```
 \end{minted}
     \vspace*{-1.75em}
-                            &
+                                  &
     \vspace*{-1.75em}
     \begin{minted}{catala_fr}
 ```catala
@@ -150,8 +150,8 @@ déclaration énumeration Foo:
   -- Baz
 ```
 \end{minted}
-    \vspace*{-1.75em}                                        \\
+    \vspace*{-1.75em}                                              \\
-    Scope declaration       &
+    Scope declaration             &
     \vspace*{-1.75em}
     \begin{minted}{catala_en}
 ```catala
@@ -162,7 +162,7 @@ declaration scope Foo:
 ```
 \end{minted}
     \vspace*{-1.75em}
-                            &
+                                  &
     \vspace*{-1.75em}
     \begin{minted}{catala_fr}
 ```catala
@@ -172,8 +172,8 @@ déclaration champ d'application Foo:
   contexte fizz champ d'application Buzz
 ```
 \end{minted}
-    \vspace*{-1.75em}                                        \\
+    \vspace*{-1.75em}                                              \\
-    Input-output qualifiers &
+    Input-output qualifiers       &
     \vspace*{-1.75em}
     \begin{minted}{catala_en}
 ```catala
@@ -186,7 +186,7 @@ context output boz content ...
 ```
 \end{minted}
     \vspace*{-1.75em}
-                            &
+                                  &
     \vspace*{-1.75em}
     \begin{minted}{catala_fr}
 ```catala
@@ -198,7 +198,27 @@ contexte biz contenu ...
 contexte sortie boz contenu ...
 ```
 \end{minted}
-    \vspace*{-1.75em}                                        \\
+    \vspace*{-1.75em}                                              \\
+    State transitions declaration &
+    \vspace*{-1.75em}
+    \begin{minted}{catala_en}
+```catala
+internal foo content ...
+  state bar
+  state buzz
+```
+\end{minted}
+    \vspace*{-1.75em}
+                                  &
+    \vspace*{-1.75em}
+    \begin{minted}{catala_fr}
+```catala
+interne foo contenu ...
+  état bar
+  état buzz
+```
+\end{minted}
+    \vspace*{-1.75em}                                              \\
     \bottomrule
   \end{tabular}
 
@@ -478,7 +498,7 @@ vrai    faux
 
   \section*{Scope use and related items}
   \begin{center}
-    \begin{tabular}{p{0.22\columnwidth}p{0.35\columnwidth}p{0.35\columnwidth}}
+    \begin{tabular}{p{0.22\columnwidth}p{0.36\columnwidth}p{0.35\columnwidth}}
       \toprule
       Feature                                 & English syntax & French syntax \\\midrule
       Scope use                               &
@@ -656,6 +676,23 @@ exception definition bar ...
 ```catala
 exception définition bar ...
 ```
+\end{minted}
+      \vspace*{-1.75em}
+      \\
+      State definition                        &
+      \vspace*{-1.75em}
+      \begin{minted}{catala_en}
+```catala
+definition foo state bar equals ...
+```
+\end{minted}
+      \vspace*{-1.75em}
+                                              &
+      \vspace*{-1.75em}
+      \begin{minted}{catala_fr}
+```catala
+définition foo état bar égal à ...
+```
 \end{minted}
       \vspace*{-1.75em}
       \\

examples/tutorial_en/tutorial_en.catala_en

@@ -588,6 +588,51 @@ scope BasisForFineDetermination :
   consequence equals $500
 ```
 
+## One variable, multiple states
+
+When a quantity is mentioned it the law, it does not always maps exactly to
+an unique Catala variable. More precisely, it often happens that the law defines
+an unique quantity with multiple computation steps, each new one building on the
+previous one. Here is an example of such a setup and how to deal with it thanks
+to a dedicated Catala feature.
+
+Under the hood, the different states of a Catala variable are implemented by
+distinct variables inside the lower intermediate representations of the
+language.
+
+### Article 8
+
+For taxation purposes, the values of the building operated for charity
+purposes can be deducted from the wealth of the individual, which is then
+capped at $2,500,000.
+
+```catala
+declaration scope WealthTax:
+  input value_of_buildings_used_for_charity content money
+  input total_wealth content money
+  internal wealth content money
+    # After the type of the variable, we can define the ordered list of states
+    # that the variable shall take before computing its final value. In each
+    # state, we'll be able to refer to the value of the previous state.
+    state total
+    state after_charity_deductions
+    state after_capping
+
+scope WealthTax:
+  definition wealth state total equals total_wealth
+  definition wealth state after_charity_deductions equals
+    wealth - # Here, "wealth" refers to the state "total"
+      value_of_buildings_used_for_charity
+  definition wealth state after_capping equals
+    if wealth >= $2,500,000 then $2,500,000 else wealth
+    # Here, "wealth" refers to the state "after_charity_decuctions"
+
+  assertion wealth > $0
+  # Outside of the definition of "wealth", "wealth" always refer to the final
+  # state of the variable, here "after_capping".
+
+```
+
 ## Catala values
 
 So far, this tutorial has introduced you to the basic structure of Catala