From d704998f8192d9c8a07904192fe0db5c437d7909 Mon Sep 17 00:00:00 2001 From: Denis Merigoux Date: Sun, 13 Feb 2022 23:40:23 +0100 Subject: [PATCH] Update READMEs --- CONTRIBUTING.md | 19 +++++---- README.md | 49 ++++++++++++++-------- examples/tutoriel_fr/tutoriel_fr.catala_fr | 7 ++++ 3 files changed, 49 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 973249a6..f56ebf0d 100644 --- a/CONTRIBUTING.md +++ b/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` diff --git a/README.md b/README.md index 702cf8f0..03d75566 100644 --- a/README.md +++ b/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 diff --git a/examples/tutoriel_fr/tutoriel_fr.catala_fr b/examples/tutoriel_fr/tutoriel_fr.catala_fr index 17a59d2e..602b835c 100644 --- a/examples/tutoriel_fr/tutoriel_fr.catala_fr +++ b/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