diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78532625..a273f3f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,48 +1,48 @@ # Contributing to Catala -The project is open to external contributions, in the spirit of open source. +The project is open to external contributions, in the spirit of open source. If you want to open a pull request, please follow the instructions below. -To ask a question to the Catala team, please open an issue on this repository. -You can also join the [Zulip chat](https://zulip.catala-lang.org/) to ask +To ask a question to the Catala team, please open an issue on this repository. +You can also join the [Zulip chat](https://zulip.catala-lang.org/) to ask 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, +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. 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 +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 -Before writing Catala code, please read the -[tutorial](https://catala-lang.org/en/examples/tutorial). You can run the -programs of the tutorial yourself by following the instruction in the -[README of the `examples` directory](examples/README.md). Then, it is suggested -that you create a new example directory again according to the instructions of +Before writing Catala code, please read the +[tutorial](https://catala-lang.org/en/examples/tutorial). You can run the +programs of the tutorial yourself by following the instruction in the +[README of the `examples` directory](examples/README.md). Then, it is suggested +that you create a new example directory again according to the instructions of this README. Let us now present the typical Catala workflow. First, you need to locate -the legislative text that you want to use as a reference. Then, simply +the legislative text that you want to use as a reference. Then, simply copy-paste the text into your source file. -First you will have to format the copy-pasted text using Catala headings +First you will have to format the copy-pasted text using Catala headings and articles markers: -``` -@@Heading@@ +```markdown +## Heading -@@Sub-heading (the more +, the less important)@@++ +### Sub-heading (the more +, the less important) -@Legislative atom@ +#### [Legislative atom] ``` -Please look at the code of other examples to see how to format things properly. -While formatting the text, don't forget regularly to try and parse your example +Please look at the code of other examples to see how to format things properly. +While formatting the text, don't forget regularly to try and parse your example using for instance @@ -50,57 +50,59 @@ using for instance make -C examples/foo foo.tex ``` -to see if you've made any syntax errors. Once the text formatting is done, you -can start to annotate each legislative atom (article, provision, etc.) with +to see if you've made any syntax errors. Once the text formatting is done, you +can start to annotate each legislative atom (article, provision, etc.) with some Catala code. To open up a code section in Catala, simply use -``` -/* +~~~markdown +```catala # In code sections, comments start with # scope Foo: -*/ ``` +~~~ -While all the code sections are equivalent in terms of execution, you can -mark some as "metadata" so that they are printed differently on lawyer-facing +While all the code sections are equivalent in terms of execution, you can +mark some as "metadata" so that they are printed differently on lawyer-facing documents. Here's how it works: -``` -@@Begin metadata@@ # @@Début métadonnées@@ en français -/* +~~~markdown +> Begin metadata # > Début métadonnées en français + +```catala declaration structure FooBar: data foo content boolean data bar content money -*/ -@@End metadata@@ # @@Fin métadonnées@@ en français ``` -Again, make sure to regularly check that your example is parsing correctly. The error message from the compiler should help you debug the syntax if need be. You can also +> End metadata # > Fin métadonnées en français +~~~ + +Again, make sure to regularly check that your example is parsing correctly. The error message from the compiler should help you debug the syntax if need be. You can also live-test the programs you wrote by feeding them to the interpreter -(see the [README of the `examples` directory](examples/README.md)); this will +(see the [README of the `examples` directory](examples/README.md)); this will also type-check the programs, which is useful for debugging them. ## Working on the compiler -The Catala compiler is a standard dune-managed OCaml project. -You can look at the -[online OCaml documentation](https://catala-lang.org/ocaml_docs/) for the +The Catala compiler is a standard dune-managed OCaml project. +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. ## Internationalization -The Catala language should be adapted to any legislative text that follows a -general-to-specifics statutes order. Therefore, there exists multiple versions +The Catala language should be adapted to any legislative text that follows a +general-to-specifics statutes order. Therefore, there exists multiple versions of the Catala surface syntax, adapted to the language of the legislative text. -Currently, Catala supports English and French legislative text via the -`--language=en` or `--language=fr` option. +Currently, Catala supports English and French legislative text via the +`--language=en` or `--language=fr` option. -Technically, support for new languages can be added via a new lexer. If you want -to add a new language, you can start from -[existing lexer examples](src/catala/catala_surface/lexer_fr.ml), tweak and open -a pull request. If you don't feel familiar enough with OCaml to do so, please +Technically, support for new languages can be added via a new lexer. If you want +to add a new language, you can start from +[existing lexer examples](src/catala/catala_surface/lexer_fr.ml), tweak and open +a pull request. If you don't feel familiar enough with OCaml to do so, please leave an issue on this repository.