Merge branch 'documentation' into main

README.md

@@ -9,4 +9,4 @@ Check out the [release notes](https://github.com/AmpersandTarski/Ampersand/blob/
 
 ## Documentation
 
-We are currently in a process to change the way we publish our documentation. The old site can be found [here](https://ampersandtarski.gitbook.io/documentation/). The new site can be found [here](https://ampersandtarski.github.io/docs/Ampersand/). It features full-text search and it contains all documentation of several repositories in a single place. We are still [working](https://github.com/AmpersandTarski/Ampersand/issues/1315) on structuring it. 
+Our [documentation](https://ampersandtarski.github.io/docs/Ampersand/) features full-text search and it contains all documentation of several repositories in a single place. We are still [working](https://github.com/AmpersandTarski/Ampersand/issues/1315) on structuring it.

ampersand/.gitignore

@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

docs/docker/1-compiler.md

@@ -7,12 +7,11 @@ description: >-
 
 # Compiler
 
-To run the Ampersand compiler from any computer that runs docker, use a Docker image from our Ampersand repository on GitHub: `docker.pkg.github.com/ampersandtarski/ampersand/ampersand`
-
-Make a shortcut tag to save typing:
+To run the Ampersand compiler from any computer that runs docker, use a Docker image from our Ampersand repository on Docker hub, and make a shortcut tag to save typing:
 
 ```bash
-docker tag docker.pkg.github.com/ampersandtarski/ampersand/ampersand ampersand
+docker pull ampersandtarski/ampersand
+docker tag ampersandtarski/ampersand ampersand
 ```
 
 Different tags are available, e.g.:

docs/reference-material/how-to-read-syntax-statements.md

@@ -59,7 +59,7 @@ Keywords in Ampersand are always written in CAPITALS.
 - Keywords for [relations](./syntax-of-ampersand#the-relation-statement)
   - [`RELATION`](./syntax-of-ampersand#the-relation-statement)
   - `PRAGMA`
-  - [`UNI`, `INJ`, `SUR`, `TOT`, `SYM`, `ASY`, `TRN`, `RFX`, `IRF`, `PROP`](../modeling/properties#properties)
+  - [`UNI`, `INJ`, `SUR`, `TOT`, `SYM`, `ASY`, `TRN`, `RFX`, `IRF`, `PROP`, `MAP`, `BIJ`](./syntax-of-ampersand.md#properties)
   - [`POPULATION`, `CONTAINS`](./syntax-of-ampersand#the-population-statement)
 - Keywords for [rules](./syntax-of-ampersand#the-rule-statement)
   - `RULE`

docs/reference-material/syntax-of-ampersand.md

@@ -353,6 +353,8 @@ The `<properties>`-part is meant for writing multiplicity constraints in a comma
 | INJ | injective  | For any `b` in `B` there can be not more than one `a` in `A` in the population of `r`. So, every `b` occurs not more than once in the target of `r`.                           |
 | SUR | surjective | For any `b` in `B` there must be at least one `a` in `A` in the population of `r`.                                                                                             |
 | TOT | total      | For any `a` in `A` there must be at least one `b` in `B` in the population of `r`.                                                                                             |
+| MAP | -          | Shortcut for the combination of total and univalent.                                                                                                                           |
+| BIJ | -          | Shortcut for the combination of surjective and injective.                                                                                                                      |
 
 There are additional relations that can be specified on endo relations. An endo relation is a relation where the source and target concepts are equal. `r[A*A]`.
 
@@ -363,7 +365,7 @@ There are additional relations that can be specified on endo relations. An endo
 | TRN  | transitive    | If (`a`,`b`) and (`b`,`c`) are both in `r`, then (`a`,`c`) is in `r`.     |
 | RFX  | reflexive     | For each `a` in `A`, the pair (`a`,`a`) is in the population of `r`       |
 | IRF  | irreflexive   | For each `a` in `A`, the pair (`a`,`a`) is _not_ in the population of `r` |
-| PROP | -             | shortcut for the combination of symmetric and antisymmetric.              |
+| PROP | -             | Shortcut for the combination of symmetric and antisymmetric.              |
 
 Let's assume that we want to express that any person can live in one city only. So under this constraint "_Joe Smith lives in New York_" and "_Joe Smith lives in Denver_" cannot both be true at the same time.
 
@@ -982,14 +984,15 @@ Examples:
 - `BOX <FORM hideLabels hideOnNoRecords noRootTitle>`
 
 Possible attributes are:
+
 | attribute | value | description |
 | --------- | ----- | ----------- |
-| hideOnNoRecords | n.a. | when attribute is set, the complete form is hidden in the interface when there are no records |
-| hideSubOnNoRecords | n.a. | when attribute is set, specific form fields (i.e. sub interfaces) that have no records are hidden |
-| hideLabels | n.a. | when attribute is set, no field labels are shown |
-| title | string | title / description for the forms. Title is shown above the form |
-| noRootTitle | n.a. | hides title; usefull for root interface boxes where a title is automatically is added |
-| showNavMenu | n.a. | show 'hamburger' button to navigate to other interfaces designed for target concept of expression |
+| hideOnNoRecords | - | when attribute is set, the complete form is hidden in the interface when there are no records |
+| hideSubOnNoRecords | - | when attribute is set, specific form fields (i.e. sub interfaces) that have no records are hidden |
+| hideLabels | - | when attribute is set, no field labels are shown |
+| title | string | title (or description) for the forms. Title is shown above the form |
+| noRootTitle | - | hides title; usefull for root interface boxes where a title is automatically is added |
+| showNavMenu | - | show 'hamburger' button to navigate to other interfaces designed for target concept of expression |
 
 #### Example
 The row layout uses `BOX <FORM>` to instruct the front-end application to layout the user interface one field on one row, as you would expect in a form. Here is an example of an interface, which uses the form layout on the top level.
@@ -1035,14 +1038,14 @@ Examples:
 Possible attributes are:
 | attribute | value | description |
 | --------- | ----- | ----------- |
-| hideOnNoRecords | n.a. | when attribute is set, the complete table is hidden in the interface when there are no records |
-| noHeader | n.a. | when attribute is set, no table header is used (all column labels are hidden) |
+| hideOnNoRecords | - | when attribute is set, the complete table is hidden in the interface when there are no records |
+| noHeader | - | when attribute is set, no table header is used (all column labels are hidden) |
 | title | string | title / description for the table. Title is shown above table |
-| noRootTitle | n.a. | hides title; usefull for root interface boxes where a title is automatically is added |
-| sortable | n.a. | makes table headers clickable to support sorting on some property of the data. Only applies to univalent fields |
+| noRootTitle | - | hides title; usefull for root interface boxes where a title is automatically is added |
+| sortable | - | makes table headers clickable to support sorting on some property of the data. Only applies to univalent fields |
 | sortBy | sub interface label | Add default sorting for given sub interface. Use in combination with 'sortable' |
 | order | `desc`, `asc` | Specifies default sorting order. Use in combination with 'sortBy'. Use `desc` for descending, `asc` for ascending |
-| showNavMenu | n.a. | show 'hamburger' button to navigate to other interfaces designed for target concept of expression |
+| showNavMenu | - | show 'hamburger' button to navigate to other interfaces designed for target concept of expression |
 
 #### Example
 The column layout uses `BOX <TABLE>` to instruct the front-end application to use a tabular layout in user interfaces. Here is an example of an interface, which uses the table layout.
@@ -1091,9 +1094,9 @@ Possible attributes are:
 | attributes | value | description |
 | ---------- | ----- | ----------- |
 | title      | string | title / description for the table. Title is shown above tabs structure |
-| noRootTitle    | n.a. | hides title; usefull for root interface boxes where a title is automatically is added |
-| hideOnNoRecords | n.a. | when attribute is set, the complete tab set is hidden in the interface when there are no records |
-| hideSubOnNoRecords | n.a. | when attribute is set, specific tabs (i.e. sub interfaces) that have no records are hidden |
+| noRootTitle    | - | hides title; usefull for root interface boxes where a title is automatically is added |
+| hideOnNoRecords | - | when attribute is set, the complete tab set is hidden in the interface when there are no records |
+| hideSubOnNoRecords | - | when attribute is set, specific tabs (i.e. sub interfaces) that have no records are hidden |
 
 
 The column layout uses `BOX <TABS>` to instruct the front-end application to tabs in the user interface. Here is an example of an interface, which uses the column layout.
@@ -1142,11 +1145,11 @@ Examples:
 Possible attributes are:
 | attribute | value | description |
 | --------- | ----- | ----------- |
-| form      | n.a.  | uses simple form structure to display data. Similar to `FORM` template, but without any functionality nor markup. This is the default layout for `RAW` template.
-| table     | n.a.  | uses simple table structure to display data. Similar to `TABLE` template (see below), but without any functionality, header and styling
+| form      | -  | uses simple form structure to display data. Similar to `FORM` template, but without any functionality nor markup. This is the default layout for `RAW` template.
+| table     | -  | uses simple table structure to display data. Similar to `TABLE` template (see below), but without any functionality, header and styling
 
 ### PROPBUTTON
-Interface template that provides a botton that, when clicked, can set, clear and/or toggle/flip the value of a number of property-relations (i.e. a relation that is [PROP] (or: [SYM,ASY]). 
+Interface template that provides a botton that, when clicked, can set, clear and/or toggle/flip the value of a number of property-relations (i.e. a relation that is [PROP] (or: [SYM,ASY])). 
 
 The interface provides means to:
 
@@ -1157,7 +1160,8 @@ The interface provides means to:
 - provide a popover text for the button, both when it is enabled and when it is disabled. 
 
 Usage (note that all attributes are optional, and you can rearrange their order as you see fit) :
-```
+
+```.adl
 expr cRud BOX <PROPBUTTON> 
   [ "label":  expr or txt    -- text on button = result of expr or txt
   , "label1": expr or txt    -- text on button = label+label1

docs/reference-material/terms.md

@@ -49,7 +49,7 @@ The operators come in families. We advise novices to study only the rule operato
 | Family                                       |                   binary operators | binding power |         unary operators | binding power |
 | -------------------------------------------- | ---------------------------------: | ------------- | ----------------------: | ------------- |
 | rules                                        |            $$=$$ and $$\subseteq$$ | 1 (weakest)   |                         |               |
-| [boolean](#boolean-operators-in-logic)       |      $$\cup$$, $$\cap$$, and $$-$$ | 2             | $\overline{\vspace{x}}$ | prefix        |
+| [boolean](#boolean-operators-in-logic)       |      $$\cup$$, $$\cap$$, and $$-$$ | 2             | $\overline{x}$ | prefix        |
 | [relational](#relational-operators-in-logic) | $$;$$, $$\times$$, and $$\dagger$$ | 4             |         $$\smallsmile$$ | postfix       |
 | [residual](#residual-operators-in-logic)     |   $$\backslash$$, $$/$$, and $$♢$$ | 3             |                         |               |
 | Kleene                                       |                                    |               |         $$∗$$ and $$+$$ | postfix       |
@@ -66,23 +66,23 @@ Repeated uses of an associative operator does not require brackets. So $$r\cap s
 
 When coding in Ampersand, these operators are typed with characters on the keyboard. The following table shows the operators in math and their equivalent in code:
 
-| operator name                | code |          math          | remark                                     |
-| ---------------------------- | :--: | :--------------------: | ------------------------------------------ | ------------------ |
-| equivalence (equal)          | `=`  |         $$=$$          | use only in a rule                         |
-| inclusion                    |  `   |           -`           | $$\subseteq$$                              | use only in a rule |
-| intersect                    | `/\` |         $$∩$$          | associative, commutative, idempotent       |
-| union                        | `\/` |         $$∪$$          | associative, commutative, idempotent       |
-| difference (minus)           | `-`  |         $$-$$          |                                            |
-| complement                   | `-`  | $$\overline{\strut }$$ | in code: Prefix; in math: Overline         |
-| compose                      | `;`  |         $$;$$          | associative                                |
-| converse (flip)              | `~`  |    $$\smallsmile$$     | postfix                                    |
-| left residual                | `/`  |         $$/$$          |                                            |
-| right residual               | `\`  |     $$\backslash$$     |                                            |
-| diamond                      | `<>` |      $$\Diamond$$      |                                            |
-| relational product           | `!`  |      $$\dagger$$       | associative                                |
-| cartesian product            | `#`  |       $$\times$$       |                                            |
-| reflexive transitive closure | `*`  |         $$∗$$          | in code: not implemented; in math: Postfix |
-| transitive closure           | `+`  |         $$+$$          | in code: not implemented; in math: Postfix |
+| operator name                |  code |          math          | remark                                     |
+| ---------------------------- | :---: | :--------------------: | ------------------------------------------ |
+| equivalence (equal)          |  `=`  |          $$=$$         | use only in a rule                         |
+| inclusion                    | `\|-` |      $$\subseteq$$     | use only in a rule                         |
+| intersect                    |  `/\` |          $$∩$$         | associative, commutative, idempotent       |
+| union                        |  `\/` |          $$∪$$         | associative, commutative, idempotent       |
+| difference (minus)           |  `-`  |          $$-$$         |                                            |
+| complement (of some relation r) | `-`|     $$\overline{r}$$   | in code: Prefix; in math: Overline         |
+| compose                      |  `;`  |          $$;$$         | associative                                |
+| converse (flip)              |  `~`  |     $$\smallsmile$$    | postfix                                    |
+| left residual                |  `/`  |          $$/$$         |                                            |
+| right residual               |  `\`  |     $$\backslash$$     |                                            |
+| diamond                      |  `<>` |      $$\Diamond$$      |                                            |
+| relational product           |  `!`  |       $$\dagger$$      | associative                                |
+| cartesian product            |  `#`  |       $$\times$$       | deprecated                                 |
+| reflexive transitive closure |  `*`  |          $$∗$$         | in code: not implemented; in math: Postfix |
+| transitive closure           |  `+`  |          $$+$$         | in code: not implemented; in math: Postfix |
 
 ## Semantics
 
@@ -156,13 +156,13 @@ To say things such as "the name of the owner", we want to string together multip
 
 ##### Converse
 
-A relation can be altered by swapping the elements of every pair in the relation. Mathematically, $$(a, b)$$ is a different from $$(b,a)$$. This operation is called the converse operator. It produces a new relation from an existing one. It is denoted by writing $$\smallsmile\$$ \(pronounced 'wok' or ’flip’\) after the relation name. This is how converse is defined:
+A relation can be altered by swapping the elements of every pair in the relation. Mathematically, $$(a, b)$$ is different from $$(b,a)$$. This operation is called the converse operator. It produces a new relation from an existing one. It is denoted by writing $$\smallsmile\$$ \(pronounced 'wok' or ’flip’\) after the relation name. This is how converse is defined:
 
 $$
 a(r\smallsmile)b\ \Leftrightarrow\ b\ r\ a
 $$
 
-If $$r$$ has type$$[A\times B]$$, then $$r\smallsmile\$$ has type $$[B\times A]$$.
+If $$r$$ has type$$[A\times B]$$, then $$r\smallsmile$$ has type $$[B\times A]$$.
 
 ##### Composition
 
@@ -363,13 +363,13 @@ To say things such as "the name of the owner", we want to string together multip
 
 ##### Converse
 
-A relation that contains pairs of the form $$(a, b)$$ can be altered by swapping the elements of every pair in the relation. Mathematically, $$(a, b)$$ is a different from $$(b,a)$$. This operation is called the converse operator. It produces a new relation from an existing one. It is denoted by writing $$\smallsmile\$$ \(pronounced 'wok' or ’flip’\) after the relation name. This is how converse is defined:
+A relation that contains pairs of the form $$(a, b)$$ can be altered by swapping the elements of every pair in the relation. Mathematically, $$(a, b)$$ is different from $$(b,a)$$. This operation is called the converse operator. It produces a new relation from an existing one. It is denoted by writing $$\smallsmile$$ \(pronounced 'wok' or ’flip’\) after the relation name. This is how converse is defined:
 
 $$
 r\smallsmile\ =\ \{ (b, a) | (a, b)∈r \}
 $$
 
-If $$r$$ has type $$[A\times B]$$, then $$r\smallsmile\$$ has type $$[B\times A]$$.
+If $$r$$ has type $$[A\times B]$$, then $$r\smallsmile$$ has type $$[B\times A]$$.
 
 ##### Composition