mirror of
https://github.com/CatalaLang/catala.git
synced 2024-09-16 14:57:13 +03:00
More readmes
This commit is contained in:
Denis Merigoux
parent
4f8ec8191e
commit
03b019f102
101
CONTRIBUTING.md
Normal file
101
CONTRIBUTING.md
Normal file
@ -0,0 +1,101 @@
|
||||
# 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. 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 email the authors at denis.merigoux@inria.fr. The Catala team meets over visioconference once in a 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 examples
|
||||
|
||||
### Setting up the machinery
|
||||
|
||||
This section describes what to do to setup a working directory for a new Catala example, as well as the development cycle. Let us suppose that you want to create a new example named `foo`.
|
||||
|
||||
First, follow the instructions of [the installation readme](INSTALL.md) to get the compiler up and working up to `make build`. You can also set up the syntax highlighting for your editor.
|
||||
|
||||
Then, create the directory `examples/foo`. In there, create a master source file `foo.catala` that will be the root of your Catala program. You can then start programming in `foo.catala`, or split up your example into multiple files. In the later case, `foo.catala` must only contain something like this:
|
||||
|
||||
```
|
||||
@@Master file@@
|
||||
|
||||
@@Include: bar.catala@@
|
||||
```
|
||||
|
||||
where `examples/bar.catala` is another source file containing code for your example. Make sure you start by including some content in the source files, like
|
||||
|
||||
```
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
Now let's build the example, create a `Makefile` with the following contents:
|
||||
|
||||
```Makefile
|
||||
CATALA_LANG=en # or fr if your source code is in French
|
||||
SRC=foo.catala
|
||||
|
||||
include ../Makefile.common
|
||||
```
|
||||
|
||||
The `include` creates automatically all the targets you will need for your example. For instance, after making sure the compiler is built, you can launch
|
||||
|
||||
```
|
||||
make -C examples/foo foo.tex
|
||||
```
|
||||
|
||||
from the repository root to create the LaTeX weaving output of your source program. `Hello, world!` should appear in there.
|
||||
|
||||
Finally, please add a rule for your example in the repository root `Makefile` in the section "Examples-related rules", following the pattern for other examples. This will ensure that
|
||||
your example is built every time the compiler is modified; if a change in the compiler breaks your example, the authors will be notified and find a solution.
|
||||
|
||||
### Writing Catala code
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
@@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
|
||||
|
||||
```
|
||||
/*
|
||||
# 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:
|
||||
|
||||
```
|
||||
@@Begin metadata@@ # @@Début métadonnées@@ en français
|
||||
/*
|
||||
declaration structure FooBar:
|
||||
data foo content boolean
|
||||
data bar content amount
|
||||
|
||||
<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.
|
||||
|
||||
## 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.
|
||||
126
INSTALL.md
Normal file
126
INSTALL.md
Normal file
@ -0,0 +1,126 @@
|
||||
# Installing the Catala compiler
|
||||
|
||||
## Requirements
|
||||
|
||||
The Catala compiler is written using OCaml. To install OCaml on your machine and
|
||||
if you're running Linux ou MacOS, open a terminal and enter :
|
||||
|
||||
./install_opam.sh
|
||||
|
||||
This will install `opam`, the OCaml dependency manager and the
|
||||
base OCaml compiler. If you're on Windows, the simplest solution
|
||||
would be to use Cygwin or the Windows Subsystem for Linux. Catala has been tested
|
||||
with OCaml version 4.09.1. You can switch to this version by typing :
|
||||
|
||||
opam switch create 4.09.1
|
||||
|
||||
or
|
||||
|
||||
opam switch 4.09.1
|
||||
|
||||
if this version of OCaml is already installed. Next, install all the build
|
||||
dependencies with
|
||||
|
||||
make install-dependencies
|
||||
|
||||
This should ensure everything is set up for developping on the Catala compiler !
|
||||
|
||||
Other features for generation of files and literate programming also require
|
||||
the following executables to be present
|
||||
|
||||
man2html virtualenv python3 rsync
|
||||
|
||||
please install them if they're not here. On a Debian distribution, this can be
|
||||
done with
|
||||
|
||||
sudo apt install python3-dev python3-setuptools man2html rsync
|
||||
sudo python3 -m pip install --upgrade pip
|
||||
sudo python3 -m pip install virtualenv
|
||||
|
||||
On ArchLinux :
|
||||
|
||||
sudo pacman -S python-virtualenv man2html rsync
|
||||
|
||||
## Installation
|
||||
|
||||
The project is distributed as a Dune artifact. Use standard dune commands to build
|
||||
and install the library. Makefile aliases are here to help you: running
|
||||
|
||||
make build
|
||||
|
||||
builds the compiler from its OCaml sources.
|
||||
|
||||
|
||||
### Generating website assets
|
||||
|
||||
The Catala website features assets generated by the Catala compiler. They are
|
||||
needed to build the website. To produce them, simply run from this repository's
|
||||
root directory
|
||||
|
||||
./generate_website_assets.sh <path-to-catala-website>/assets
|
||||
|
||||
You will need the `man2html` executable to generate the HTML versions of the man
|
||||
pages, as well as the `rsync` executable to transfer files (preferred to `cp`)
|
||||
because it also works with a remote server.
|
||||
|
||||
### Opam package
|
||||
|
||||
If you want to install the library as an opam
|
||||
package, use the following command at the root of the repository:
|
||||
|
||||
opam install ./
|
||||
|
||||
You can then can the compiler using the `catala` command.
|
||||
|
||||
## Usage
|
||||
|
||||
Use `catala --help` to get more information about the command line options available.
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
The Catala language also comes with syntax highlighting to
|
||||
ease program development. The syntax highlighting is done
|
||||
with the [Iro](https://eeyo.io/iro/) compiler that allows
|
||||
writing the syntax only once, and then export it to formats
|
||||
understood by various IDE. Currently, two syntax
|
||||
highlighting plugins are under version control.
|
||||
|
||||
### Atom
|
||||
|
||||
To get Catala syntax highlighting in Atom, simply enter from
|
||||
the root of the repository, depending on the language you want to use :
|
||||
|
||||
make atom_fr
|
||||
or
|
||||
|
||||
make atom_en
|
||||
|
||||
You can now reload Atom and check that you have syntax highlighting on any `.catala` file.
|
||||
|
||||
### Pygments
|
||||
|
||||
Pygments is a Python-based versatile lexer for various
|
||||
programming languages. To use a version of Pygments
|
||||
augmented with the Catala plugin, simply enter
|
||||
|
||||
make pygments
|
||||
|
||||
This will execute the
|
||||
script `syntax_highlighting/fr/pygments/set_up_pygments.sh` and `syntax_highlighting/en/pygments/set_up_pygments.sh`.
|
||||
|
||||
The scripts set up a virtual environement in
|
||||
`syntax_highlighting/fr/pygments/pygments/env` or
|
||||
`syntax_highlighting/en/pygments/pygments/env`, which will
|
||||
contain the modified version of Pygments that has Catala
|
||||
support. If you want to hack something, it is possible to use this virtual
|
||||
environnement directly with
|
||||
|
||||
source syntax_highlighting/fr/pygments/pygments/env/bin/activate
|
||||
|
||||
or
|
||||
|
||||
source syntax_highlighting/en/pygments/pygments/env/bin/activate
|
||||
|
||||
The `pigmentize` executable, used for instance by the `minted` LaTeX package,
|
||||
will now point to the Catala-enabled version inside the virtual environment.
|
||||
This `source` setup is not necessary if you use the rules in the `Makefile`.
|
||||
140
README.md
140
README.md
@ -57,10 +57,10 @@ You will need to have a standard LaTeX distribution installed as well as the
|
||||
|
||||
To get that lawyer-readable version (which is a LaTeX-created) PDF, simply use
|
||||
|
||||
make allocations_familiales
|
||||
make -C allocations_familiales allocations_familiales.pdf
|
||||
|
||||
from the repository root, once you have managed to install the
|
||||
compiler (see below). You can then open `examples/allocations_familiales/allocations_familiales.pdf`
|
||||
compiler using [the dedicated readme](INSTALL.md). You can then open `examples/allocations_familiales/allocations_familiales.pdf`
|
||||
|
||||
## Languages
|
||||
|
||||
@ -83,143 +83,13 @@ However, the language is bound to have a complete formal semantics
|
||||
in the near future. This semantics will guide the compiler
|
||||
implementation.
|
||||
|
||||
## The Catala compiler
|
||||
## Installation
|
||||
|
||||
### Requirements
|
||||
|
||||
The Catala compiler is written using OCaml. To install OCaml on your machine and
|
||||
if you're running Linux ou MacOS, open a terminal and enter :
|
||||
|
||||
./install_opam.sh
|
||||
|
||||
This will install `opam`, the OCaml dependency manager and the
|
||||
base OCaml compiler. If you're on Windows, the simplest solution
|
||||
would be to use Cygwin or the Windows Subsystem for Linux. Catala has been tested
|
||||
with OCaml version 4.09.1. You can switch to this version by typing :
|
||||
|
||||
opam switch create 4.09.1
|
||||
|
||||
or
|
||||
|
||||
opam switch 4.09.1
|
||||
|
||||
if this version of OCaml is already installed. Next, install all the build
|
||||
dependencies with
|
||||
|
||||
make install-dependencies
|
||||
|
||||
This should ensure everything is set up for developping on the Catala compiler !
|
||||
|
||||
Other features for generation of files and literate programming also require
|
||||
the following executables to be present
|
||||
|
||||
man2html virtualenv python3 rsync
|
||||
|
||||
please install them if they're not here. On a Debian distribution, this can be
|
||||
done with
|
||||
|
||||
sudo apt install python3-dev python3-setuptools man2html rsync
|
||||
sudo python3 -m pip install --upgrade pip
|
||||
sudo python3 -m pip install virtualenv
|
||||
|
||||
On ArchLinux :
|
||||
|
||||
sudo pacman -S python-virtualenv man2html rsync
|
||||
|
||||
### Installation
|
||||
|
||||
The project is distributed as a Dune artifact. Use standard dune commands to build
|
||||
and install the library. Makefile aliases are here to help you: running
|
||||
|
||||
make build
|
||||
|
||||
builds the compiler from its OCaml sources.
|
||||
|
||||
|
||||
#### Generating website assets
|
||||
|
||||
The Catala website features assets generated by the Catala compiler. They are
|
||||
needed to build the website. To produce them, simply run from this repository's
|
||||
root directory
|
||||
|
||||
./generate_website_assets.sh <path-to-catala-website>/assets
|
||||
|
||||
You will need the `man2html` executable to generate the HTML versions of the man
|
||||
pages, as well as the `rsync` executable to transfer files (preferred to `cp`)
|
||||
because it also works with a remote server.
|
||||
|
||||
#### Opam package
|
||||
|
||||
If you want to install the library as an opam
|
||||
package, use the following command at the root of the repository:
|
||||
|
||||
opam install ./
|
||||
|
||||
You can then can the compiler using the `catala` command.
|
||||
|
||||
### Usage
|
||||
|
||||
Use `catala --help` to get more information about the command line options available.
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
The Catala language also comes with syntax highlighting to
|
||||
ease program development. The syntax highlighting is done
|
||||
with the [Iro](https://eeyo.io/iro/) compiler that allows
|
||||
writing the syntax only once, and then export it to formats
|
||||
understood by various IDE. Currently, two syntax
|
||||
highlighting plugins are under version control.
|
||||
|
||||
### Atom
|
||||
|
||||
To get Catala syntax highlighting in Atom, simply enter from
|
||||
the root of the repository, depending on the language you want to use :
|
||||
|
||||
make atom_fr
|
||||
or
|
||||
|
||||
make atom_en
|
||||
|
||||
You can now reload Atom and check that you have syntax highlighting on any `.catala` file.
|
||||
|
||||
### Pygments
|
||||
|
||||
Pygments is a Python-based versatile lexer for various
|
||||
programming languages. To use a version of Pygments
|
||||
augmented with the Catala plugin, simply enter
|
||||
|
||||
make pygments
|
||||
|
||||
This will execute the
|
||||
script `syntax_highlighting/fr/pygments/set_up_pygments.sh` and `syntax_highlighting/en/pygments/set_up_pygments.sh`.
|
||||
|
||||
The scripts set up a virtual environement in
|
||||
`syntax_highlighting/fr/pygments/pygments/env` or
|
||||
`syntax_highlighting/en/pygments/pygments/env`, which will
|
||||
contain the modified version of Pygments that has Catala
|
||||
support. If you want to hack something, it is possible to use this virtual
|
||||
environnement directly with
|
||||
|
||||
source syntax_highlighting/fr/pygments/pygments/env/bin/activate
|
||||
|
||||
or
|
||||
|
||||
source syntax_highlighting/en/pygments/pygments/env/bin/activate
|
||||
|
||||
The `pigmentize` executable, used for instance by the `minted` LaTeX package,
|
||||
will now point to the Catala-enabled version inside the virtual environment.
|
||||
This `source` setup is not necessary if you use the rules in the `Makefile`.
|
||||
See [the dedicated readme](INSTALL.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
The project accepts pull requests. Please email the authors
|
||||
if you are interested, whether you are a law professional, a
|
||||
computer scientist or a developer. Please use this email address :
|
||||
|
||||
denis DOT merigoux AT inria DOT fr
|
||||
|
||||
Please note that the copyright of this code is owned by Inria;
|
||||
by contributing, you disclaim all copyright interests in favor of Inria.
|
||||
See [the dedicated readme](CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user