From f282d9586be302e370789354aebb2ee48f3c4908 Mon Sep 17 00:00:00 2001 From: Denis Merigoux Date: Mon, 14 Dec 2020 10:59:15 +0100 Subject: [PATCH] Improved readmes --- CONTRIBUTING.md | 28 ++++- INSTALL.md | 62 +++++----- README.md | 109 ++++++++---------- catala.opam | 6 +- doc/{ => images}/CatalaScreenShot.png | Bin doc/{ => images}/ScreenShotVSCode.png | Bin doc/{ => images}/logo.png | Bin doc/{ => images}/logo.svg | 0 doc/{ => out_of_date}/enlish_token_list.md | 0 doc/{ => out_of_date}/motivation.tex | 0 doc/{ => out_of_date}/questionnaire.tex | 0 .../questionnaire_for_lawyers.tex | 0 doc/{ => out_of_date}/reading_guide.tex | 0 dune-project | 7 +- install_opam.sh | 3 - tests/README.md | 17 ++- 16 files changed, 130 insertions(+), 102 deletions(-) rename doc/{ => images}/CatalaScreenShot.png (100%) rename doc/{ => images}/ScreenShotVSCode.png (100%) rename doc/{ => images}/logo.png (100%) rename doc/{ => images}/logo.svg (100%) rename doc/{ => out_of_date}/enlish_token_list.md (100%) rename doc/{ => out_of_date}/motivation.tex (100%) rename doc/{ => out_of_date}/questionnaire.tex (100%) rename doc/{ => out_of_date}/questionnaire_for_lawyers.tex (100%) rename doc/{ => out_of_date}/reading_guide.tex (100%) delete mode 100755 install_opam.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff6c3ac2..d949b201 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,18 @@ # 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. +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. +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 [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. +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 @@ -99,3 +106,18 @@ Again, make sure to regularly check that your example is parsing correctly. The ## 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. + +## 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. diff --git a/INSTALL.md b/INSTALL.md index ee20fa76..3afb6f51 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,29 +1,26 @@ -# Installing the Catala compiler +# Building and installing the Catala language ## 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 : +The Catala compiler is written using OCaml. First, you have to install `opam`, +OCaml's distribution and package manager. Follow the [instructions on the `opam` +website](https://opam.ocaml.org/doc/Install.html). - ./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 +Next, you will need to use the correct version of OCaml. Catala has been tested +with OCaml compiler versions that are at least 4.09.1. To switch to OCaml 4.09.1., +just use: opam switch 4.09.1 -if this version of OCaml is already installed. Next, install all the build -dependencies with +If you get a `No switch 4.09.1 is currently installed` error message, follow +the hint and enter `opam switch create 4.09.1`. + +Next, install all the OCaml packages that Catala depend on, as well as some +git submodules, with make install-dependencies -This should ensure everything is set up for developping on the Catala compiler ! +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 @@ -41,7 +38,7 @@ On ArchLinux : sudo pacman -S python-virtualenv man2html rsync -## Installation +## Build 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 @@ -50,12 +47,27 @@ and install the library. Makefile aliases are here to help you: running builds the compiler from its OCaml sources. +## Install + +The installation of the Catala compiler is handled through `opam`. Since the +Catala compiler is not yet published to the `opam` repository, you can install +a local version from this Git repository by using + + opam install ./ + +To uninstall, use + + opam unpin catala ### 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 +needed to build the website. To produce them, simply run + + make website-assets + +Then, use a helper script to copy them over to the `assets` directory of the +Catala website. ./generate_website_assets.sh /assets @@ -63,15 +75,6 @@ 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 use the compiler with the `catala` command. - ## Usage Use `catala --help` to get more information about the command line options available. @@ -119,7 +122,8 @@ 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`. +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 diff --git a/README.md b/README.md index 2729ece6..02661c79 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,30 @@
-Catala logo +Catala logo
# Catala Catala is a domain-specific language for deriving -faithful-by-construction algorithms from legislative texts. +faithful-by-construction algorithms from legislative texts. To learn quickly +about the language and its features, you can jump right to the official +[Catala tutorial](https://catala-lang.org/en/examples/tutorial). ## Concepts -Catala is a programming language adapted for socio-fiscal legislative literate programming. By annotating each line of the -legislative text with its meaning in terms of code, one can derive -an implementation of complex socio-fiscal mechanisms that enjoys -a high level of assurance regarding the code-law faithfulness. +Catala is a programming language adapted for socio-fiscal legislative literate +programming. By annotating each line of the legislative text with its meaning +in terms of code, one can derive an implementation of complex socio-fiscal +mechanisms that enjoys a high level of assurance regarding the code-law +faithfulness. -Concretely, you have to first gather all the laws, executive orders, previous cases, etc. that contain information about the -socio-fiscal mechanism that you want to implement. Then, you can -proceed to annotate the text article by article, in your favorite -text editor : +Concretely, you have to first gather all the laws, executive orders, previous +cases, etc. that contain information about the socio-fiscal mechanism that +you want to implement. Then, you can proceed to annotate the text article by +article, in your favorite text editor :
-Screenshot +Screenshot
Once your code is complete and tested, you can use the Catala @@ -32,72 +35,58 @@ can be reviewed and certified correct by the domain experts, which are in this case lawyers and not programmers.
-Screenshot +Screenshot
The Catala language is special because its logical structure mimics the logical structure of the law. Indeed, the core concept of -"definition-under-conditions" that builds on default logic has been formalized by Professor of Law Sarah Lawsky in her article [A Logic for Statutes](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3088206). 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. - - -## Catala motivating example : French "allocations familiales" - -In the `example/allocations_familiales` folder, you will find the -`allocations_familiales.catala` file which contains the -algorithm computing French family benefits. The algorithm consists of annotations to the legislative -texts that define the family benetifs, using the literate programming paradigm. The Catala -compiler can extract from the `.catala` file a lawyer-readable version of the annotated text. - -Currently, this lawyer-readable version comes in the form of a LaTeX document. -You will need to have a standard LaTeX distribution installed as well as the -`latexmk` build tool in order to enjoy the automated document generation process. - -To get that lawyer-readable version (which is a LaTeX-created) PDF, simply use - - make -C allocations_familiales allocations_familiales.pdf - -from the repository root, once you have managed to install the -compiler using [the dedicated readme](INSTALL.md). You can then open `examples/allocations_familiales/allocations_familiales.pdf` - -## Languages - -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 lefislative text. - -Currently, Catala supports English and French legislations via the `--language=en` or `--language=fr` option. Contact the authors -if you are interested in adding support for another language. - -## Limitations and disclaimer - -### Early stage project - -Catala is a research project from Inria, the French National -Research Institute for Computer Science. The compiler is yet very -unstable and lacks most of its features. Currently, it only -parses the surface language to producde the lawyer-readable PDF, -no interpreter or compiler backend is provided. - -However, the language is bound to have a complete formal semantics -in the near future. This semantics will guide the compiler -implementation. +"definition-under-conditions" that builds on default logic has been formalized +by Professor of Law Sarah Lawsky in her article +[A Logic for Statutes](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3088206). +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. ## Installation See [the dedicated readme](INSTALL.md). -## Test suite +## Examples -See [the dedicated readme](tests/README.md). +See [the dedicated readme](examples/README.md). ## Contributing See [the dedicated readme](CONTRIBUTING.md). +## Test suite + +See [the dedicated readme](tests/README.md). + +## Documentation + +### Formal semantics + +See [the dedicated readme](doc/formalization/README.md). + +### Compiler documentation + +See [the dedicated readme](src/README.md). + ## License -The library is released under the Apache license (version 2). +The library is released under the [Apache license (version 2)](LICENSE.txt). + +## Limitations and disclaimer + +Catala is a research project from Inria, the French National +Research Institute for Computer Science. The compiler is yet +unstable and lacks some of its features. Currently, here is the list +of existing features: + +* Literate programming output to HTML or LaTeX +* Typechecker and interpreter for most of the language + ## Pierre Catala diff --git a/catala.opam b/catala.opam index 99a58642..1bdedd02 100644 --- a/catala.opam +++ b/catala.opam @@ -6,7 +6,7 @@ description: """ The Catala language is designed to be a low-level target for higher-level specification languages for fiscal legislation. """ -maintainer: ["denis.merigoux@inria.fr"] +maintainer: ["contact@catala-lang.org"] authors: ["Denis Merigoux"] license: "Apache2" homepage: "https://github.com/CatalaLang/catala" @@ -17,11 +17,15 @@ depends: [ "sedlex" {>= "2.1"} "menhir" {>= "20200211"} "menhirLib" {>= "20200211"} + "unionfind" {>= "20200320"} + "bindlib" {>= "5.0.1"} "dune-build-info" {>= "2.0.1"} "cmdliner" {>= "1.0.4"} "re" {>= "1.9.0"} + "zarith" {>= "1.10"} "dune" {build} "ocamlgraph" {>= "1.8.8"} + "odate" {>= "0.6"} ] build: [ ["dune" "subst"] {pinned} diff --git a/doc/CatalaScreenShot.png b/doc/images/CatalaScreenShot.png similarity index 100% rename from doc/CatalaScreenShot.png rename to doc/images/CatalaScreenShot.png diff --git a/doc/ScreenShotVSCode.png b/doc/images/ScreenShotVSCode.png similarity index 100% rename from doc/ScreenShotVSCode.png rename to doc/images/ScreenShotVSCode.png diff --git a/doc/logo.png b/doc/images/logo.png similarity index 100% rename from doc/logo.png rename to doc/images/logo.png diff --git a/doc/logo.svg b/doc/images/logo.svg similarity index 100% rename from doc/logo.svg rename to doc/images/logo.svg diff --git a/doc/enlish_token_list.md b/doc/out_of_date/enlish_token_list.md similarity index 100% rename from doc/enlish_token_list.md rename to doc/out_of_date/enlish_token_list.md diff --git a/doc/motivation.tex b/doc/out_of_date/motivation.tex similarity index 100% rename from doc/motivation.tex rename to doc/out_of_date/motivation.tex diff --git a/doc/questionnaire.tex b/doc/out_of_date/questionnaire.tex similarity index 100% rename from doc/questionnaire.tex rename to doc/out_of_date/questionnaire.tex diff --git a/doc/questionnaire_for_lawyers.tex b/doc/out_of_date/questionnaire_for_lawyers.tex similarity index 100% rename from doc/questionnaire_for_lawyers.tex rename to doc/out_of_date/questionnaire_for_lawyers.tex diff --git a/doc/reading_guide.tex b/doc/out_of_date/reading_guide.tex similarity index 100% rename from doc/reading_guide.tex rename to doc/out_of_date/reading_guide.tex diff --git a/dune-project b/dune-project index 1c7ab125..c6665207 100644 --- a/dune-project +++ b/dune-project @@ -8,7 +8,7 @@ (homepage https://github.com/CatalaLang/catala) (bug_reports https://github.com/CatalaLang/catala/issues) (authors "Denis Merigoux") -(maintainers "denis.merigoux@inria.fr") +(maintainers "contact@catala-lang.org") (license Apache2) @@ -24,13 +24,16 @@ (sedlex (>= 2.1)) (menhir (>= 20200211)) (menhirLib (>= 20200211)) + (unionfind (>= 20200320)) + (bindlib (>= 5.0.1)) (dune-build-info (>= 2.0.1)) (cmdliner (>= 1.0.4)) (re (>= 1.9.0)) + (zarith (>= 1.10)) (dune (and :build )) (ocamlgraph (>= 1.8.8)) + (odate (>= 0.6)) ) ) - (using menhir 2.1) diff --git a/install_opam.sh b/install_opam.sh deleted file mode 100755 index 364c0593..00000000 --- a/install_opam.sh +++ /dev/null @@ -1,3 +0,0 @@ -#! /usr/bin/env bash - -sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) diff --git a/tests/README.md b/tests/README.md index ffdf81b4..e833c60a 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,10 +1,14 @@ # Catala test suite -This folder contains Catala source files designed to test the features of the language. +This folder contains Catala source files designed to test the features of the +language. -It uses `make` to launch tests and compare the test terminal output with an expected output. +It uses `make pass_tests` to launch tests and compare the test terminal output +with an expected output. -When you create a new test, please register it in the `Makefile` following the other examples. Expected outputs are stored using the convention `.catala..out` in the corresponding test folder. +When you create a new test, please register it in the `Makefile` following the +other examples. Expected outputs are stored using the convention +`.catala..out` in the corresponding test folder. For both workflows: use `CATALA_OPTS="..." make ...` to pass in Catala compiler options when debugging. @@ -33,4 +37,9 @@ options when debugging. `make foo/bar.catala.A.in`. 5. Re-reun `make` to check that everything passes. 6. That's it, you've fixed the Catala test suite to adapt for changes in the - language. \ No newline at end of file + language. + +If a compiler change causes a lot of regressions (error message formatting changes +for instance), you can mass-reset the expected the outputs with `make reset_tests`. +**Caution**: use at your own risk, regressions should be fixed one by one in +general. \ No newline at end of file