Update READMEs

CONTRIBUTING.md

@@ -10,14 +10,14 @@ any questions about the project.
 If you want to contribute to the project on a longer-term basis, or if you have
 specific competences as a socio-fiscal lawyer or a programming language specialist,
 please [contact the authors](mailto:contact@catala-lang.org).
-The Catala team meets over visioconference once every two weeks.
+The Catala team meets over visioconference once every week.
 
 Please note that the copyright of this code is owned by Inria;
 by contributing, you disclaim all copyright interests in favor of Inria.
 Both the code for the compiler and the examples in this repository are
 distributed under the Apache2 license.
 
-### Writing Catala code
+## Writing Catala code
 
 Before writing Catala code, please read the
 [tutorial](https://catala-lang.org/en/examples/tutorial). You can run the
@@ -47,6 +47,8 @@ using for instance
 
 ```
 make -C examples/foo foo.tex
+make -C examples/foo foo.py
+make -C examples/foo foo.ml
 ```
 
 to see if you've made any syntax errors. Once the text formatting is done, you
@@ -87,7 +89,7 @@ You can look at the
 [online OCaml documentation](https://catala-lang.org/ocaml_docs/) for the
 different modules' interfaces as well as high-level architecture documentation.
 
-Please note that the `ocamlformat` version this project uses is `0.18.0`.
+Please note that the `ocamlformat` version this project uses is `0.19.0`.
 Using another version may cause spurious diffs to appear in your pull requests.
 
 ### Example: adding a builtin function
@@ -114,7 +116,7 @@ need more, here is how one can be added:
     - in `dcalc/interpreter.ml`, function `evaluate_operator`
 - Update the syntax guide in `doc/syntax/syntax.tex` with your new builtin
 
-## Internationalization
+### Internationalization of the Catala syntax
 
 The Catala language should be adapted to any legislative text that follows a
 general-to-specifics statutes order. Therefore, there exists multiple versions
@@ -124,12 +126,14 @@ Currently, Catala supports English, French and Polish legislative text via the
 `--language=en`, `--language=fr` or `--language=pl` options.
 
 To add support for a new language:
+
 - the basic syntax localisation is defined in
   `compiler/surface/lexer_xx.cppo.ml` where `xx` is the language code (`en`,
   `fr`...)
 - copy the files from another language, e.g.
   [english](compiler/surface/lexer_en.cppo.ml), then replace the strings with your
   translations. Be careful with the following:
+
   - The file must be encoded in latin-1
   - For a given token `FOO`, define `MS_FOO` to be the string version of the
     keyword. Due to the encoding, use `\xNN` [escape
@@ -138,13 +142,12 @@ To add support for a new language:
   - If the string contains spaces or non-latin1 characters, you need to define
     `MR_FOO` as well with a regular expression in [sedlex
     format](https://github.com/ocaml-community/sedlex#lexer-specifications).
-    Replace spaces with `", space_plus, "`, and unicode characters with `",
-    0xNNNN, "` where `NNNN` is the hexadecimal unicode codepoint.
+    Replace spaces with `", space_plus, "`, and unicode characters with `", 0xNNNN, "` where `NNNN` is the hexadecimal unicode codepoint.
 
   **Hint:** You may get syntax errors with unhelpful locations because of
-  `sedlex`. In that case the command `ocamlc
-  _build/default/compiler/surface/lexer_xx.ml` may point you to the source of the
+  `sedlex`. In that case the command `ocamlc _build/default/compiler/surface/lexer_xx.ml` may point you to the source of the
   error.
+
 - add your translation to the compilation rules:
   - in `compiler/surface/dune`, copying another `parser_xx.cppo.ml` rule
   - in the `extensions` list in `compiler/driver.ml`

README.md

@@ -87,6 +87,12 @@ The Catala language is the only programming language to our knowledge that
 embeds default logic as a first-class feature, which is why it is the only
 language perfectly adapted to literate legislative programming.
 
+## Getting started
+
+To get started, the best place is the [tutorial](https://catala-lang.org/en/examples/tutorial)
+of the language. A [French version](https://catala-lang.org/fr/examples/tutoriel)
+is also available but might be out of sync with the latest language features.
+
 ## Building and installation
 
 Catala is available as an [opam package](https://opam.ocaml.org/packages/catala/)!
@@ -108,7 +114,8 @@ want to compile it from the sources of this repository or use nix. For that, see
 ### Catala
 
 Use `catala --help` if you have installed it to get more information about the command line
-options available. To get the development version of the help, run `make help_catala`
+options available. The man page is also [available online](https://catala-lang.org/en/doc/catala).
+To get the development version of the help, run `make help_catala`
 after `make build`. The `catala` binary corresponds to the Catala compiler.
 
 The top-level `Makefile` contains a lot of useful targets to run. To display
@@ -123,6 +130,29 @@ options available. To get the development version of the help, run `make help_cl
 after `make build`. The `clerk` binary corresponds to the Catala build system,
 responsible for testing among other things.
 
+## Documentation
+
+### Syntax cheat sheet
+
+A complete and handy reference of the Catala syntax can be found in the
+[cheat sheet](doc/syntax/syntax.pdf) (for French and English versions
+of the syntax).
+
+### Formal semantics
+
+To audit the formal proof of the partial certification of the Catala compiler,
+see [the dedicated readme](doc/formalization/README.md).
+
+### Compiler documentation
+
+The compiler documentation is auto-generated from its source code using
+`dune` and `odoc`. Use
+
+    make doc
+
+to generate the documentation, then open the `doc/odoc.html` file in any browser.
+The documentation is also accessible [online](https://catala-lang.org/ocaml_docs/).
+
 ## Examples
 
 To explore the different programs written in Catala, see
@@ -143,23 +173,6 @@ To know how you can contribute to the project, see
 To know how to run or improve the Catala reference test suite,
 see [the dedicated readme](tests/README.md).
 
-## Documentation
-
-### Formal semantics
-
-To audit the formal proof of the partial certification of the Catala compiler,
-see [the dedicated readme](doc/formalization/README.md).
-
-### Compiler documentation
-
-The compiler documentation is auto-generated from its source code using
-`dune` and `odoc`. Use
-
-    make doc
-
-to generate the documentation, then open the `doc/odoc.html` file in any browser.
-The documentation is also accessible [online](https://catala-lang.org/ocaml_docs/).
-
 ## License
 
 The compiler and all the code contained in this repository is released under

examples/tutoriel_fr/tutoriel_fr.catala_fr

@@ -6,6 +6,13 @@ législatifs avec ce langage. Ce document s'adresse principalement à des dével
 ou des personnes ayant déjà programmé, même si des juristes avec des appétences
 en informatique devraient pouvoir s'en sortir.
 
+```catala
+# Attention, ce tutoriel en français n'est peut-être pas à jour avec
+# les dernières fonctionnalités du langage. En effet, le tutoriel en anglais
+# disponible sur https://catala-lang.org/en/examples/tutorial constitue
+# la référence pour le langage.
+```
+
 ### Programmation littéraire
 
 Pour commencer à écrire un programme Catala, vous devez partir du texte