mirror of
https://github.com/CatalaLang/catala.git
synced 2024-09-16 14:57:13 +03:00
docs(contributing): update the CONTRIBUTING.md catala code examples
This commit is contained in:
EmileRolley
parent
86d0476b58
commit
98beaf850c
@ -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:
|
||||
<your code goes here>
|
||||
*/
|
||||
```
|
||||
~~~
|
||||
|
||||
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
|
||||
|
||||
<your structure/enumeration/scope declarations goes here>
|
||||
*/
|
||||
@@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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user