Improved readmes

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.

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
+The Catala compiler is written using OCaml. First, you have to install `opam`,
-if you're running Linux ou MacOS, open a terminal and enter :
+OCaml's distribution and package manager. Follow the [instructions on the `opam`
+website](https://opam.ocaml.org/doc/Install.html). 
 
-    ./install_opam.sh
+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.,
-This will install `opam`, the OCaml dependency manager and the
+just use:
-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
+If you get a `No switch 4.09.1 is currently installed` error message, follow 
-dependencies with
+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
+needed to build the website. To produce them, simply run 
-root directory
+
+    make website-assets
+
+Then, use a helper script to copy them over to the `assets` directory of the 
+Catala website.
 
     ./generate_website_assets.sh <path-to-catala-website>/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

README.md

@@ -1,27 +1,30 @@
 
 <center>
-<img src="https://github.com/CatalaLang/catala/raw/master/doc/logo.png" alt="Catala logo" width="100"/>
+<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/logo.png" alt="Catala logo" width="100"/>
 </center>
 
 # 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
+Catala is a programming language adapted for socio-fiscal legislative literate
-legislative text with its meaning in terms of code, one can derive
+programming. By annotating each line of the legislative text with its meaning
-an implementation of complex socio-fiscal mechanisms that enjoys
+in terms of code, one can derive an implementation of complex socio-fiscal 
-a high level of assurance regarding the code-law faithfulness.
+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
+Concretely, you have to first gather all the laws, executive orders, previous 
-socio-fiscal mechanism that you want to implement. Then, you can
+cases, etc. that contain information about the socio-fiscal mechanism that 
-proceed to annotate the text article by article, in your favorite
+you want to implement. Then, you can proceed to annotate the text article by 
-text editor :
+article, in your favorite text editor :
 
 <center>
-<img src="https://github.com/CatalaLang/catala/raw/master/doc/ScreenShotVSCode.png" alt="Screenshot" height="500"/>
+<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/ScreenShotVSCode.png" alt="Screenshot" height="500"/>
 </center>
 
 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.
 
 <center>
-<img src="https://github.com/CatalaLang/catala/raw/master/doc/CatalaScreenShot.png" alt="Screenshot" height="500"/>
+<img src="https://github.com/CatalaLang/catala/raw/master/doc/images/CatalaScreenShot.png" alt="Screenshot" height="500"/>
 </center>
 
 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
+"definition-under-conditions" that builds on default logic has been formalized 
-programming language to our knowledge that embeds default logic
+by Professor of Law Sarah Lawsky in her article 
-as a first-class feature, which is why it is the only language
+[A Logic for Statutes](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3088206). 
-perfectly adapted to literate legislative programming.
+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.
 
 ## 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
 

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}

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)

install_opam.sh

@@ -1,3 +0,0 @@
-#! /usr/bin/env bash
-
-sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)

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 `<name_of_test>.catala.<name_of_scope>.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 
+`<name_of_test>.catala.<name_of_scope>.out` in the corresponding test folder.
 
 For both workflows: use `CATALA_OPTS="..." make ...` to pass in Catala compiler
 options when debugging.
@@ -34,3 +38,8 @@ options when debugging.
 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.
+
+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.