mirror of
https://github.com/CatalaLang/catala.git
synced 2024-11-10 06:37:54 +03:00
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# Contributing to Catala
|
|
|
|
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
|
|
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.
|
|
|
|
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
|
|
|
|
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
|
|
copy-paste the text into your source file.
|
|
|
|
First you will have to format the copy-pasted text using Catala headings
|
|
and articles markers:
|
|
|
|
```markdown
|
|
## Heading
|
|
|
|
### Sub-heading (the more '#', the less important)
|
|
|
|
#### [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
|
|
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
|
|
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
|
|
documents. Here's how it works:
|
|
|
|
~~~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
|
|
live-test the programs you wrote by feeding them to the interpreter
|
|
(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
|
|
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
|
|
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.
|
|
|
|
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.
|