diff --git a/.devcontainer/DockerfileUpstream b/.devcontainer/DockerfileUpstream
index 87ff5485ad..788521e975 100644
--- a/.devcontainer/DockerfileUpstream
+++ b/.devcontainer/DockerfileUpstream
@@ -58,8 +58,8 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
ENV PATH="${WDIR}/.cabal/bin:${WDIR}/.ghcup/bin:${PATH}:${WDIR}/.local/bin:${PATH}"
ARG GHC=8.10.7
-ARG CABAL=3.10.1.0
-ARG HLS=2.0.0.1
+ARG CABAL=3.6.2.0
+ARG HLS=2.2.0.0
ARG STACK=2.11.1
# install GHC and cabal
@@ -99,11 +99,7 @@ ENV PATH="${WDIR}/.cabal/bin:${WDIR}/.ghcup/bin:${WDIR}/.local/bin:${PATH}"
COPY ./package.yaml ${WDIR}/package.yaml
COPY ./stack.yaml ${WDIR}/stack.yaml
-RUN groupadd --gid $USER_GID $USERNAME && \
- useradd -ms /bin/bash -K MAIL_DIR=/dev/null --uid $USER_UID --gid $USER_GID -m $USERNAME && \
- echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME && \
- chmod 0440 /etc/sudoers.d/$USERNAME
-
+RUN stack setup ${GHC}
ENV DEBIAN_FRONTEND=dialog
ENTRYPOINT ["/bin/bash"]
\ No newline at end of file
diff --git a/.devcontainer/README.md b/.devcontainer/README.md
new file mode 100644
index 0000000000..0a45af7800
--- /dev/null
+++ b/.devcontainer/README.md
@@ -0,0 +1,26 @@
+# On the use of the ampersand .devcontainer stuff
+
+## Purpose
+
+The purpose of the .devcontainer is to provide a common development environment for the Haskellers among the developers of Ampersand.
+
+## What is in this directory
+
+`DockerfileUpstream` is a Dockerfile to build an image. That image should be [available at dockerhub](https://hub.docker.com/repository/docker/ampersandtarski/ampersand-devcontainer/general).
+`devcontainer.json` contains the information to properly launch a remote container for the developer.
+
+## Usage
+
+To use this devcontainer, simply open vscode in the Ampersand workspace. It should ask to reopen in a container. The first time might take quite a while, but it is worth the wait. All Haskell goodies will be at your fingertips.
+
+## Maintenance of the upstream image
+
+NB: This action is currently done by Han, no need for other people to do so. It can be seen as regular maintenance of the image
+
+Sometimes there are updates of the Haskell toolchain we use. For instance whenever a new version of the Haskell Language Server is made available, the `DockerfileUpstream` should be updated accordingly. Then, the new image should be built and published at dockerhub. To do so, go to the ampersand root directory and run the following commands:
+
+```
+docker build -f .devcontainer/DockerfileUpstream -t ampersandtarski/ampersand-devcontainer:latest .
+docker push ampersandtarski/ampersand-devcontainer:latest
+
+```
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 53015cc2b0..bf3a68dd30 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -6,10 +6,12 @@
"context": "..",
"dockerfile": "Dockerfile"
},
+ "postStartCommand": "stack build",
"customizations": {
"vscode": {
"extensions": [
"haskell.haskell",
+ "justusadam.language-haskell",
"phoityne.phoityne-vscode",
"eriksik2.vscode-ghci",
"jcanero.hoogle-vscode",
diff --git a/Ampersand.archimate b/Ampersand.archimate
new file mode 100644
index 0000000000..7fa8848a8d
--- /dev/null
+++ b/Ampersand.archimate
@@ -0,0 +1,673 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<archimate:model xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:archimate="http://www.archimatetool.com/archimate" name="Ampersand" id="id-51417a5833884cb386efff6db5117d83" version="5.0.0">
+ <folder name="Strategy" id="id-ecad04e506714c4bbcdc18f17469dd81" type="strategy"/>
+ <folder name="Business" id="id-d7fb92c8460f4cf49c6289f6284cc908" type="business">
+ <element xsi:type="archimate:Representation" name="Ampersand script 1" id="id-d416c59ad9ea47289dcde683423d2c5d"/>
+ <element xsi:type="archimate:Representation" name="Ampersand script 2" id="id-69b5cb7448e542c699460419020bba14"/>
+ <element xsi:type="archimate:Representation" name="INCLUDES stmt" id="id-5fed881eea4a467e99ec539b2ccb900c"/>
+ <element xsi:type="archimate:Product" name="./docs" id="id-933a4166eaeb4258b1e3e8a6ab3aec99">
+ <documentation>
+</documentation>
+ </element>
+ <element xsi:type="archimate:Product" name="./" id="id-f48d5f70855f4b3fb29070d3c6813582">
+ <documentation>
+</documentation>
+ </element>
+ <element xsi:type="archimate:BusinessObject" name="sidebar.js " id="id-b0e4256b6bb2445691a9831a7547a1a0"/>
+ <element xsi:type="archimate:BusinessObject" name="sidebar.js (ampersand)" id="id-2995b55c8d6f48e58fb894da9d89422e"/>
+ <element xsi:type="archimate:BusinessObject" name="sidebar.js (prototype)" id="id-19f46ddaa41d46998f30ab569caaf403"/>
+ <element xsi:type="archimate:BusinessObject" name="sidebar.js (the-tools-we-use)" id="id-4cc69dbbfed147a08f86f00a7b5243e4"/>
+ <element xsi:type="archimate:BusinessService" name="Business Service" id="id-c87fbe964fdb4ca48eadc47010857f10"/>
+ <element xsi:type="archimate:BusinessFunction" name="Business Function" id="id-3349621c3582424a9b2940d14f56ccbc">
+ <documentation>
+
+</documentation>
+ </element>
+ </folder>
+ <folder name="Application" id="id-0c6d725b48844463aa47c6ce972c3c30" type="application">
+ <element xsi:type="archimate:DataObject" name="docusaurus.config.js" id="id-b55ebf8e98474ac5b36fd32c54cbfb36"/>
+ <element xsi:type="archimate:ApplicationService" name="Ampersand documentation site" id="id-1fcbf442e0ba4d069368041f58ddc3d5">
+ <documentation>
+</documentation>
+ </element>
+ <element xsi:type="archimate:ApplicationService" name="Docusaurus" id="id-669d773a3f9640399c03ab1390a2bd6b"/>
+ <element xsi:type="archimate:ApplicationFunction" name="triggerDocsUpdate.yml" id="id-152ad5a2e65b4a6ca6218aef0585e9b8"/>
+ <element xsi:type="archimate:ApplicationEvent" name="docker compose up -d --build" id="id-469036c7c4d14b6dbf1d54fc23546467"/>
+ <element xsi:type="archimate:DataObject" name="Copy of documentation source code" id="id-eac110ed899f42a0b19e97a329457afd"/>
+ <element xsi:type="archimate:ApplicationComponent" name="existing application" id="id-f6b0869f2bcf47cebb836f47e076f2a4"/>
+ <element xsi:type="archimate:ApplicationService" name="retrieve schema" id="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <documentation>
+
+</documentation>
+ </element>
+ <element xsi:type="archimate:DataObject" name="existing data set" id="id-8159335d378e44a2b528ad609c69bffe"/>
+ <element xsi:type="archimate:ApplicationComponent" name="migration system" id="id-7c4ad8b343ac45208f7e1f6e7dd73c41"/>
+ <element xsi:type="archimate:DataObject" name="migration data set" id="id-d17e55e941184567b338f3e003ec1dd4"/>
+ <element xsi:type="archimate:ApplicationComponent" name="migrated application" id="id-c156b9eb4a05406396a0816a1c7e03d2"/>
+ <element xsi:type="archimate:DataObject" name="existing schema" id="id-17da1776ea434e91a193440cab695f6f"/>
+ <element xsi:type="archimate:DataObject" name="new schema" id="id-fffd7eef08004ceea35a6d541f01d1fd"/>
+ <element xsi:type="archimate:DataObject" name="migration schema" id="id-9933f48411754bc4bde097aedcb356b5"/>
+ <element xsi:type="archimate:DataObject" name="new data set" id="id-e3bbb23e04644f0c82e34dbe6de9f2a7"/>
+ <element xsi:type="archimate:ApplicationComponent" name="legend-purpose-application-component" id="id-c7f624b0cfa345c581e539282adbc602"/>
+ <element xsi:type="archimate:ApplicationService" name="legend-purpose-application-service" id="id-e4a1f2550abc412980739bf839af303e"/>
+ <element xsi:type="archimate:DataObject" name="legend-purpose-data-object" id="id-f9f8871221464027b310beb32585b0fe"/>
+ <element xsi:type="archimate:DataObject" id="id-12a7f0386cb2437891fe48a828ff028d"/>
+ <element xsi:type="archimate:ApplicationService" name="finish" id="id-b4aa7866aa7a498b9df96e3841fd4716">
+ <documentation>
+
+</documentation>
+ </element>
+ <element xsi:type="archimate:ApplicationComponent" name="Dataset" id="id-76de9e543bb84968a4bb9f73c43a7575"/>
+ <element xsi:type="archimate:ApplicationFunction" name="Name mapping" id="id-412714f508a545aca720451e5a9ed212"/>
+ <element xsi:type="archimate:ApplicationComponent" name="API-1" id="id-97d51d02994b44aa96a0d33f01149936"/>
+ <element xsi:type="archimate:DataObject" name="Schema-1" id="id-14e1f329f21b4c5bb8750e7d1d63398e"/>
+ <element xsi:type="archimate:ApplicationComponent" name="API-2" id="id-3d3be9e73ff44f4a96d5991f8502ed09"/>
+ <element xsi:type="archimate:DataObject" name="Schema-2" id="id-063da8b38955436eac2d96896b82601f"/>
+ <element xsi:type="archimate:DataObject" name=".md file" id="id-09c03741835148fb8ec247396b422b88"/>
+ <element xsi:type="archimate:ApplicationEvent" name="build documentation" id="id-19f86694391b4b9faa3a9e53a50fa621"/>
+ <element xsi:type="archimate:DataObject" name="DeployToPages.yml" id="id-216b523d7d834938852c2c15476edec2"/>
+ <element xsi:type="archimate:ApplicationEvent" name="docker build . -t documentation" id="id-c9e941bae2164503a0792a914510f2ae"/>
+ <element xsi:type="archimate:ApplicationService" name="Application Service" id="id-825f1ded85cc49aaafb9d5fd03010c11">
+ <documentation>
+
+</documentation>
+ </element>
+ <element xsi:type="archimate:ApplicationComponent" name="Pod" id="id-4cbc6be959ef49e18aee938b3328e8d1">
+ <documentation>
+
+
+
+</documentation>
+ </element>
+ <element xsi:type="archimate:ApplicationComponent" name="Container" id="id-def630c240c543f3a6d74218739aefdd">
+ <documentation>
+
+
+</documentation>
+ </element>
+ </folder>
+ <folder name="Technology & Physical" id="id-f3c6fb875d9745e3b1e942e740320a3f" type="technology">
+ <element xsi:type="archimate:TechnologyService" name="Ingress" id="id-586ae0fbf4ff4f6ab121cf71240f02cc"/>
+ <element xsi:type="archimate:Node" name="prototype" id="id-b3d269512182443297108af5739a9177"/>
+ <element xsi:type="archimate:Node" name="Ampersand" id="id-6db149e9d7d54761a66afe4cb53e8bce"/>
+ <element xsi:type="archimate:Node" name="TheToolsWeUse" id="id-0b3efc73811e45138c8ff69f0f8a96d1"/>
+ <element xsi:type="archimate:Node" name="AmpersandTarski.github.io" id="id-810dd6d86e1d4830baf22c5dc94a10ee"/>
+ <element xsi:type="archimate:TechnologyService" name="Kubernetes platform" id="id-379bf6291b66447bbe911a8d6643dff2"/>
+ </folder>
+ <folder name="Motivation" id="id-08021d0fd7554ede9b7877bc01f497a1" type="motivation"/>
+ <folder name="Implementation & Migration" id="id-850db561a843428eb153628bab2d28f4" type="implementation_migration"/>
+ <folder name="Other" id="id-03e0022a9e154954998086af9081970c" type="other">
+ <element xsi:type="archimate:Location" name="https://AmpersandTarski.github.io" id="id-a76de2298b9e4b8892f633da25824bf0"/>
+ <element xsi:type="archimate:Location" name="Container" id="id-9d87d2c3dad949e8ba9943cdf3f6bbbd"/>
+ <element xsi:type="archimate:Location" name="Github: ampersandtarski" id="id-514656a32add4521bad7ab9a687f7288"/>
+ </folder>
+ <folder name="Relations" id="id-e36891784adb49429324e44e8d9e59e1" type="relations">
+ <element xsi:type="archimate:CompositionRelationship" id="id-8ba43687252f4e79b5f27c58d31d0c27" source="id-a76de2298b9e4b8892f633da25824bf0" target="id-1fcbf442e0ba4d069368041f58ddc3d5"/>
+ <element xsi:type="archimate:FlowRelationship" id="id-56f67c68575a4729813b11e66d5a8b9e" source="id-669d773a3f9640399c03ab1390a2bd6b" target="id-1fcbf442e0ba4d069368041f58ddc3d5"/>
+ <element xsi:type="archimate:AssociationRelationship" name="config" id="id-c53f4b2ccdce4f4594cdabd7a9441b8a" source="id-b55ebf8e98474ac5b36fd32c54cbfb36" target="id-669d773a3f9640399c03ab1390a2bd6b"/>
+ <element xsi:type="archimate:TriggeringRelationship" id="id-d2bc436327294ac2a24cc85fc122dde3" source="id-9d87d2c3dad949e8ba9943cdf3f6bbbd" target="id-669d773a3f9640399c03ab1390a2bd6b"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-967494823bdd4771a0058f0fe95ad5fc" source="id-9d87d2c3dad949e8ba9943cdf3f6bbbd" target="id-eac110ed899f42a0b19e97a329457afd"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-a4b686bbb3ad47bd9f6fda91b9aab652" source="id-f6b0869f2bcf47cebb836f47e076f2a4" target="id-621a84fd26f24c198fa8e2c8aacd73de"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-cd670a560d654b639894aafa9cf4b358" source="id-f6b0869f2bcf47cebb836f47e076f2a4" target="id-8159335d378e44a2b528ad609c69bffe" accessType="3"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-6851fcaa530c4947a28f55f63686e09a" source="id-7c4ad8b343ac45208f7e1f6e7dd73c41" target="id-621a84fd26f24c198fa8e2c8aacd73de"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-46ac0fb1f08c4cf8a19e86c9d373efd6" source="id-7c4ad8b343ac45208f7e1f6e7dd73c41" target="id-d17e55e941184567b338f3e003ec1dd4" accessType="3"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-a2fbcc8f796c493eaeb934ebc20cfd52" source="id-c156b9eb4a05406396a0816a1c7e03d2" target="id-621a84fd26f24c198fa8e2c8aacd73de"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-515fa83b4bcc4511be0a205e3cfc97d2" source="id-c156b9eb4a05406396a0816a1c7e03d2" target="id-e3bbb23e04644f0c82e34dbe6de9f2a7" accessType="3"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-e9c76f1d8e9e44fba4b30125829cf872" source="id-621a84fd26f24c198fa8e2c8aacd73de" target="id-621a84fd26f24c198fa8e2c8aacd73de"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-2be6cd840e1c40ab8038a1dd49f493c8" source="id-621a84fd26f24c198fa8e2c8aacd73de" target="id-621a84fd26f24c198fa8e2c8aacd73de"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-9f27bcdff61543989b8a396235dbe231" source="id-621a84fd26f24c198fa8e2c8aacd73de" target="id-17da1776ea434e91a193440cab695f6f" accessType="1"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-81e1f60e2237483fbba9f3a03c0d427b" source="id-d17e55e941184567b338f3e003ec1dd4" target="id-e3bbb23e04644f0c82e34dbe6de9f2a7"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-2f00c98acfa643249b01ad4c20188c2a" source="id-621a84fd26f24c198fa8e2c8aacd73de" target="id-9933f48411754bc4bde097aedcb356b5" accessType="1"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-055fc4c760d048868a34f168ef94fe76" source="id-621a84fd26f24c198fa8e2c8aacd73de" target="id-fffd7eef08004ceea35a6d541f01d1fd" accessType="1"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-115ae4f172d4441f89fd993e47cebcb6" source="id-7c4ad8b343ac45208f7e1f6e7dd73c41" target="id-b4aa7866aa7a498b9df96e3841fd4716"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-e1a2f18187914ae1b8d0f03fa65d7772" source="id-b4aa7866aa7a498b9df96e3841fd4716" target="id-d17e55e941184567b338f3e003ec1dd4"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-75f0940d0de84696ae650213fd6ab5ba" source="id-d17e55e941184567b338f3e003ec1dd4" target="id-8159335d378e44a2b528ad609c69bffe"/>
+ <element xsi:type="archimate:FlowRelationship" id="id-55c1022e1cb744329303d1849d8b6d92" source="id-586ae0fbf4ff4f6ab121cf71240f02cc" target="id-c156b9eb4a05406396a0816a1c7e03d2"/>
+ <element xsi:type="archimate:FlowRelationship" id="id-9cc7a0d44d57449991b1cdea23fcb4ad" source="id-586ae0fbf4ff4f6ab121cf71240f02cc" target="id-f6b0869f2bcf47cebb836f47e076f2a4"/>
+ <element xsi:type="archimate:FlowRelationship" id="id-a7649bb791a542089ba484fde3dfc032" source="id-586ae0fbf4ff4f6ab121cf71240f02cc" target="id-7c4ad8b343ac45208f7e1f6e7dd73c41"/>
+ <element xsi:type="archimate:AssociationRelationship" name="discloses" id="id-9fc956f7df9f487d9c5bc8591e90d078" source="id-97d51d02994b44aa96a0d33f01149936" target="id-76de9e543bb84968a4bb9f73c43a7575" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="satisfies" id="id-117cce9cbd904b4f8071936d42c964b3" source="id-76de9e543bb84968a4bb9f73c43a7575" target="id-14e1f329f21b4c5bb8750e7d1d63398e" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="schema" id="id-511581f6addd4d90bb11ac4c2c4f1a40" source="id-97d51d02994b44aa96a0d33f01149936" target="id-14e1f329f21b4c5bb8750e7d1d63398e" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="schema" id="id-22e4c1f03e0d46c890334a563ddbe875" source="id-3d3be9e73ff44f4a96d5991f8502ed09" target="id-063da8b38955436eac2d96896b82601f" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="discloses" id="id-0378c126913149359b6f1efeb6479931" source="id-3d3be9e73ff44f4a96d5991f8502ed09" target="id-76de9e543bb84968a4bb9f73c43a7575" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="satisfies" id="id-045b5873b4fa4a9abcd4b67c99c38687" source="id-76de9e543bb84968a4bb9f73c43a7575" target="id-063da8b38955436eac2d96896b82601f" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="maps-from" id="id-df8837bdb8384db498d69ec781795f3b" source="id-412714f508a545aca720451e5a9ed212" target="id-14e1f329f21b4c5bb8750e7d1d63398e" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="maps-to" id="id-26a87af9e7a84943a7ad6740627ac24e" source="id-412714f508a545aca720451e5a9ed212" target="id-063da8b38955436eac2d96896b82601f" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="schema" id="id-fa0be40b19214c7da59aac2c1b6c09a7" source="id-d416c59ad9ea47289dcde683423d2c5d" target="id-14e1f329f21b4c5bb8750e7d1d63398e" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="schema" id="id-366532c2266c43269c1312d3d2fbaa4a" source="id-69b5cb7448e542c699460419020bba14" target="id-063da8b38955436eac2d96896b82601f" directed="true"/>
+ <element xsi:type="archimate:AssociationRelationship" name="source code" id="id-f92bf1ab2acc4b019783126c6859d11d" source="id-412714f508a545aca720451e5a9ed212" target="id-69b5cb7448e542c699460419020bba14" directed="true"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-47a5898bbd3f4b2888f16ed53759dd73" source="id-69b5cb7448e542c699460419020bba14" target="id-5fed881eea4a467e99ec539b2ccb900c"/>
+ <element xsi:type="archimate:AssociationRelationship" name="includes" id="id-621c1c0b39624a78a256d779f722a24d" source="id-5fed881eea4a467e99ec539b2ccb900c" target="id-d416c59ad9ea47289dcde683423d2c5d" directed="true"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-65623262f80e4f9692153935b5c1492c" source="id-f48d5f70855f4b3fb29070d3c6813582" target="id-b0e4256b6bb2445691a9831a7547a1a0"/>
+ <element xsi:type="archimate:AssociationRelationship" name="sub" id="id-3bd75edcbf6041c7adbf9ecf4da1b89e" source="id-2995b55c8d6f48e58fb894da9d89422e" target="id-b0e4256b6bb2445691a9831a7547a1a0"/>
+ <element xsi:type="archimate:AssociationRelationship" name="sub" id="id-5b7cc3e54b9a477d8b539413de52e0cb" source="id-19f46ddaa41d46998f30ab569caaf403" target="id-b0e4256b6bb2445691a9831a7547a1a0"/>
+ <element xsi:type="archimate:AssociationRelationship" name="sub" id="id-720fa550b0de4b62884bdf5175955dfd" source="id-4cc69dbbfed147a08f86f00a7b5243e4" target="id-b0e4256b6bb2445691a9831a7547a1a0"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-ee20563217244f42a20ea601a48b58b2" source="id-933a4166eaeb4258b1e3e8a6ab3aec99" target="id-2995b55c8d6f48e58fb894da9d89422e"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-edc00785709e4b11aa8d9556d806b8c7" source="id-933a4166eaeb4258b1e3e8a6ab3aec99" target="id-19f46ddaa41d46998f30ab569caaf403"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-4183174ad2b740cca1323d98e08ef2b0" source="id-f48d5f70855f4b3fb29070d3c6813582" target="id-4cc69dbbfed147a08f86f00a7b5243e4"/>
+ <element xsi:type="archimate:AssociationRelationship" name="mentions" id="id-bb278626027943e18eff6c00c766e28d" source="id-2995b55c8d6f48e58fb894da9d89422e" target="id-09c03741835148fb8ec247396b422b88"/>
+ <element xsi:type="archimate:AggregationRelationship" id="id-9ea802215392464d966332e86abdc306" source="id-933a4166eaeb4258b1e3e8a6ab3aec99" target="id-09c03741835148fb8ec247396b422b88"/>
+ <element xsi:type="archimate:TriggeringRelationship" id="id-a601e2267c664679ae33be3237fd567b" source="id-19f86694391b4b9faa3a9e53a50fa621" target="id-152ad5a2e65b4a6ca6218aef0585e9b8"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-8c3ac00c0f184e1bab24da76f1b64424" source="id-514656a32add4521bad7ab9a687f7288" target="id-0b3efc73811e45138c8ff69f0f8a96d1"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-3ba185bad1254de4abaabef58f184b66" source="id-514656a32add4521bad7ab9a687f7288" target="id-b3d269512182443297108af5739a9177"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-de9f2543e8474b3cba40f2f5e4ee7f7e" source="id-514656a32add4521bad7ab9a687f7288" target="id-6db149e9d7d54761a66afe4cb53e8bce"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-316256e0633f47f4bcdbb955521f4373" source="id-6db149e9d7d54761a66afe4cb53e8bce" target="id-152ad5a2e65b4a6ca6218aef0585e9b8"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-d44f911f9c714f86b79e97bd917036ad" source="id-514656a32add4521bad7ab9a687f7288" target="id-19f86694391b4b9faa3a9e53a50fa621"/>
+ <element xsi:type="archimate:TriggeringRelationship" id="id-445256d6a342495eb0543d65a6359c1f" source="id-6db149e9d7d54761a66afe4cb53e8bce" target="id-19f86694391b4b9faa3a9e53a50fa621"/>
+ <element xsi:type="archimate:RealizationRelationship" id="id-61853f8ed2b64d9d916246687ff1c46b" source="id-514656a32add4521bad7ab9a687f7288" target="id-810dd6d86e1d4830baf22c5dc94a10ee"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-b75fba5852e84be390def15ac80a1365" source="id-810dd6d86e1d4830baf22c5dc94a10ee" target="id-216b523d7d834938852c2c15476edec2"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-e3340652694e40a8b94e01d3ac9e0033" source="id-810dd6d86e1d4830baf22c5dc94a10ee" target="id-b55ebf8e98474ac5b36fd32c54cbfb36"/>
+ <element xsi:type="archimate:AssociationRelationship" name="calls" id="id-7920443b1b1d4d7fb7ca09f95f012203" source="id-152ad5a2e65b4a6ca6218aef0585e9b8" target="id-216b523d7d834938852c2c15476edec2"/>
+ <element xsi:type="archimate:AssociationRelationship" name="calls" id="id-4708075b62904f58a7eeb65528bd525b" source="id-216b523d7d834938852c2c15476edec2" target="id-669d773a3f9640399c03ab1390a2bd6b"/>
+ <element xsi:type="archimate:TriggeringRelationship" id="id-aa6779cb3ebc4131bc191e748b006dd7" source="id-469036c7c4d14b6dbf1d54fc23546467" target="id-9d87d2c3dad949e8ba9943cdf3f6bbbd"/>
+ <element xsi:type="archimate:AssociationRelationship" name="calls" id="id-83c952112dbf4adea610a410dd7cb574" source="id-216b523d7d834938852c2c15476edec2" target="id-c9e941bae2164503a0792a914510f2ae"/>
+ <element xsi:type="archimate:TriggeringRelationship" id="id-f404edb1099f48f492660f60d7d9d3d2" source="id-c9e941bae2164503a0792a914510f2ae" target="id-9d87d2c3dad949e8ba9943cdf3f6bbbd"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-fd94bf9017de4538a96c8742f773839e" source="id-810dd6d86e1d4830baf22c5dc94a10ee" target="id-b0e4256b6bb2445691a9831a7547a1a0"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-16d39c506b29441aac9aa563cff62eea" source="id-6db149e9d7d54761a66afe4cb53e8bce" target="id-2995b55c8d6f48e58fb894da9d89422e"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-ad21076ff0024214a45fb0f1e9c5fa4b" source="id-b3d269512182443297108af5739a9177" target="id-19f46ddaa41d46998f30ab569caaf403"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-2ed37eba33814300af416e0081c50497" source="id-0b3efc73811e45138c8ff69f0f8a96d1" target="id-4cc69dbbfed147a08f86f00a7b5243e4"/>
+ <element xsi:type="archimate:AccessRelationship" id="id-1eaa372f869e4353bccbdc63efd1f678" source="id-6db149e9d7d54761a66afe4cb53e8bce" target="id-09c03741835148fb8ec247396b422b88"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-00596da412af4c339e9ab007e668ac99" source="id-3349621c3582424a9b2940d14f56ccbc" target="id-c87fbe964fdb4ca48eadc47010857f10"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-f9e5be02d5dd4e74bd5911f30e175916" source="id-3349621c3582424a9b2940d14f56ccbc" target="id-c87fbe964fdb4ca48eadc47010857f10"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-8d494f2f43bd452785e2e352d197d185" source="id-3349621c3582424a9b2940d14f56ccbc" target="id-c87fbe964fdb4ca48eadc47010857f10"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-c80f1897dece4fb0a7bcc4148c819bc8" source="id-825f1ded85cc49aaafb9d5fd03010c11" target="id-3349621c3582424a9b2940d14f56ccbc"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-83aa7d15a2e34215b8f6ce6aa324046e" source="id-825f1ded85cc49aaafb9d5fd03010c11" target="id-3349621c3582424a9b2940d14f56ccbc"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-0d56ff12b91c4163aab7e6a2ee667003" source="id-825f1ded85cc49aaafb9d5fd03010c11" target="id-3349621c3582424a9b2940d14f56ccbc"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-1044daa245e0479db77852b5dc388426" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-def630c240c543f3a6d74218739aefdd"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-0bf2ec3b86f249a699a157b2319dc524" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-def630c240c543f3a6d74218739aefdd"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-b6b3da68540949aaa20e405c0b612205" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-def630c240c543f3a6d74218739aefdd"/>
+ <element xsi:type="archimate:CompositionRelationship" id="id-2f3292d9cc0741e080bd0860a37b060c" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-def630c240c543f3a6d74218739aefdd"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-ae7a7a1d49b64d009877170d343ee328" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-825f1ded85cc49aaafb9d5fd03010c11"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-28315e3d344645c39c210581c8a6c8b2" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-825f1ded85cc49aaafb9d5fd03010c11"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-4f64ceead1f94bb98f387fcd9dc7dbba" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-825f1ded85cc49aaafb9d5fd03010c11"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-d35830df2b4a40baab58f3ba36373f7f" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-825f1ded85cc49aaafb9d5fd03010c11"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-40799f207ef048238fbcd3a3fe68433b" source="id-4cbc6be959ef49e18aee938b3328e8d1" target="id-825f1ded85cc49aaafb9d5fd03010c11"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-da9dace0a9c049d9a725448909e583ea" source="id-379bf6291b66447bbe911a8d6643dff2" target="id-4cbc6be959ef49e18aee938b3328e8d1"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-585248e970964400b911d2b08b6bf0d2" source="id-379bf6291b66447bbe911a8d6643dff2" target="id-4cbc6be959ef49e18aee938b3328e8d1"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-9ba8fd52e70b4908877d5074d39914e3" source="id-379bf6291b66447bbe911a8d6643dff2" target="id-4cbc6be959ef49e18aee938b3328e8d1"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-4459e37ddf4c4a03875635ef09e44d3e" source="id-379bf6291b66447bbe911a8d6643dff2" target="id-4cbc6be959ef49e18aee938b3328e8d1"/>
+ <element xsi:type="archimate:AssociationRelationship" id="id-7f9fb8967b7e4c61a8d28cde8ad389ef" source="id-379bf6291b66447bbe911a8d6643dff2" target="id-4cbc6be959ef49e18aee938b3328e8d1"/>
+ </folder>
+ <folder name="Views" id="id-f8cda31f608044dfb807aa294f0f8566" type="diagrams">
+ <element xsi:type="archimate:ArchimateDiagramModel" name="Documentation triggers" id="id-c9989c22df61442ab267f5e84e88363d">
+ <child xsi:type="archimate:DiagramObject" id="id-49cc63fe6c264734b5d3b5fd42ff1fbd" textPosition="2" archimateElement="id-a76de2298b9e4b8892f633da25824bf0">
+ <bounds x="504" y="36" width="253" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-5380eaacfd934fa9afcdbfa03dc33119" source="id-49cc63fe6c264734b5d3b5fd42ff1fbd" target="id-943cfb758f5e425c827b7aa9b25d9027" archimateRelationship="id-8ba43687252f4e79b5f27c58d31d0c27"/>
+ <child xsi:type="archimate:DiagramObject" id="id-943cfb758f5e425c827b7aa9b25d9027" targetConnections="id-5380eaacfd934fa9afcdbfa03dc33119 id-b51483f783b34c1c862c996e09228ad6" archimateElement="id-1fcbf442e0ba4d069368041f58ddc3d5">
+ <bounds x="24" y="10" width="205" height="61"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-f673cb2b744c4d32b5b5b4813424bc10" targetConnections="id-8a6c00146b8147b0b1f49e9179e4d5c2 id-9f0b769736d94321a6e3eacf8a2ef96d id-01f63b2b7f974bdf83941d6bfe9fc26b" archimateElement="id-669d773a3f9640399c03ab1390a2bd6b" type="1">
+ <bounds x="384" y="72" width="96" height="25"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b51483f783b34c1c862c996e09228ad6" source="id-f673cb2b744c4d32b5b5b4813424bc10" target="id-943cfb758f5e425c827b7aa9b25d9027" archimateRelationship="id-56f67c68575a4729813b11e66d5a8b9e"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-f9629625556140688a1c5c820628307f" textPosition="1" archimateElement="id-469036c7c4d14b6dbf1d54fc23546467" type="1">
+ <bounds x="36" y="36" width="120" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-d2145347aada4b63995c3a1fab01a7f9" source="id-f9629625556140688a1c5c820628307f" target="id-1b93be2d5e7d4a5c87e257fd24514781" archimateRelationship="id-aa6779cb3ebc4131bc191e748b006dd7"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-1b93be2d5e7d4a5c87e257fd24514781" targetConnections="id-d2145347aada4b63995c3a1fab01a7f9 id-3822bffc8a2c4203a65387ba15de4c3a" textPosition="2" archimateElement="id-9d87d2c3dad949e8ba9943cdf3f6bbbd">
+ <bounds x="192" y="36" width="157" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-39a94519cd9c44b49ede53c4018a5639" source="id-1b93be2d5e7d4a5c87e257fd24514781" target="id-cfdd27dfc50c4fd8a4b923fe4310035d" archimateRelationship="id-967494823bdd4771a0058f0fe95ad5fc"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-01f63b2b7f974bdf83941d6bfe9fc26b" source="id-1b93be2d5e7d4a5c87e257fd24514781" target="id-f673cb2b744c4d32b5b5b4813424bc10" archimateRelationship="id-d2bc436327294ac2a24cc85fc122dde3"/>
+ <child xsi:type="archimate:DiagramObject" id="id-cfdd27dfc50c4fd8a4b923fe4310035d" targetConnections="id-39a94519cd9c44b49ede53c4018a5639" archimateElement="id-eac110ed899f42a0b19e97a329457afd" type="1">
+ <bounds x="12" y="12" width="120" height="67"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-2103a910e48f4c5ebb973f26700ded3d" textPosition="2" archimateElement="id-514656a32add4521bad7ab9a687f7288">
+ <bounds x="36" y="168" width="721" height="181"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-95aa942d9eda4f509eab2f43464883d9" source="id-2103a910e48f4c5ebb973f26700ded3d" target="id-97ad2e27376f4f8f97108d7c86313d65" archimateRelationship="id-8c3ac00c0f184e1bab24da76f1b64424"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-0aa68ba8eff5427faae78bdc3ed7b9c0" source="id-2103a910e48f4c5ebb973f26700ded3d" target="id-24ffc2228f5d44948cbf72989fca003c" archimateRelationship="id-3ba185bad1254de4abaabef58f184b66"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-5b5cd95ed33a4a40ae8c6e87b7642852" source="id-2103a910e48f4c5ebb973f26700ded3d" target="id-9c42fd5fc9e3482c9e1d9f1ad897da42" archimateRelationship="id-de9f2543e8474b3cba40f2f5e4ee7f7e"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-0478d287ffaf49788ea7f605fa444296" source="id-2103a910e48f4c5ebb973f26700ded3d" target="id-384f725fbc7e41cc8a8466023dd20854" archimateRelationship="id-d44f911f9c714f86b79e97bd917036ad"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-4920ce3c4df2425ab9fdc39acd938d71" source="id-2103a910e48f4c5ebb973f26700ded3d" target="id-6606961aeecb4f1d9f510f75a2e48df4" archimateRelationship="id-61853f8ed2b64d9d916246687ff1c46b"/>
+ <child xsi:type="archimate:DiagramObject" id="id-97ad2e27376f4f8f97108d7c86313d65" targetConnections="id-95aa942d9eda4f509eab2f43464883d9" textPosition="1" archimateElement="id-0b3efc73811e45138c8ff69f0f8a96d1">
+ <bounds x="576" y="24" width="120" height="55"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-24ffc2228f5d44948cbf72989fca003c" targetConnections="id-0aa68ba8eff5427faae78bdc3ed7b9c0" archimateElement="id-b3d269512182443297108af5739a9177">
+ <bounds x="516" y="96" width="120" height="55"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-9c42fd5fc9e3482c9e1d9f1ad897da42" targetConnections="id-5b5cd95ed33a4a40ae8c6e87b7642852" archimateElement="id-6db149e9d7d54761a66afe4cb53e8bce">
+ <bounds x="24" y="24" width="193" height="85"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-db34ea1d05db456db074687e19e921f9" source="id-9c42fd5fc9e3482c9e1d9f1ad897da42" target="id-7e5514a8ffd34f54888e52d34a9f8718" archimateRelationship="id-316256e0633f47f4bcdbb955521f4373"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-2ac75bccc0fc49d8a297ec7fbd40ded5" source="id-9c42fd5fc9e3482c9e1d9f1ad897da42" target="id-384f725fbc7e41cc8a8466023dd20854" archimateRelationship="id-445256d6a342495eb0543d65a6359c1f"/>
+ <child xsi:type="archimate:DiagramObject" id="id-7e5514a8ffd34f54888e52d34a9f8718" targetConnections="id-db34ea1d05db456db074687e19e921f9 id-8c80e70b48134dceb4891ab245e062f0" textPosition="2" archimateElement="id-152ad5a2e65b4a6ca6218aef0585e9b8">
+ <bounds x="24" y="24" width="150" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-7598c171803a47b693de61c3f767f739" source="id-7e5514a8ffd34f54888e52d34a9f8718" target="id-89b62c1d957b4b4eb1559ad67c351c3a" archimateRelationship="id-7920443b1b1d4d7fb7ca09f95f012203"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-384f725fbc7e41cc8a8466023dd20854" targetConnections="id-0478d287ffaf49788ea7f605fa444296 id-2ac75bccc0fc49d8a297ec7fbd40ded5" textPosition="2" archimateElement="id-19f86694391b4b9faa3a9e53a50fa621">
+ <bounds x="48" y="132" width="120" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-8c80e70b48134dceb4891ab245e062f0" source="id-384f725fbc7e41cc8a8466023dd20854" target="id-7e5514a8ffd34f54888e52d34a9f8718" archimateRelationship="id-a601e2267c664679ae33be3237fd567b">
+ <bendpoint startX="-36" startY="-48" endX="-51" endY="48"/>
+ </sourceConnection>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-6606961aeecb4f1d9f510f75a2e48df4" targetConnections="id-4920ce3c4df2425ab9fdc39acd938d71" textPosition="2" archimateElement="id-810dd6d86e1d4830baf22c5dc94a10ee">
+ <bounds x="264" y="24" width="215" height="121"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b2ae642f24ed4464a45597b2e1a73a7b" source="id-6606961aeecb4f1d9f510f75a2e48df4" target="id-89b62c1d957b4b4eb1559ad67c351c3a" archimateRelationship="id-b75fba5852e84be390def15ac80a1365"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-68e142cce8ae4712830de3b1a6b2b539" source="id-6606961aeecb4f1d9f510f75a2e48df4" target="id-58e1bd3479604f5fa5febf420d6282e4" archimateRelationship="id-e3340652694e40a8b94e01d3ac9e0033"/>
+ <child xsi:type="archimate:DiagramObject" id="id-89b62c1d957b4b4eb1559ad67c351c3a" targetConnections="id-b2ae642f24ed4464a45597b2e1a73a7b id-7598c171803a47b693de61c3f767f739" archimateElement="id-216b523d7d834938852c2c15476edec2" type="1">
+ <bounds x="12" y="12" width="132" height="33"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9f0b769736d94321a6e3eacf8a2ef96d" source="id-89b62c1d957b4b4eb1559ad67c351c3a" target="id-f673cb2b744c4d32b5b5b4813424bc10" archimateRelationship="id-4708075b62904f58a7eeb65528bd525b"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-62aa6e31df8549efb46ef188790efdef" source="id-89b62c1d957b4b4eb1559ad67c351c3a" target="id-1a1e064a10f04dddb5b5dc30f5a4600e" archimateRelationship="id-83c952112dbf4adea610a410dd7cb574"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-58e1bd3479604f5fa5febf420d6282e4" targetConnections="id-68e142cce8ae4712830de3b1a6b2b539" archimateElement="id-b55ebf8e98474ac5b36fd32c54cbfb36" type="1">
+ <bounds x="72" y="60" width="132" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-8a6c00146b8147b0b1f49e9179e4d5c2" source="id-58e1bd3479604f5fa5febf420d6282e4" target="id-f673cb2b744c4d32b5b5b4813424bc10" archimateRelationship="id-c53f4b2ccdce4f4594cdabd7a9441b8a">
+ <bendpoint startX="18" startY="-114" endX="24" endY="72"/>
+ </sourceConnection>
+ </child>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-1a1e064a10f04dddb5b5dc30f5a4600e" targetConnections="id-62aa6e31df8549efb46ef188790efdef" archimateElement="id-c9e941bae2164503a0792a914510f2ae" type="1">
+ <bounds x="36" y="84" width="120" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-3822bffc8a2c4203a65387ba15de4c3a" source="id-1a1e064a10f04dddb5b5dc30f5a4600e" target="id-1b93be2d5e7d4a5c87e257fd24514781" archimateRelationship="id-f404edb1099f48f492660f60d7d9d3d2"/>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="5. Moment of Transition" id="id-772f9f78757243338faa0af79f1f4653">
+ <child xsi:type="archimate:DiagramObject" id="id-e965f29d23cf467fa86378f85066e49c" archimateElement="id-f6b0869f2bcf47cebb836f47e076f2a4">
+ <bounds x="36" y="98" width="133" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-205331f945e1461a8992d0a2c9f37bb0" source="id-e965f29d23cf467fa86378f85066e49c" target="id-10892028ba954e7aa1cb31bb8c440c14" archimateRelationship="id-a4b686bbb3ad47bd9f6fda91b9aab652"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-7b6cd70a602d47e888cde446ff40f1c6" source="id-e965f29d23cf467fa86378f85066e49c" target="id-5cc29ef9bf3f4473af2eeb28458b6874" archimateRelationship="id-cd670a560d654b639894aafa9cf4b358"/>
+ <child xsi:type="archimate:DiagramObject" id="id-10892028ba954e7aa1cb31bb8c440c14" targetConnections="id-205331f945e1461a8992d0a2c9f37bb0 id-38f7a3be6f8940f8b4635e73be6768c6" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="24" y="36" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-588e9495e0224a12916a2ec7d506281f" source="id-10892028ba954e7aa1cb31bb8c440c14" target="id-900b8173b0324443b15c4b3382b87ae1" archimateRelationship="id-9f27bcdff61543989b8a396235dbe231"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-de803da1196845fa97a8c165b5bcd72e" targetConnections="id-f4258fa5a8a24cd08bed17f488ff85ef" archimateElement="id-7c4ad8b343ac45208f7e1f6e7dd73c41">
+ <bounds x="180" y="98" width="169" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-06201c9c87eb4aa98a42fc2ba2fc7f2f" source="id-de803da1196845fa97a8c165b5bcd72e" target="id-0074ba1b337b4f4193fc1b608551339b" archimateRelationship="id-46ac0fb1f08c4cf8a19e86c9d373efd6">
+ <bendpoint startX="60" startY="60" endX="-24" endY="-48"/>
+ </sourceConnection>
+ <sourceConnection xsi:type="archimate:Connection" id="id-c4093f2093fa44ffad6c2ac0b03bb56f" source="id-de803da1196845fa97a8c165b5bcd72e" target="id-e12532c78f0c4fcabca19f16443407ae" archimateRelationship="id-6851fcaa530c4947a28f55f63686e09a"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-23aaf55ed1db464d85f9b78c8466641b" source="id-de803da1196845fa97a8c165b5bcd72e" target="id-d4404ff475dd4fe6b97beff0b8a28ebf" archimateRelationship="id-115ae4f172d4441f89fd993e47cebcb6"/>
+ <child xsi:type="archimate:DiagramObject" id="id-e12532c78f0c4fcabca19f16443407ae" targetConnections="id-c4093f2093fa44ffad6c2ac0b03bb56f" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="24" y="24" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-a6a4671f765c46e39dcd128d59429031" source="id-e12532c78f0c4fcabca19f16443407ae" target="id-c72a112a93f24cda90c6d426468afd21" archimateRelationship="id-e9c76f1d8e9e44fba4b30125829cf872"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-38f7a3be6f8940f8b4635e73be6768c6" source="id-e12532c78f0c4fcabca19f16443407ae" target="id-10892028ba954e7aa1cb31bb8c440c14" archimateRelationship="id-2be6cd840e1c40ab8038a1dd49f493c8"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-5476944b9d1942e3876ffcd9c3f591fb" source="id-e12532c78f0c4fcabca19f16443407ae" target="id-0976a9856f3c4f4dbced1609fd85077d" archimateRelationship="id-2f00c98acfa643249b01ad4c20188c2a"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-d4404ff475dd4fe6b97beff0b8a28ebf" targetConnections="id-23aaf55ed1db464d85f9b78c8466641b" textAlignment="1" textPosition="2" archimateElement="id-b4aa7866aa7a498b9df96e3841fd4716">
+ <bounds x="96" y="60" width="59" height="25"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-4be089c65e3d4856bf43300c98b67ab0" source="id-d4404ff475dd4fe6b97beff0b8a28ebf" target="id-0074ba1b337b4f4193fc1b608551339b" archimateRelationship="id-e1a2f18187914ae1b8d0f03fa65d7772"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-94c87167c1ba4c27ace2cf3de97581c1" archimateElement="id-c156b9eb4a05406396a0816a1c7e03d2">
+ <bounds x="360" y="98" width="133" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9287a78d4fc04391897167e7bdcb884f" source="id-94c87167c1ba4c27ace2cf3de97581c1" target="id-c72a112a93f24cda90c6d426468afd21" archimateRelationship="id-a2fbcc8f796c493eaeb934ebc20cfd52"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-84eea4fe8fef49129535878ba7e4441d" source="id-94c87167c1ba4c27ace2cf3de97581c1" target="id-409c01f10d154591ad8b411b5b968dff" archimateRelationship="id-515fa83b4bcc4511be0a205e3cfc97d2"/>
+ <child xsi:type="archimate:DiagramObject" id="id-c72a112a93f24cda90c6d426468afd21" targetConnections="id-9287a78d4fc04391897167e7bdcb884f id-a6a4671f765c46e39dcd128d59429031" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="48" y="36" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b84070b1fb5b4608837d567a493f8d12" source="id-c72a112a93f24cda90c6d426468afd21" target="id-d5496c8c90e24470b911e499f85a8a54" archimateRelationship="id-055fc4c760d048868a34f168ef94fe76"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-0074ba1b337b4f4193fc1b608551339b" targetConnections="id-06201c9c87eb4aa98a42fc2ba2fc7f2f id-4be089c65e3d4856bf43300c98b67ab0" textPosition="2" archimateElement="id-d17e55e941184567b338f3e003ec1dd4">
+ <bounds x="108" y="254" width="313" height="61"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-354b86b027514884962d8276aaac5c2f" source="id-0074ba1b337b4f4193fc1b608551339b" target="id-409c01f10d154591ad8b411b5b968dff" archimateRelationship="id-81e1f60e2237483fbba9f3a03c0d427b"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-09a73931f7134b41992d95bce6d41952" source="id-0074ba1b337b4f4193fc1b608551339b" target="id-5cc29ef9bf3f4473af2eeb28458b6874" archimateRelationship="id-75f0940d0de84696ae650213fd6ab5ba"/>
+ <child xsi:type="archimate:DiagramObject" id="id-409c01f10d154591ad8b411b5b968dff" targetConnections="id-354b86b027514884962d8276aaac5c2f id-84eea4fe8fef49129535878ba7e4441d" textAlignment="1" textPosition="2" archimateElement="id-e3bbb23e04644f0c82e34dbe6de9f2a7">
+ <bounds x="216" y="12" width="75" height="37"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-5cc29ef9bf3f4473af2eeb28458b6874" targetConnections="id-7b6cd70a602d47e888cde446ff40f1c6 id-09a73931f7134b41992d95bce6d41952" textAlignment="1" textPosition="2" archimateElement="id-8159335d378e44a2b528ad609c69bffe">
+ <bounds x="12" y="12" width="73" height="37"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-900b8173b0324443b15c4b3382b87ae1" targetConnections="id-588e9495e0224a12916a2ec7d506281f" textPosition="2" archimateElement="id-17da1776ea434e91a193440cab695f6f" type="1">
+ <bounds x="36" y="202" width="63" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-0976a9856f3c4f4dbced1609fd85077d" targetConnections="id-5476944b9d1942e3876ffcd9c3f591fb" textPosition="2" archimateElement="id-9933f48411754bc4bde097aedcb356b5" type="1">
+ <bounds x="192" y="202" width="73" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-d5496c8c90e24470b911e499f85a8a54" targetConnections="id-b84070b1fb5b4608837d567a493f8d12" textPosition="2" archimateElement="id-fffd7eef08004ceea35a6d541f01d1fd" type="1">
+ <bounds x="432" y="202" width="61" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-7050707b08a1421396fef8ec655620c8" archimateElement="id-586ae0fbf4ff4f6ab121cf71240f02cc" type="1">
+ <bounds x="226" y="36" width="78" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-f4258fa5a8a24cd08bed17f488ff85ef" source="id-7050707b08a1421396fef8ec655620c8" target="id-de803da1196845fa97a8c165b5bcd72e" archimateRelationship="id-a7649bb791a542089ba484fde3dfc032"/>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="After migration" id="id-3e221107e06a4c168a3918573ff56b0a">
+ <child xsi:type="archimate:DiagramObject" id="id-0b1e93149ef2442a92d1ffb4b94add34" targetConnections="id-bffad1a0923d4c62aa1fd8ef143fc544" archimateElement="id-c156b9eb4a05406396a0816a1c7e03d2">
+ <bounds x="36" y="84" width="133" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b1389590ea7f4114a9b6da502028bd71" source="id-0b1e93149ef2442a92d1ffb4b94add34" target="id-46826e602555465ba73b1862eb9e1f8e" archimateRelationship="id-a2fbcc8f796c493eaeb934ebc20cfd52"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-92efac1b96c04970b4121d6adbc3d9ab" source="id-0b1e93149ef2442a92d1ffb4b94add34" target="id-2574f5d6722241e687166309b64124ec" archimateRelationship="id-515fa83b4bcc4511be0a205e3cfc97d2"/>
+ <child xsi:type="archimate:DiagramObject" id="id-46826e602555465ba73b1862eb9e1f8e" targetConnections="id-b1389590ea7f4114a9b6da502028bd71" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="48" y="36" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-d79399f94fcd4147b197c7eefaf1ab65" source="id-46826e602555465ba73b1862eb9e1f8e" target="id-62b02b7e5d274a61b4e70f1aa6da04e7" archimateRelationship="id-055fc4c760d048868a34f168ef94fe76"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-62b02b7e5d274a61b4e70f1aa6da04e7" targetConnections="id-d79399f94fcd4147b197c7eefaf1ab65" textPosition="2" archimateElement="id-fffd7eef08004ceea35a6d541f01d1fd" type="1">
+ <bounds x="108" y="204" width="61" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-2574f5d6722241e687166309b64124ec" targetConnections="id-92efac1b96c04970b4121d6adbc3d9ab" textPosition="2" archimateElement="id-e3bbb23e04644f0c82e34dbe6de9f2a7">
+ <bounds x="36" y="192" width="63" height="57"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-7eec6670737b4508853c9ff0e307eb6c" archimateElement="id-586ae0fbf4ff4f6ab121cf71240f02cc" type="1">
+ <bounds x="64" y="24" width="78" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-bffad1a0923d4c62aa1fd8ef143fc544" source="id-7eec6670737b4508853c9ff0e307eb6c" target="id-0b1e93149ef2442a92d1ffb4b94add34" archimateRelationship="id-55c1022e1cb744329303d1849d8b6d92"/>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="Before migration" id="id-718563961ee641398236cc4a84f9167e">
+ <child xsi:type="archimate:DiagramObject" id="id-a7a24e7829a540c6a9b9da08885d8301" targetConnections="id-627b668316874c6cae3cae287b098f87" archimateElement="id-f6b0869f2bcf47cebb836f47e076f2a4">
+ <bounds x="36" y="72" width="133" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-4ff0c9c545734abd96fcd1962a845de0" source="id-a7a24e7829a540c6a9b9da08885d8301" target="id-8d0221b21c5e451b8f68fa3bcc6a7985" archimateRelationship="id-a4b686bbb3ad47bd9f6fda91b9aab652"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-a2cefb7e4760403dafc9de8ce814cd24" source="id-a7a24e7829a540c6a9b9da08885d8301" target="id-348dfef6df99497b88df7f5944d2e1fd" archimateRelationship="id-cd670a560d654b639894aafa9cf4b358"/>
+ <child xsi:type="archimate:DiagramObject" id="id-8d0221b21c5e451b8f68fa3bcc6a7985" targetConnections="id-4ff0c9c545734abd96fcd1962a845de0" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="48" y="36" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9b93e3a90655499e8aa844775557a13d" source="id-8d0221b21c5e451b8f68fa3bcc6a7985" target="id-f8cb37046557416299af05250434c29a" archimateRelationship="id-9f27bcdff61543989b8a396235dbe231"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-348dfef6df99497b88df7f5944d2e1fd" targetConnections="id-a2cefb7e4760403dafc9de8ce814cd24" textPosition="2" archimateElement="id-8159335d378e44a2b528ad609c69bffe">
+ <bounds x="36" y="192" width="61" height="61"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-f8cb37046557416299af05250434c29a" targetConnections="id-9b93e3a90655499e8aa844775557a13d" textPosition="2" archimateElement="id-17da1776ea434e91a193440cab695f6f" type="1">
+ <bounds x="106" y="192" width="63" height="45"/>
+ </child>
+ <child xsi:type="archimate:Group" id="id-8a1cbc8e3fb546ad84f6649f557f62f3" name="Legend" textAlignment="1">
+ <bounds x="324" y="36" width="135" height="207"/>
+ <child xsi:type="archimate:DiagramObject" id="id-5d246706d8ab409dba53683e922a7a9a" archimateElement="id-c7f624b0cfa345c581e539282adbc602">
+ <bounds x="10" y="30" width="30" height="30"/>
+ </child>
+ <child xsi:type="archimate:Note" id="id-aee6ed4a21a449d987f1271aa257bd95" textAlignment="1" alpha="0">
+ <bounds x="50" y="24" width="83" height="47"/>
+ <feature name="lineAlpha" value="0"/>
+ <content>application back-end</content>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-942227ee861c4645a7444988f4cea588" archimateElement="id-e4a1f2550abc412980739bf839af303e">
+ <bounds x="10" y="70" width="30" height="30"/>
+ </child>
+ <child xsi:type="archimate:Note" id="id-66756191f3ab4ed3a6eeec313c80fe1b" textAlignment="1" alpha="0">
+ <bounds x="50" y="70" width="59" height="30"/>
+ <feature name="lineAlpha" value="0"/>
+ <content>service</content>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-de658af3062f471ca02b04df18144e8c" archimateElement="id-f9f8871221464027b310beb32585b0fe">
+ <bounds x="10" y="110" width="30" height="30"/>
+ </child>
+ <child xsi:type="archimate:Note" id="id-404bf03e37974cb587855d41c00027a5" textAlignment="1" alpha="0">
+ <bounds x="50" y="110" width="59" height="30"/>
+ <feature name="lineAlpha" value="0"/>
+ <content>data set</content>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-326af4ec0bb3403e9e26b93172041195" archimateElement="id-12a7f0386cb2437891fe48a828ff028d" type="1">
+ <bounds x="10" y="156" width="30" height="30"/>
+ </child>
+ <child xsi:type="archimate:Note" id="id-ba73cf1527134008951c3bcb5ef6c002" textAlignment="1" alpha="0">
+ <bounds x="50" y="156" width="59" height="30"/>
+ <feature name="lineAlpha" value="0"/>
+ <content>schema</content>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-78764e028e2b4893bc70008ebe00161e" archimateElement="id-586ae0fbf4ff4f6ab121cf71240f02cc" type="1">
+ <bounds x="64" y="12" width="78" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-627b668316874c6cae3cae287b098f87" source="id-78764e028e2b4893bc70008ebe00161e" target="id-a7a24e7829a540c6a9b9da08885d8301" archimateRelationship="id-9cc7a0d44d57449991b1cdea23fcb4ad"/>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="4. Moment of Deployment" id="id-0ae8230c31f0453084cb45041225a281">
+ <child xsi:type="archimate:DiagramObject" id="id-52571cffba3c4edc9309ab4ab59e0d39" targetConnections="id-bdbb4d3653f642308d50c28a44c36709" archimateElement="id-f6b0869f2bcf47cebb836f47e076f2a4">
+ <bounds x="36" y="98" width="133" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-dd593e2bb92c4aae8c383f0d4592ab67" source="id-52571cffba3c4edc9309ab4ab59e0d39" target="id-de98587d6f544ad6a9b3a12b596745a6" archimateRelationship="id-a4b686bbb3ad47bd9f6fda91b9aab652"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-f877ef2197c9413dbdf42dd26d4e0713" source="id-52571cffba3c4edc9309ab4ab59e0d39" target="id-ffadbdd6890444229a5cf4d908b4c4fe" archimateRelationship="id-cd670a560d654b639894aafa9cf4b358"/>
+ <child xsi:type="archimate:DiagramObject" id="id-de98587d6f544ad6a9b3a12b596745a6" targetConnections="id-dd593e2bb92c4aae8c383f0d4592ab67 id-a088c92cf3fc46e99b1d0a950863fc7b" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="24" y="36" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b01b68bfa8d74d0a8d1706b7c55e1f25" source="id-de98587d6f544ad6a9b3a12b596745a6" target="id-c23077d1ab4547599c007d49a877ccd4" archimateRelationship="id-9f27bcdff61543989b8a396235dbe231"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-88e2fa8d78484760b632260e7aed7e60" archimateElement="id-7c4ad8b343ac45208f7e1f6e7dd73c41">
+ <bounds x="180" y="98" width="169" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-73b7a8d3473d47569a5b12768e0b933f" source="id-88e2fa8d78484760b632260e7aed7e60" target="id-0baaeb18f9204dfda19dbec981d93291" archimateRelationship="id-46ac0fb1f08c4cf8a19e86c9d373efd6">
+ <bendpoint startX="60" startY="60" endX="-24" endY="-48"/>
+ </sourceConnection>
+ <sourceConnection xsi:type="archimate:Connection" id="id-145855e2c2144c80957a5df53cd6a8c3" source="id-88e2fa8d78484760b632260e7aed7e60" target="id-7a269da7530343a08516e58e399afee0" archimateRelationship="id-6851fcaa530c4947a28f55f63686e09a"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-1931d7621baf4f21b652d73c45464634" source="id-88e2fa8d78484760b632260e7aed7e60" target="id-61b4eb21f15648e9b579f2fb6c7282f3" archimateRelationship="id-115ae4f172d4441f89fd993e47cebcb6"/>
+ <child xsi:type="archimate:DiagramObject" id="id-7a269da7530343a08516e58e399afee0" targetConnections="id-145855e2c2144c80957a5df53cd6a8c3" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="24" y="24" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-ad4b9d7184f24163b04e76eff674a68e" source="id-7a269da7530343a08516e58e399afee0" target="id-e9bc01c573354adca72c9dc721e4910d" archimateRelationship="id-e9c76f1d8e9e44fba4b30125829cf872"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-a088c92cf3fc46e99b1d0a950863fc7b" source="id-7a269da7530343a08516e58e399afee0" target="id-de98587d6f544ad6a9b3a12b596745a6" archimateRelationship="id-2be6cd840e1c40ab8038a1dd49f493c8"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-1e92b72958714bd7b12e92004f41903a" source="id-7a269da7530343a08516e58e399afee0" target="id-d03f96187c4f4b038f16f9f461535817" archimateRelationship="id-2f00c98acfa643249b01ad4c20188c2a"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-61b4eb21f15648e9b579f2fb6c7282f3" targetConnections="id-1931d7621baf4f21b652d73c45464634" textAlignment="1" textPosition="2" archimateElement="id-b4aa7866aa7a498b9df96e3841fd4716">
+ <bounds x="96" y="60" width="59" height="25"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-30874c9f4a4648c3bdf80de4ca5074d4" source="id-61b4eb21f15648e9b579f2fb6c7282f3" target="id-0baaeb18f9204dfda19dbec981d93291" archimateRelationship="id-e1a2f18187914ae1b8d0f03fa65d7772"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-9802d19c6a464177b23562508c1a4f82" archimateElement="id-c156b9eb4a05406396a0816a1c7e03d2">
+ <bounds x="360" y="98" width="133" height="97"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9adf657eb2c24b6eaaa0bdf562e0a3f0" source="id-9802d19c6a464177b23562508c1a4f82" target="id-e9bc01c573354adca72c9dc721e4910d" archimateRelationship="id-a2fbcc8f796c493eaeb934ebc20cfd52"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-bd012402a99540baa9e710ecea0932d3" source="id-9802d19c6a464177b23562508c1a4f82" target="id-040d7f83c4a3493e89753d923bd2b305" archimateRelationship="id-515fa83b4bcc4511be0a205e3cfc97d2"/>
+ <child xsi:type="archimate:DiagramObject" id="id-e9bc01c573354adca72c9dc721e4910d" targetConnections="id-9adf657eb2c24b6eaaa0bdf562e0a3f0 id-ad4b9d7184f24163b04e76eff674a68e" textPosition="2" archimateElement="id-621a84fd26f24c198fa8e2c8aacd73de">
+ <bounds x="48" y="36" width="61" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-eeaef56cc37c416eb59e3d53ad078f9d" source="id-e9bc01c573354adca72c9dc721e4910d" target="id-145633a41f414a2e93b327ea5fc9feb5" archimateRelationship="id-055fc4c760d048868a34f168ef94fe76"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-0baaeb18f9204dfda19dbec981d93291" targetConnections="id-73b7a8d3473d47569a5b12768e0b933f id-30874c9f4a4648c3bdf80de4ca5074d4" textPosition="2" archimateElement="id-d17e55e941184567b338f3e003ec1dd4">
+ <bounds x="108" y="254" width="313" height="61"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-a610a5baf99d449b80865c857be738de" source="id-0baaeb18f9204dfda19dbec981d93291" target="id-040d7f83c4a3493e89753d923bd2b305" archimateRelationship="id-81e1f60e2237483fbba9f3a03c0d427b"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-7a3f4ff8feb24cb699d0804b22a4cde8" source="id-0baaeb18f9204dfda19dbec981d93291" target="id-ffadbdd6890444229a5cf4d908b4c4fe" archimateRelationship="id-75f0940d0de84696ae650213fd6ab5ba"/>
+ <child xsi:type="archimate:DiagramObject" id="id-040d7f83c4a3493e89753d923bd2b305" targetConnections="id-a610a5baf99d449b80865c857be738de id-bd012402a99540baa9e710ecea0932d3" textAlignment="1" textPosition="2" archimateElement="id-e3bbb23e04644f0c82e34dbe6de9f2a7">
+ <bounds x="216" y="12" width="75" height="37"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-ffadbdd6890444229a5cf4d908b4c4fe" targetConnections="id-f877ef2197c9413dbdf42dd26d4e0713 id-7a3f4ff8feb24cb699d0804b22a4cde8" textAlignment="1" textPosition="2" archimateElement="id-8159335d378e44a2b528ad609c69bffe">
+ <bounds x="12" y="12" width="73" height="37"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-c23077d1ab4547599c007d49a877ccd4" targetConnections="id-b01b68bfa8d74d0a8d1706b7c55e1f25" textPosition="2" archimateElement="id-17da1776ea434e91a193440cab695f6f" type="1">
+ <bounds x="36" y="202" width="63" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-d03f96187c4f4b038f16f9f461535817" targetConnections="id-1e92b72958714bd7b12e92004f41903a" textPosition="2" archimateElement="id-9933f48411754bc4bde097aedcb356b5" type="1">
+ <bounds x="192" y="202" width="73" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-145633a41f414a2e93b327ea5fc9feb5" targetConnections="id-eeaef56cc37c416eb59e3d53ad078f9d" textPosition="2" archimateElement="id-fffd7eef08004ceea35a6d541f01d1fd" type="1">
+ <bounds x="432" y="202" width="61" height="45"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-73b0787109344394a9e66bc8f21d5f00" archimateElement="id-586ae0fbf4ff4f6ab121cf71240f02cc" type="1">
+ <bounds x="64" y="36" width="78" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-bdbb4d3653f642308d50c28a44c36709" source="id-73b0787109344394a9e66bc8f21d5f00" target="id-52571cffba3c4edc9309ab4ab59e0d39" archimateRelationship="id-9cc7a0d44d57449991b1cdea23fcb4ad"/>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="Name mappings" id="id-fd229648f2074b7e99f059d015f631f3">
+ <child xsi:type="archimate:DiagramObject" id="id-0d86f16617c84c24bbb83472212917cf" targetConnections="id-85ca9469971c4406aa23aa71c07a02a5 id-b02efd1ae75b4b25b91ef5d3761229eb" textPosition="1" archimateElement="id-76de9e543bb84968a4bb9f73c43a7575">
+ <bounds x="504" y="120" width="73" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-2697b62bda90470fbcd379e0b7d56ad4" source="id-0d86f16617c84c24bbb83472212917cf" target="id-08819ef9fbd542439d81c5bea0052279" archimateRelationship="id-117cce9cbd904b4f8071936d42c964b3"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-82f43a34efa34f1eb9737c0cc2f88bb6" source="id-0d86f16617c84c24bbb83472212917cf" target="id-dc8e85ae4e4847c5af60794bee7caf5e" archimateRelationship="id-045b5873b4fa4a9abcd4b67c99c38687"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-f0d47c41170641d799538ff170e8e905" textPosition="1" archimateElement="id-412714f508a545aca720451e5a9ed212">
+ <bounds x="144" y="84" width="72" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-c3ec587c53e8405792184a041b4f505b" source="id-f0d47c41170641d799538ff170e8e905" target="id-08819ef9fbd542439d81c5bea0052279" archimateRelationship="id-df8837bdb8384db498d69ec781795f3b"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-701fe08c2a73446b96e4765662971a50" source="id-f0d47c41170641d799538ff170e8e905" target="id-dc8e85ae4e4847c5af60794bee7caf5e" archimateRelationship="id-26a87af9e7a84943a7ad6740627ac24e"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-c310247a44b948caadb171bd740ced13" source="id-f0d47c41170641d799538ff170e8e905" target="id-3d7c87ce3db744b492e3aec8cfe7827a" archimateRelationship="id-f92bf1ab2acc4b019783126c6859d11d"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-c0e7a63d5a9743d28ef1e3b2927c620d" textPosition="1" archimateElement="id-97d51d02994b44aa96a0d33f01149936">
+ <bounds x="504" y="36" width="73" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-85ca9469971c4406aa23aa71c07a02a5" source="id-c0e7a63d5a9743d28ef1e3b2927c620d" target="id-0d86f16617c84c24bbb83472212917cf" archimateRelationship="id-9fc956f7df9f487d9c5bc8591e90d078"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-e0dea4b96e444e7284ad3130a7a1815f" source="id-c0e7a63d5a9743d28ef1e3b2927c620d" target="id-08819ef9fbd542439d81c5bea0052279" archimateRelationship="id-511581f6addd4d90bb11ac4c2c4f1a40"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-08819ef9fbd542439d81c5bea0052279" targetConnections="id-2697b62bda90470fbcd379e0b7d56ad4 id-e0dea4b96e444e7284ad3130a7a1815f id-c3ec587c53e8405792184a041b4f505b id-e354902265db4c60bb2161a913bf5992" textPosition="1" archimateElement="id-14e1f329f21b4c5bb8750e7d1d63398e">
+ <bounds x="312" y="36" width="73" height="55"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-ad137a2afcfc427db052adb44bcab278" targetConnections="id-75def44de4c9491f9dd1dbd9b613868b" textPosition="2" archimateElement="id-d416c59ad9ea47289dcde683423d2c5d">
+ <bounds x="36" y="36" width="97" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-e354902265db4c60bb2161a913bf5992" source="id-ad137a2afcfc427db052adb44bcab278" target="id-08819ef9fbd542439d81c5bea0052279" archimateRelationship="id-fa0be40b19214c7da59aac2c1b6c09a7"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-ed697bd37be144a99d5aa7feb82a91ef" textPosition="1" archimateElement="id-3d3be9e73ff44f4a96d5991f8502ed09">
+ <bounds x="504" y="204" width="73" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-d3ba46396bd34519a17faf0d3e704e89" source="id-ed697bd37be144a99d5aa7feb82a91ef" target="id-dc8e85ae4e4847c5af60794bee7caf5e" archimateRelationship="id-22e4c1f03e0d46c890334a563ddbe875"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b02efd1ae75b4b25b91ef5d3761229eb" source="id-ed697bd37be144a99d5aa7feb82a91ef" target="id-0d86f16617c84c24bbb83472212917cf" archimateRelationship="id-0378c126913149359b6f1efeb6479931"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-dc8e85ae4e4847c5af60794bee7caf5e" targetConnections="id-d3ba46396bd34519a17faf0d3e704e89 id-82f43a34efa34f1eb9737c0cc2f88bb6 id-701fe08c2a73446b96e4765662971a50 id-9f4fef0ce94749b2b6918935c3cabc67" textPosition="1" archimateElement="id-063da8b38955436eac2d96896b82601f">
+ <bounds x="311" y="204" width="73" height="55"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-3d7c87ce3db744b492e3aec8cfe7827a" targetConnections="id-c310247a44b948caadb171bd740ced13" textPosition="2" archimateElement="id-69b5cb7448e542c699460419020bba14">
+ <bounds x="36" y="168" width="133" height="91"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9f4fef0ce94749b2b6918935c3cabc67" source="id-3d7c87ce3db744b492e3aec8cfe7827a" target="id-dc8e85ae4e4847c5af60794bee7caf5e" archimateRelationship="id-366532c2266c43269c1312d3d2fbaa4a"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-8d93d4d9d16748f99bf3a4187e2fac8a" source="id-3d7c87ce3db744b492e3aec8cfe7827a" target="id-52ff0cfae8db460d9c7dfc628f32e03b" archimateRelationship="id-47a5898bbd3f4b2888f16ed53759dd73"/>
+ <child xsi:type="archimate:DiagramObject" id="id-52ff0cfae8db460d9c7dfc628f32e03b" targetConnections="id-8d93d4d9d16748f99bf3a4187e2fac8a" textPosition="2" archimateElement="id-5fed881eea4a467e99ec539b2ccb900c">
+ <bounds x="12" y="12" width="70" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-75def44de4c9491f9dd1dbd9b613868b" source="id-52ff0cfae8db460d9c7dfc628f32e03b" target="id-ad137a2afcfc427db052adb44bcab278" archimateRelationship="id-621c1c0b39624a78a256d779f722a24d"/>
+ </child>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="Documentation structure" id="id-9ecb7779ff204376bb41ec26736b3b6f">
+ <child xsi:type="archimate:DiagramObject" id="id-457909b398f4419cbb9e614d736b9c7f" archimateElement="id-514656a32add4521bad7ab9a687f7288">
+ <bounds x="36" y="36" width="733" height="313"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-d632ba32e0dc417b87fab2465e1e86a3" source="id-457909b398f4419cbb9e614d736b9c7f" target="id-eaefec32c5924e35a84ccbc786c51cf6" archimateRelationship="id-8c3ac00c0f184e1bab24da76f1b64424"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-4baecd8c39454e9f833d2a54dcf44831" source="id-457909b398f4419cbb9e614d736b9c7f" target="id-3fbb10bc74444fdf9bb7d56cfb33e800" archimateRelationship="id-3ba185bad1254de4abaabef58f184b66"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-be82c49fd8c947be8763a2ca4ea99257" source="id-457909b398f4419cbb9e614d736b9c7f" target="id-3c7d0fa99f2a44ab8102abaf732748dd" archimateRelationship="id-de9f2543e8474b3cba40f2f5e4ee7f7e"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-935a6a18b1df40e08a1b5dfef407fedd" source="id-457909b398f4419cbb9e614d736b9c7f" target="id-36fea4323b894e51a39998a83c6be0c8" archimateRelationship="id-61853f8ed2b64d9d916246687ff1c46b"/>
+ <child xsi:type="archimate:DiagramObject" id="id-eaefec32c5924e35a84ccbc786c51cf6" targetConnections="id-d632ba32e0dc417b87fab2465e1e86a3" textPosition="2" archimateElement="id-0b3efc73811e45138c8ff69f0f8a96d1">
+ <bounds x="564" y="24" width="144" height="271"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-5d577e35851d4c0899378bbcd8d73972" source="id-eaefec32c5924e35a84ccbc786c51cf6" target="id-162d7835d2ee4661b79b6b969e49c772" archimateRelationship="id-2ed37eba33814300af416e0081c50497"/>
+ <child xsi:type="archimate:DiagramObject" id="id-162d7835d2ee4661b79b6b969e49c772" targetConnections="id-c952741ff14b44d692e35b82e8f4e785 id-5d577e35851d4c0899378bbcd8d73972" archimateElement="id-4cc69dbbfed147a08f86f00a7b5243e4">
+ <bounds x="12" y="120" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-aa429ef92781466990d0e3c37605a0e0" source="id-162d7835d2ee4661b79b6b969e49c772" target="id-fa19fb3adefa4dd8b765c0cdbe0977d9" archimateRelationship="id-720fa550b0de4b62884bdf5175955dfd">
+ <bendpoint startX="-91" startY="-51" endX="456" endY="-15"/>
+ </sourceConnection>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-9a49b070726e4315be1252b8070fd376" textPosition="1" archimateElement="id-f48d5f70855f4b3fb29070d3c6813582">
+ <bounds x="34" y="12" width="75" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-c952741ff14b44d692e35b82e8f4e785" source="id-9a49b070726e4315be1252b8070fd376" target="id-162d7835d2ee4661b79b6b969e49c772" archimateRelationship="id-4183174ad2b740cca1323d98e08ef2b0"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-3fbb10bc74444fdf9bb7d56cfb33e800" targetConnections="id-4baecd8c39454e9f833d2a54dcf44831" textPosition="2" archimateElement="id-b3d269512182443297108af5739a9177">
+ <bounds x="391" y="24" width="144" height="271"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9137a34465d340019079076a815e0e66" source="id-3fbb10bc74444fdf9bb7d56cfb33e800" target="id-ff14de2607134558b3ad27b68d0bc0ec" archimateRelationship="id-ad21076ff0024214a45fb0f1e9c5fa4b"/>
+ <child xsi:type="archimate:DiagramObject" id="id-ff14de2607134558b3ad27b68d0bc0ec" targetConnections="id-17968e1c643c4db083f35e59f1e1dfd5 id-9137a34465d340019079076a815e0e66" archimateElement="id-19f46ddaa41d46998f30ab569caaf403">
+ <bounds x="12" y="120" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-45c1452f23204267883a1903ad28ce16" source="id-ff14de2607134558b3ad27b68d0bc0ec" target="id-fa19fb3adefa4dd8b765c0cdbe0977d9" archimateRelationship="id-5b7cc3e54b9a477d8b539413de52e0cb">
+ <bendpoint startX="-91" startY="-51" endX="276" endY="-15"/>
+ </sourceConnection>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-b7eb1da339b4412093e90a99a8d55d41" textPosition="1" archimateElement="id-933a4166eaeb4258b1e3e8a6ab3aec99">
+ <bounds x="34" y="12" width="75" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-17968e1c643c4db083f35e59f1e1dfd5" source="id-b7eb1da339b4412093e90a99a8d55d41" target="id-ff14de2607134558b3ad27b68d0bc0ec" archimateRelationship="id-edc00785709e4b11aa8d9556d806b8c7"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-3c7d0fa99f2a44ab8102abaf732748dd" targetConnections="id-be82c49fd8c947be8763a2ca4ea99257" textPosition="2" archimateElement="id-6db149e9d7d54761a66afe4cb53e8bce">
+ <bounds x="211" y="24" width="144" height="271"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-8b59f30a1c3040f98fa4672ae55ddc68" source="id-3c7d0fa99f2a44ab8102abaf732748dd" target="id-cfc31c2574f347e19ceba2f4a8645d04" archimateRelationship="id-16d39c506b29441aac9aa563cff62eea"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-ecfffe1baab346b184c8b967ef27c7c1" source="id-3c7d0fa99f2a44ab8102abaf732748dd" target="id-b48af43ee7ee41d6a22d696deae37e22" archimateRelationship="id-1eaa372f869e4353bccbdc63efd1f678"/>
+ <child xsi:type="archimate:DiagramObject" id="id-cfc31c2574f347e19ceba2f4a8645d04" targetConnections="id-245cc1a445064016b03d44cad2b4e36a id-8b59f30a1c3040f98fa4672ae55ddc68" archimateElement="id-2995b55c8d6f48e58fb894da9d89422e">
+ <bounds x="12" y="120" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-783ed610e3244544b5018bd7c911d8af" source="id-cfc31c2574f347e19ceba2f4a8645d04" target="id-fa19fb3adefa4dd8b765c0cdbe0977d9" archimateRelationship="id-3bd75edcbf6041c7adbf9ecf4da1b89e">
+ <bendpoint startX="-91" startY="-51" endX="96" endY="-15"/>
+ </sourceConnection>
+ <sourceConnection xsi:type="archimate:Connection" id="id-6b9b709b2fda4a55886cc670f961fef2" source="id-cfc31c2574f347e19ceba2f4a8645d04" target="id-b48af43ee7ee41d6a22d696deae37e22" archimateRelationship="id-bb278626027943e18eff6c00c766e28d">
+ <bendpoint startX="41" startY="57" endX="-48" endY="-39"/>
+ </sourceConnection>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-b281be488fc64699ab32192b8780ac77" textPosition="1" archimateElement="id-933a4166eaeb4258b1e3e8a6ab3aec99">
+ <bounds x="34" y="12" width="75" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-245cc1a445064016b03d44cad2b4e36a" source="id-b281be488fc64699ab32192b8780ac77" target="id-cfc31c2574f347e19ceba2f4a8645d04" archimateRelationship="id-ee20563217244f42a20ea601a48b58b2"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-9b188bf6e3474d9d8abf5b97e916be32" source="id-b281be488fc64699ab32192b8780ac77" target="id-b48af43ee7ee41d6a22d696deae37e22" archimateRelationship="id-9ea802215392464d966332e86abdc306">
+ <bendpoint startX="78" startY="81" endX="72" endY="-102"/>
+ <bendpoint startX="78" startY="141" endX="72" endY="-42"/>
+ </sourceConnection>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-b48af43ee7ee41d6a22d696deae37e22" targetConnections="id-6b9b709b2fda4a55886cc670f961fef2 id-9b188bf6e3474d9d8abf5b97e916be32 id-ecfffe1baab346b184c8b967ef27c7c1" archimateElement="id-09c03741835148fb8ec247396b422b88">
+ <bounds x="23" y="204" width="109" height="37"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-36fea4323b894e51a39998a83c6be0c8" targetConnections="id-935a6a18b1df40e08a1b5dfef407fedd" textPosition="2" archimateElement="id-810dd6d86e1d4830baf22c5dc94a10ee">
+ <bounds x="12" y="24" width="169" height="271"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-8215477fc72a4acba3356b79319bf426" source="id-36fea4323b894e51a39998a83c6be0c8" target="id-fa19fb3adefa4dd8b765c0cdbe0977d9" archimateRelationship="id-fd94bf9017de4538a96c8742f773839e"/>
+ <child xsi:type="archimate:DiagramObject" id="id-fa19fb3adefa4dd8b765c0cdbe0977d9" targetConnections="id-cbaf21cff87c4695a6eaf151af792277 id-783ed610e3244544b5018bd7c911d8af id-45c1452f23204267883a1903ad28ce16 id-aa429ef92781466990d0e3c37605a0e0 id-8215477fc72a4acba3356b79319bf426" archimateElement="id-b0e4256b6bb2445691a9831a7547a1a0">
+ <bounds x="24" y="84" width="120" height="55"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-03be624c3055458ba6edad4d6b9694be" textPosition="1" archimateElement="id-f48d5f70855f4b3fb29070d3c6813582">
+ <bounds x="46" y="12" width="75" height="37"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-cbaf21cff87c4695a6eaf151af792277" source="id-03be624c3055458ba6edad4d6b9694be" target="id-fa19fb3adefa4dd8b765c0cdbe0977d9" archimateRelationship="id-65623262f80e4f9692153935b5c1492c"/>
+ </child>
+ </child>
+ </child>
+ </element>
+ <element xsi:type="archimate:ArchimateDiagramModel" name="IS structure" id="id-f1000d06cdd9443ca130dd287144a043">
+ <child xsi:type="archimate:DiagramObject" id="id-5e7ab37b295f46eab9ebb7a0cd802ead" targetConnections="id-6ddbb46a48474d8a8a714a2080e5160b id-69f5aaed02f44b748410ae1addaf92f9 id-cf94cdff518541a7a1a1d86a46f1dd12" textPosition="1" archimateElement="id-c87fbe964fdb4ca48eadc47010857f10">
+ <bounds x="336" y="36" width="120" height="55"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-5a84814cb34648e0b11b5d574c77ac2b" targetConnections="id-04e3c33855d54938a31584d4157bceb9" archimateElement="id-3349621c3582424a9b2940d14f56ccbc">
+ <bounds x="336" y="108" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-69f5aaed02f44b748410ae1addaf92f9" source="id-5a84814cb34648e0b11b5d574c77ac2b" target="id-5e7ab37b295f46eab9ebb7a0cd802ead" archimateRelationship="id-f9e5be02d5dd4e74bd5911f30e175916"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-156ac0b23c7c4458a11f33fbc4fed90f" targetConnections="id-0e91f076dc21497d875fa80eee08b1e2" archimateElement="id-3349621c3582424a9b2940d14f56ccbc">
+ <bounds x="480" y="108" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-6ddbb46a48474d8a8a714a2080e5160b" source="id-156ac0b23c7c4458a11f33fbc4fed90f" target="id-5e7ab37b295f46eab9ebb7a0cd802ead" archimateRelationship="id-00596da412af4c339e9ab007e668ac99"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-89ca344dac3f41e7bc91042e59de3330" targetConnections="id-2671dbd8e0d64f1db4acbee63bd5132d" archimateElement="id-3349621c3582424a9b2940d14f56ccbc">
+ <bounds x="192" y="108" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-cf94cdff518541a7a1a1d86a46f1dd12" source="id-89ca344dac3f41e7bc91042e59de3330" target="id-5e7ab37b295f46eab9ebb7a0cd802ead" archimateRelationship="id-8d494f2f43bd452785e2e352d197d185"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-05d36473a012403c974cc0bd1dc4d4e0" archimateElement="id-825f1ded85cc49aaafb9d5fd03010c11">
+ <bounds x="192" y="180" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-2671dbd8e0d64f1db4acbee63bd5132d" source="id-05d36473a012403c974cc0bd1dc4d4e0" target="id-89ca344dac3f41e7bc91042e59de3330" archimateRelationship="id-c80f1897dece4fb0a7bcc4148c819bc8"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-bf30a3fe48f7422bb9c326b6e54518b0" targetConnections="id-80997b8e7dab43938195d73b3697280a id-7a26b1dd019146bc99a397cb2ceb4b89 id-727d32777b6a49f28d7dafefcd3a1788 id-f07b4831273a4ec1860229283352cbf3 id-cab0631e006a4bf4b167c8400fbbbcdb" archimateElement="id-825f1ded85cc49aaafb9d5fd03010c11">
+ <bounds x="336" y="180" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-04e3c33855d54938a31584d4157bceb9" source="id-bf30a3fe48f7422bb9c326b6e54518b0" target="id-5a84814cb34648e0b11b5d574c77ac2b" archimateRelationship="id-83aa7d15a2e34215b8f6ce6aa324046e"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-1164f02326e44b6f873ed4aa92f5eac3" archimateElement="id-825f1ded85cc49aaafb9d5fd03010c11">
+ <bounds x="480" y="180" width="120" height="55"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-0e91f076dc21497d875fa80eee08b1e2" source="id-1164f02326e44b6f873ed4aa92f5eac3" target="id-156ac0b23c7c4458a11f33fbc4fed90f" archimateRelationship="id-0d56ff12b91c4163aab7e6a2ee667003"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-eee7d64767834531bbb6e2113d5265e0" targetConnections="id-387046c2e18f4dbcbc23b5ff0491ad0a" textPosition="2" archimateElement="id-4cbc6be959ef49e18aee938b3328e8d1">
+ <bounds x="192" y="252" width="49" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-80997b8e7dab43938195d73b3697280a" source="id-eee7d64767834531bbb6e2113d5265e0" target="id-bf30a3fe48f7422bb9c326b6e54518b0" archimateRelationship="id-ae7a7a1d49b64d009877170d343ee328"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-dcd986cdc7284e6796da7a8e26b24f68" targetConnections="id-fb2f16ac6c9d455b8c03d456bdb6bb82" textPosition="2" archimateElement="id-4cbc6be959ef49e18aee938b3328e8d1">
+ <bounds x="252" y="252" width="49" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-7a26b1dd019146bc99a397cb2ceb4b89" source="id-dcd986cdc7284e6796da7a8e26b24f68" target="id-bf30a3fe48f7422bb9c326b6e54518b0" archimateRelationship="id-28315e3d344645c39c210581c8a6c8b2"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-9f647ff6153a41b18cce49a26d467175" targetConnections="id-b1346bcffbd14c27be710e43dacc76ba" textPosition="2" archimateElement="id-4cbc6be959ef49e18aee938b3328e8d1">
+ <bounds x="552" y="252" width="49" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-cab0631e006a4bf4b167c8400fbbbcdb" source="id-9f647ff6153a41b18cce49a26d467175" target="id-bf30a3fe48f7422bb9c326b6e54518b0" archimateRelationship="id-40799f207ef048238fbcd3a3fe68433b"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-e5afd4d993ff48f69ec9facb6973dc80" targetConnections="id-7db537d84fc644b98a794e56ddd8e219" textPosition="2" archimateElement="id-4cbc6be959ef49e18aee938b3328e8d1">
+ <bounds x="492" y="252" width="49" height="49"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-f07b4831273a4ec1860229283352cbf3" source="id-e5afd4d993ff48f69ec9facb6973dc80" target="id-bf30a3fe48f7422bb9c326b6e54518b0" archimateRelationship="id-d35830df2b4a40baab58f3ba36373f7f"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-96d2411e77d74f0e855f8abd82c839ab" targetConnections="id-a31074b74bbd4dc2b82527deebac6596" textAlignment="1" archimateElement="id-4cbc6be959ef49e18aee938b3328e8d1">
+ <bounds x="311" y="252" width="170" height="145"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-ee08787ffcae43c0a73b36101006a923" source="id-96d2411e77d74f0e855f8abd82c839ab" target="id-577f293631ef41fd803e8df5fd25b01d" archimateRelationship="id-1044daa245e0479db77852b5dc388426"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-fe2f99c5ca4548ba8c881d4bc92b153e" source="id-96d2411e77d74f0e855f8abd82c839ab" target="id-db64a01e81504809904d1aebebdfcfb9" archimateRelationship="id-0bf2ec3b86f249a699a157b2319dc524"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-1b00f20ffb8b473dba9a6cab6f84bdc4" source="id-96d2411e77d74f0e855f8abd82c839ab" target="id-607927cf83e548b4b8923d2876ea36af" archimateRelationship="id-b6b3da68540949aaa20e405c0b612205"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-ff31a079ceb840cebf5e702496f99bba" source="id-96d2411e77d74f0e855f8abd82c839ab" target="id-5d9f230dc7004ea293eaa165a19f79c3" archimateRelationship="id-2f3292d9cc0741e080bd0860a37b060c"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-727d32777b6a49f28d7dafefcd3a1788" source="id-96d2411e77d74f0e855f8abd82c839ab" target="id-bf30a3fe48f7422bb9c326b6e54518b0" archimateRelationship="id-4f64ceead1f94bb98f387fcd9dc7dbba"/>
+ <child xsi:type="archimate:DiagramObject" id="id-577f293631ef41fd803e8df5fd25b01d" targetConnections="id-ee08787ffcae43c0a73b36101006a923" textPosition="2" archimateElement="id-def630c240c543f3a6d74218739aefdd">
+ <bounds x="6" y="24" width="73" height="47"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-db64a01e81504809904d1aebebdfcfb9" targetConnections="id-fe2f99c5ca4548ba8c881d4bc92b153e" textPosition="2" archimateElement="id-def630c240c543f3a6d74218739aefdd">
+ <bounds x="90" y="84" width="73" height="47"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-607927cf83e548b4b8923d2876ea36af" targetConnections="id-1b00f20ffb8b473dba9a6cab6f84bdc4" textPosition="2" archimateElement="id-def630c240c543f3a6d74218739aefdd">
+ <bounds x="6" y="84" width="73" height="47"/>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-5d9f230dc7004ea293eaa165a19f79c3" targetConnections="id-ff31a079ceb840cebf5e702496f99bba" textPosition="2" archimateElement="id-def630c240c543f3a6d74218739aefdd">
+ <bounds x="90" y="24" width="73" height="47"/>
+ </child>
+ </child>
+ <child xsi:type="archimate:DiagramObject" id="id-050c01cd265d4f0d88c68cb5b4cc79c4" archimateElement="id-379bf6291b66447bbe911a8d6643dff2" type="1">
+ <bounds x="192" y="408" width="407" height="30"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-b1346bcffbd14c27be710e43dacc76ba" source="id-050c01cd265d4f0d88c68cb5b4cc79c4" target="id-9f647ff6153a41b18cce49a26d467175" archimateRelationship="id-da9dace0a9c049d9a725448909e583ea"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-7db537d84fc644b98a794e56ddd8e219" source="id-050c01cd265d4f0d88c68cb5b4cc79c4" target="id-e5afd4d993ff48f69ec9facb6973dc80" archimateRelationship="id-585248e970964400b911d2b08b6bf0d2"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-a31074b74bbd4dc2b82527deebac6596" source="id-050c01cd265d4f0d88c68cb5b4cc79c4" target="id-96d2411e77d74f0e855f8abd82c839ab" archimateRelationship="id-9ba8fd52e70b4908877d5074d39914e3"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-fb2f16ac6c9d455b8c03d456bdb6bb82" source="id-050c01cd265d4f0d88c68cb5b4cc79c4" target="id-dcd986cdc7284e6796da7a8e26b24f68" archimateRelationship="id-4459e37ddf4c4a03875635ef09e44d3e"/>
+ <sourceConnection xsi:type="archimate:Connection" id="id-387046c2e18f4dbcbc23b5ff0491ad0a" source="id-050c01cd265d4f0d88c68cb5b4cc79c4" target="id-eee7d64767834531bbb6e2113d5265e0" archimateRelationship="id-7f9fb8967b7e4c61a8d28cde8ad389ef"/>
+ </child>
+ <child xsi:type="archimate:Note" id="id-4db6ba1a40bc473d912fc7a4b7a50df6" textAlignment="1">
+ <bounds x="635" y="108" width="185" height="55"/>
+ <content>Doet één ding en doet dat volledig.</content>
+ </child>
+ <child xsi:type="archimate:Note" id="id-cc77547293d24ec6b9d38c6cf3f52ac2" textAlignment="1">
+ <bounds x="635" y="180" width="206" height="61"/>
+ <content>Aanspreekbaar door gebruikers, vaak via een URL. Realiseert niet-functionele eisen.</content>
+ </child>
+ <child xsi:type="archimate:Note" id="id-41c72db07bae4d2da37d889f1e4fbbbc" textAlignment="1">
+ <bounds x="635" y="252" width="206" height="85"/>
+ <content>Een pod is een zelfstandig gedeployde hoeveelheid software, die draait op één computer binnen vooraf gedefinieerde grenzen. </content>
+ </child>
+ <child xsi:type="archimate:Note" id="id-e6474bad528a434baa639ceebd2b3ffe" textAlignment="1">
+ <bounds x="635" y="348" width="206" height="61"/>
+ <content>Een container is een geisoleerde VM, zonder eigen persistente opslag.</content>
+ </child>
+ </element>
+ </folder>
+ <purpose>This model is a collection of architectural products that describe the Ampersand project. Each view has a purpose of its own and is not necessarily related to other views.</purpose>
+</archimate:model>
diff --git a/ArchitectureAndDesign/Syntax/Pre 2010 version/ADL_V1.0.ebnf b/ArchitectureAndDesign/Syntax/Pre 2010 version/ADL_V1.0.ebnf
index 7ddcd6581d..37abc24d96 100644
--- a/ArchitectureAndDesign/Syntax/Pre 2010 version/ADL_V1.0.ebnf
+++ b/ArchitectureAndDesign/Syntax/Pre 2010 version/ADL_V1.0.ebnf
@@ -4,12 +4,12 @@ Context ::= 'CONTEXT' Id
Declaration |
ConceptDef |
KeyDef |
- Service |
+ Interface |
Plug |
Explain |
Population
)* 'ENDCONTEXT'
-Explain ::= 'EXPLAIN' (( ('CONCEPT'|'RULE'|'KEY'|'PATTERN'|'SERVICE'|'CONTEXT') Id)|'RELATION' Relation Sign)
+Explain ::= 'EXPLAIN' (( ('CONCEPT'|'RULE'|'KEY'|'PATTERN'|'INTERFACE'|'CONTEXT') Id)|'RELATION' Relation Sign)
('IN' ('DUTCH' | 'ENGLISH'))?
('REF' String)? ExplainString
Population ::= 'POPULATION' Relation Sign? 'CONTAINS' Content
@@ -35,7 +35,7 @@ LabelProps ::= Id ('{' Id (',' (Id Id*))* '}')? ':'
ConceptDef ::= 'CONCEPT' Id String String?
KeyDef ::= 'KEY' LabelProps Concept '(' (LabelProps? Term)(',' (LabelProps? Term))* ')'
Plug ::= ('SQLPLUG' | 'PHPPLUG') Obj
-Service ::= 'SERVICE' ('(' (Relation Sign?) (',' (Relation Sign?))* ')')?
+Interface ::= 'INTERFACE' ('(' (Relation Sign?) (',' (Relation Sign?))* ')')?
('{' (Id ) (','? Id)*'}')?
(':' Expr)
('=' '[' (Obj (',' Obj)*)? ']')?
diff --git a/ReleaseNotes.md b/ReleaseNotes.md
index 6e6769366d..d95d82c5e2 100644
--- a/ReleaseNotes.md
+++ b/ReleaseNotes.md
@@ -5,7 +5,7 @@
* [Issue #1419](https://github.com/AmpersandTarski/Ampersand/issues/1419) added a test, to be activated in the regression after resolving #1419.
* [Issue #1420](https://github.com/AmpersandTarski/Ampersand/issues/1420) added a test, to be activated in the regression after resolving #1420.
* [Issue #1421](https://github.com/AmpersandTarski/Ampersand/issues/1421) added easier development through Docker image at dockerhub: [ampersandtarski/ampersand-devcontainer](https://hub.docker.com/repository/docker/ampersandtarski/ampersand-devcontainer/general). Also fixes https://github.com/AmpersandTarski/Ampersand/issues/1359
-
+* Development of Ampersand generator can now be done with codespaces.
## v4.7.6 (26 february 2023)
## v4.7.5 (25 february 2023)
@@ -224,7 +224,7 @@ New CI workflow for releases to be pushed automatically to DockerHub with semver
## v3.16.0 (8 april 2019) (few days before scedule)
-- New switch: --daemon. This enables automatic checking of your scripts as you type. Very nice in combination with the vscode extension [Ampersand (ADL) language support](https://marketplace.visualstudio.com/items?itemName=AmpersandTarski.language-ampersand).
+- New switch: --daemon. This enables automatic checking of your scripts as you type. Very nice in combination with the vscode extension [Ampersand language support](https://marketplace.visualstudio.com/items?itemName=AmpersandTarski.language-ampersand).
- [Issue #920](https://github.com/AmpersandTarski/Ampersand/issues/920) Warnings are generated for concepts/relations with names that are equal except for the caseing.
## v3.15.0 (15 march 2019)
diff --git a/docker/with-texlive/Dockerfile b/docker/with-texlive/Dockerfile
deleted file mode 100644
index edd231266c..0000000000
--- a/docker/with-texlive/Dockerfile
+++ /dev/null
@@ -1,25 +0,0 @@
-# !!!!!!!!!!!!!!
-# This Dockerfile is not yet working or tested
-# Contains old setup. Rethinking how to effectively and efficiently textlive can be used by Ampersand compiler
-# !!!!!!!!!!!!!
-FROM ampersandtarski/ampersand:latest
-
-RUN apt-get update \
- && apt-get install -y --no-install-recommends \
- curl \
- netbase \
- wget \
- zlib1g-dev \
- graphviz \
- ghostscript
-
-# install texlive from network
-ENV PATH /texlive/bin/x86_64-linux:$PATH
-ADD texlive.profile /tmp
-RUN cd ~ \
- && curl http://ctan.mirrors.hoobly.com/systems/texlive/tlnet/install-tl-unx.tar.gz | tar -vxz \
- && cd install-tl* \
- && ./install-tl -profile /tmp/texlive.profile -repository http://ftp.uni-erlangen.de/mirrors/CTAN/systems/texlive/tlnet/ \
- && cd .. \
- && rm -rf install-tl* \
- && rm /tmp/texlive.profile
diff --git a/docker/with-texlive/texlive.profile b/docker/with-texlive/texlive.profile
deleted file mode 100644
index ec6897d46e..0000000000
--- a/docker/with-texlive/texlive.profile
+++ /dev/null
@@ -1,11 +0,0 @@
-TEXDIR /texlive
-TEXMFSYSVAR /texlive/texmf-var
-TEXMFSYSCONFIG /texlive/texmf-config
-TEXMFLOCAL /texlive/texmf-local
-TEXMFHOME $TEXMFLOCAL
-TEXMFVAR $TEXMFSYSVAR
-TEXMFCONFIG $TEXMFSYSCONFIG
-instopt_portable 1
-
-tlpdbopt_install_docfiles 0
-tlpdbopt_install_srcfiles 0
diff --git a/docs/Examples.md b/docs/Examples.md
index 1f14b73fd3..5816a4c5cc 100644
--- a/docs/Examples.md
+++ b/docs/Examples.md
@@ -3,14 +3,19 @@ title: Examples
id: examples
description: Examples of Ampersand programs and fragments
---
+
# Examples
+
This page is a collection of examples, meant for learning and explaining the language Ampersand.
-## Example: Client {#services-example-client}
-This example illustrates the structure of [services in Ampersand](./reference-material/The-language-Ampersand.md#Services)
+TODO: refactor this documentation to match the latest syntax.
+
+## Example: Client {#interfaces-example-client}
-### A Client service
+This example illustrates the structure of [interfaces in Ampersand](reference-material/syntax-of-ampersand#the-interface-statement)
-Suppose we have a delivery-hub that distributes orders over vendors and registers the subsequent deliveries. Let us define a service for clients, to allow clients to change their name and address and display their orders.
+### A Client interface
+
+Suppose we have a delivery-hub that distributes orders over vendors and registers the subsequent deliveries. Let us define an interface for clients, to allow clients to change their name and address and display their orders.
```text
INTERFACE ClientInfo FOR Client,Vendor : I[Client]
@@ -29,48 +34,48 @@ BOX [ "Name" : clientName
### Structure
-The service has a **header**, which is the first line in this example:
+The interface has a **header**, which is the first line in this example:
```text
INTERFACE ClientInfo FOR Client,Vendor : I[Client]
```
-The word `ClientInfo` is the **name** of this service. This name identifies the service , so it must be unique throughout the entire context.
+The word `ClientInfo` is the **name** of this interface. This name identifies the interface , so it must be unique throughout the entire context.
-This service is shown only to users with roles `Client` or `Vendor`. That is indicated by the restriction `FOR Client,Vendor`. Without that restriction, the service is available for every user in any role.
+This interface is shown only to users with roles `Client` or `Vendor`. That is indicated by the restriction `FOR Client,Vendor`. Without that restriction, the interface is available for every user in any role.
-The term to the right of the colon \(`:`\) symbol is called the **interface term**. A service is called from an atom which must be in the domain of this term. Let, for example, `Peter` be a `Client`. As `Peter` is an element of the domain of `I[Client]`, the service can be called from that atom.
+The term to the right of the colon \(`:`\) symbol is called the **interface term**. An interface is called from an atom which must be in the domain of this term. Let, for example, `Peter` be a `Client`. As `Peter` is an element of the domain of `I[Client]`, the interface can be called from that atom.
-The same term, `I[Client]`, is also used as **box term** for the box that follows the header. For every element in the codomain of the box term, a container \(in HTML: `<div>`\) will be drawn on the user screen. That box serves as a subinterface, which is called with precisely one atom. With `I[Client]` as box term, the codomain will contain just one atom, which is precisely the atom from which the service was called.
+The same term, `I[Client]`, is also used as **box term** for the box that follows the header. For every element in the codomain of the box term, a container \(in HTML: `<div>`\) will be drawn on the user screen. That box serves as a subinterface, which is called with precisely one atom. With `I[Client]` as box term, the codomain will contain just one atom, which is precisely the atom from which the interface was called.
In this example, the outermost box contains seven **box items** and the innermost box two. Each box item has a label and an term. For example the box item `"Name" : clientName` has `"Name"` as its label and `clientName` as term. The atom `a` from which the box was called is used to select the pairs \(`a`,`x`\) from the term. All `x`-es for which \(`a`,`x`\) is in `clientName` will be displayed. Supposing that the relation `clientName` associates only one name to a client, this specific box item displays just one name. However, in the fifth box item, the term `orderedBy~ - V; orderAccepted~` may contain an arbitrary number of orders to be accepted by provider, all of which are shown.
---
-description: 'TODO: This example is subject to bitrot. It has to be redone.'
----
-# Example: Login {#services-example-login}
+## description: 'TODO: This example is subject to bitrot. It has to be redone.'
+
+# Example: Login {#interfaces-example-login}
-This example defines a login/logout service,
+This example defines a login/logout interface,
because it is familiar. We show this example to demonstrate how to get different interface structures under varying conditions.
## Preliminaries
-The compiler uses templates to adapt an interface to specific needs regarding its HTML structure. Please read the [documentation of templates](https://github.com/AmpersandTarski/prototype/tree/master/templates) first for details.
+The compiler uses templates to adapt an interface to specific needs regarding its HTML structure. Please read the [documentation of templates](reference-material/syntax-of-ampersand#layout-of-user-interfaces) first for details.
To link system activities to a person or organisation, we use the notion of `Account`. To log in means to associate a session with the `Account` of the user. This association is made in the relation `sessionAccount`. To log out means to break that link, i.e. to remove the session/account pair from relation `sessionAccount`. When logging in, it is customary that the user identifies herself. In this example we do this with a `UserID` and `Password`.
A `UserId` is used to identify the user by a unique name. In this way, the \(system generated\) key of the user in the database is kept within the database.
-To make it more difficult to use an other person's `Account`, the system registers passwords. A `Password` is a string of characters known to the user only. For this reason, the login service must not expose the password while the user is typing it.
+To make it more difficult to use an other person's `Account`, the system registers passwords. A `Password` is a string of characters known to the user only. For this reason, the login interface must not expose the password while the user is typing it.
To isolate a data space for one specific user, we use the notion of session. A `SESSION` corresponds with the notion of session as used in browsers. Ampersand links the session called `'_SESSION'` to the current browser session, which results in the behaviour one would expect of a browser session.
-## How the service works
+## How the interface works
-A login service allows a user to log in and log out of the system. Here is what it looks like in a browser:
+A login interface allows a user to log in and log out of the system. Here is what it looks like in a browser:
-
+
Wonder what the 25al1rdkdfvmapkkqvuf5sroc5 means? Well this is the session number of the actual browser session. It is the value for which the atom
@@ -102,7 +107,7 @@ When you click the checkbox, you have logged out and will return to the first sc
## What the Ampersand code looks like
-To understand how it all works, let us discuss the code for this service:
+To understand how it all works, let us discuss the code for this interface:
```text
INTERFACE Login : '_SESSION'[SESSION] cRud BOX <HROWS>
@@ -119,7 +124,7 @@ INTERFACE Login : '_SESSION'[SESSION] cRud BOX <HROWS>
]
```
-If you analyse this code, notice the nested structure of `BOX`-es. The service is a box on the top level with two sub-boxes labeled `"Login"` and `"Logout"`.
+If you analyse this code, notice the nested structure of `BOX`-es. The interface is a box on the top level with two sub-boxes labeled `"Login"` and `"Logout"`.
The top-level box has `"_SESSION"[SESSION]` as its box-term. What you must remember is that the every atom of the codomain of that term causes one contain \(HTML: `<div>`\). In this example, the codomain of `"_SESSION"[SESSION]` is just one atom, which is the session identifier. That is shown in the title of the outmost box in the browser.
@@ -153,12 +158,13 @@ subbox remains empty. However, when logged in, the other subbox remains empty:
-## Example {#example-service-structure}
-To understand the structure of a service (keyword: `INTERFACE`), this section introduces a small example of a user interface, which shows the name, status, e-mail and co-workers of a person called "J. Lovell".
+## Example {#example-interface-structure}
-
+To understand the structure of an interface (keyword: `INTERFACE`), this section introduces a small example of a user interface, which shows the name, status, e-mail and co-workers of a person called "J. Lovell".
-The specification of this user interface is given in the following service definition:
+
+
+The specification of this user interface is given in the following interface definition:
```
INTERFACE Person : I[Person]
@@ -166,31 +172,33 @@ BOX
[ "Name" : personName
, "Status" : personStatus
, "Email" : personEmail
- , "Works with" : workswith
+ , "Works with" : workswith
]
```
To understand this fragment, take notice of:
-1. The name of this service is `Person`. This name immediately follows the keyword `INTERFACE`.
-2. The term following the colon, `I[Person]`, is the interface term of this service.
-3. The service can be applied to any atom from the _domain of the interface term_. So this particular service is applicable to any atom of type `Person`. In the screenshot, it applies to `"J. Lovell"`.
-4. The labels "Name", "Status", "Email", and "Works with" correspond to field names in the user interface.
+1. The name of this interface is `Person`. This name immediately follows the keyword `INTERFACE`.
+2. The term following the colon, `I[Person]`, is the interface term of this interface.
+3. The interface can be applied to any atom from the _domain of the interface term_. So this particular interface is applicable to any atom of type `Person`. In the screenshot, it applies to `"J. Lovell"`.
+4. The labels "Name", "Status", "Email", and "Works with" correspond to field names in the user interface.
5. Each term at the right of a field name specifies which data is presented in the field. For this reason it is called the _field term_ for that field. Field name and field term are separated by a colon.
6. Of all pairs `<"J. Lovell", x>` from the field term, the field displays the right atom `x`. A field term always works on one specific atom on the left, which is `"J. Lovell"` in this example.
-7. Field terms are subject to type checking. The following relations provide an example for getting a type-correct service:
+7. Field terms are subject to type checking. The following relations provide an example for getting a type-correct interface:
+
+ ```
+ RELATION personName :: Person * PersonName [UNI]
+ RELATION personStatus :: Person * PersonStatus [UNI]
+ RELATION personEmail :: Person * Email [UNI,TOT]
+ RELATION workswith :: Person * Person
+ ```
- ```
- RELATION personName :: Person * PersonName [UNI]
- RELATION personStatus :: Person * PersonStatus [UNI]
- RELATION personEmail :: Person * Email [UNI,TOT]
- RELATION workswith :: Person * Person
- ```
+ The source concepts of a field term must match the target concept of the interface term.
- The source concepts of a field term must match the target concept of the interface term.
8. Looking at the screenshot, we can tell that `"J. Lovell"` has one personName (which is `"J. Lovell"`), it has no personStatus, one personEmail and three persons to work with in `RELATION workswith`.
-## Example of a Service {#service-introductory-example}
+## Example of an interface {#interface-introductory-example}
+
```text
INTERFACE Overview : "_SESSION" cRud
BOX <TABS>
@@ -219,9 +227,9 @@ This example specifies three tabs. One shows students, one shows courses and one
Notice the following features:
-1. The structure of a service is hierarchical. It consists of boxes within a box. This is because a field term may be followed by a `BOX` with a list of subservices. Without it, it is just a field term.
-2. When a field term is followed by a `BOX`, every atom in the _codomain of the field term_ is displayed in a box of its own on the screen. That box behaves like a service with the field term serving as interface term of that subservice.
-3. By this mechanism, the hierarchical structure of the entire service translates directly to the hierarchical structure of the web-page in which it is displayed.
+
+1. The structure of an interface is hierarchical. It consists of boxes within a box. This is because a field term may be followed by a `BOX` with a list of subinterfaces. Without it, it is just a field term.
+2. When a field term is followed by a `BOX`, every atom in the _codomain of the field term_ is displayed in a box of its own on the screen. That box behaves like an interface with the field term serving as interface term of that subinterface.
+3. By this mechanism, the hierarchical structure of the entire interface translates directly to the hierarchical structure of the web-page in which it is displayed.
4. The source concept of a field term must match with the target concept of the field term outside the box.
5. The target concept of a field term that has a box, must match with the source concepts of each field inside that box.
-
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
deleted file mode 100755
index dfa9c823cc..0000000000
--- a/docs/SUMMARY.md
+++ /dev/null
@@ -1,84 +0,0 @@
----
-title: Table of contents (old style)
-id: toc
----
-
-# Table of contents (old style)
-
-:::tip
-
-We are currently refactoring our documentation. The navigation at the left is work in progress, and we are moving pages into it. For the time being, we have the old style index below. It will gradually be stripped, as pages move to the sidebar at the left.
-
-:::
-
-* [Introduction](ampersand/intro)
-* [Why Ampersand?](ampersand/landingpage/1-interested-visitor.md#whyAmpersand)
- * [The Business Rules Manifesto and Ampersand](ampersand/why-ampersand/BRManifestoAndAmpersand)
-* [Tutorial](ampersand/tutorial-rap4/)
-* [Reactive programming](ampersand/reactive-programming)
-* [New language documentation](./reference-material/The-language-Ampersand.md)
-* [Old language documentation (we're replacing it)](ampersand/the-language-ampersand/)
- * [How to read syntax statements](ampersand/the-language-ampersand/how-to-read-syntax-statements)
- * [Truth](ampersand/the-language-ampersand/truth)
- * [Atoms](ampersand/the-language-ampersand/atoms)
- * [Terms](ampersand/the-language-ampersand/terms/)
- * [Semantics](ampersand/the-language-ampersand/terms/semantics)
- * [Semantics in logic](ampersand/the-language-ampersand/terms/semantics#semantics-in-logic)
- * [Primitive terms](ampersand/the-language-ampersand/terms/semantics#primitive-terms-in-logic)
- * [Boolean operators](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-logic)
- * [Relational operators](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-logic)
- * [Residual operators](ampersand/the-language-ampersand/terms/semantics#residual-operators-in-logic)
- * [Semantics in natural language](ampersand/the-language-ampersand/terms/semantics#semantics-in-natural-language)
- * [Primitive terms in natural language](ampersand/the-language-ampersand/terms/semantics#primitive-terms-in-natural-language)
- * [Boolean operators in natural language](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-natural-language)
- * [Relational operators in natural language](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-natural-language)
- * [Residual operators in natural language](ampersand/the-language-ampersand/terms/semantics#residual-operators-in-natural-language)
- * [Semantics in set theory](ampersand/the-language-ampersand/terms/semantics#semantics-in-set-theory)
- * [Primitive terms in set theory](ampersand/the-language-ampersand/terms/semantics#semantics-in-set-theory)
- * [Boolean operators in set theory](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-set-theory)
- * [Relational operators in set theory](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-set-theory)
- * [Semantics of terms, defined algebraically](ampersand/the-language-ampersand/terms/semantics#semantics-in-relational-algebra)
- * [Boolean operators in algebra](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-algebra)
- * [Relational operators in algebra](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-algebra)
- * [Semantics visualized](ampersand/the-language-ampersand/terms/semantics#semantics-visualized)
- * [Boolean operators visualized](ampersand/the-language-ampersand/terms/semantics#boolean-operators-visualized)
- * [Relational operators visualized](ampersand/the-language-ampersand/terms/semantics#relational-operators-visualized)
- * [Residuals visualized](ampersand/the-language-ampersand/terms/semantics#residual-operators-visualized)
- * [Context](ampersand/the-language-ampersand/context)
- * [Syntactical Conventions](ampersand/the-language-ampersand/syntactical-conventions/)
- * [Language support](ampersand/the-language-ampersand/syntactical-conventions/language-support)
- * [Patterns](ampersand/the-language-ampersand/patterns)
- * [Language support](ampersand/the-language-ampersand/language-support)
- * [Current date](ampersand/the-language-ampersand/current-date)
- * [The Preprocessor](ampersand/the-language-ampersand/the-preprocessor)
- * [Design considerations](ampersand/the-language-ampersand/design-considerations)
-* [Running the Ampersand compiler](ampersand/the-command-line-tool)
-* [Architecture of an Ampersand Application](ampersand/architecture-of-an-ampersand-application/)
- * [Backend framework](ampersand/architecture-of-an-ampersand-application/backend-framework)
- * [Hooks](ampersand/architecture-of-an-ampersand-application/hooks)
- * [Extensions](ampersand/architecture-of-an-ampersand-application/extensions/)
- * [The ExecEngine](ampersand/architecture-of-an-ampersand-application/extensions/the-execengine)
-* [Deploying your Ampersand script](ampersand/docker/)
- * [Compiler](ampersand/docker/compiler)
- * [Deploy your own web application on your laptop](ampersand/docker/modelling-environment)
- * [Prototype multi-stage build](ampersand/docker/prototype-multi-stage-build)
- * [Prototype database](ampersand/docker/prototype-database)
-* [Reusing Available Modules](ampersand/reusing-available-modules)
-* [Best Practices](ampersand/the-language-ampersand/best-practices)
-* [Exercises](ampersand/exercises/)
- * [Delivery](ampersand/exercises/delivery)
- * [VOG (in Dutch)](ampersand/exercises/vog-in-dutch)
-* [Installing Ampersand](ampersand/installing-ampersand/)
- * [Deploying your Prototype](ampersand/installing-ampersand/deploying-your-prototype)
- * [Installing the tools manually](ampersand/installing-ampersand/installing-the-tools-manually)
-* [Modeling](ampersand/modeling/)
- * [Domain Driven Design](ampersand/modeling/conceptual-modeling)
- * [Data modeling](ampersand/modeling/data-modeling)
- * [Legal modeling](ampersand/modeling/legal-modeling)
- * [Architecture modeling](ampersand/modeling#architecture)
- * [Metamodeling](ampersand/modeling/metamodeling)
- * [Limitations of Ampersand](ampersand/modeling/limitations-of-ampersand)
-* [Configuring your application](ampersand/configuring-your-application)
-* [The Excel Importer](ampersand/the-excel-importer)
-* [Future plans](ampersand/future-plans)
-* [Research](ampersand/research)
diff --git a/docs/architecture-of-an-ampersand-application/README.md b/docs/architecture-of-an-ampersand-application/README.md
deleted file mode 100644
index 283968a1e1..0000000000
--- a/docs/architecture-of-an-ampersand-application/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Architecture of an Ampersand Application
-
-This chapter is intended for programmers who wish to know more about the software Ampersand generates. There can be many reasons, such as wanting to change the user experience, add or change functionality in views and/or controls, or simply to use the API of an Ampersand application. In this chapter you will find more details of the applications you generate.
-
-## Information systems
-
-In general, any information system has a structure like the one depicted below:
-
-
-
-An information system is meant to support users (e.g. Peter, Sally, Daisy). Differences among users can be handled by using roles (e.g. customerRep, sysMgr, MgmtSupporter). In this diagram, users are coloured to depict different roles.
-
-An information system consists of a number of services. We distinguish user facing services and non-user facing services. User facing services (e.g. register a client, sanitize case files, login) can be made available for a limited number of roles, giving each user access to precisely the services he or she is meant to see. In the diagram, user-facing services are colored corresponding to the roles they serve. Non-user facing services are not colored. Therefore, they are used exclusively by other software. Services can be either stateful or stateless. In the diagram, stateful services are drawn with a data container inside.
-
-Services communicate by means of streams or by means of remote calls.
-
-Currently, Ampersand generates correct information systems with one stateful service, which is the database. All other services are stateless and client-facing.
-
-
-
-An Ampersand information system is deployed as a whole. Therefore it qualifies as a "monolithic" system.
-
-.png>)
-
-## Infrastructural Architecture of an Ampersand application
-
-Let us look at a typical Ampersand Application called RAP, as an example:
-
-.png>)
-
-This example demonstrates how Ampersand applications function on the web. The application is deployed on a docker platform to facilitate frequent deployment anywhere in a robust manner and to isolate the internals from the outside world. Its structure has been defined statically (in docker-compose) to allow automated maintenance in production. The application itself is implemented as a statefree service, `rap4`. It uses a database service, `db`, for persistent storage. It is connected to the internet by a proxy which takes care of https and http traffic on ports 443 and 80 respectively. Two local networks separate data traffic to facilitate future work load balancing. The components `db`, `phpmyadmin`, and `proxy` are open source components which we have reused from the internet. The component `rap4` has been generated by Ampersand and has the structure shown in the following section.
-
-## Software Architecture of an Ampersand application
-
-Let us take a look at the structure of any system that Ampersand generates.
-
-
-
-The diagram shows an Ampersand framework (Ampersand FW, i.e. the green area), which is a database application that works as a stateful service. It ensures that all invariants are kept satisfied in production, as changes to the database are being made. So the integrity of the data is defined by the rules in the Ampersand script and perpetuously maintained in the back-end of the application.
-
-The framework is encapsulated by an application programming interface (API, the yellow area), which exports the functionality in a standardised way. Every application that interfaces through that API will therefore automatically preserve the integrity of data.
-
-On top of the API, the application comes with a front-end application (the blue area). This web-application has a conventional structure, based on the well-known [Model-View-Control (MVC) pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) used in many web-applications.
-
-The Ampersand compiler (the orange thing on the right) generates the application as a collection of HTML-pages (views) and JavaScript pages (controls), together with static code that is loaded from a framework. So the framework and the API are generic components, in which the semantics are "injected" as JSON files from the Ampersand compiler.
-
-The structure described above is reflected in the directory structure generated by Ampersand:
-
-.png>)
-
-So if you look in your directory, the generated application will look like this:
-
-
-
-The following figure shows the view-files to the left, the controller-files in the middle, and the services used by the controllers to the right.
-
-
diff --git a/docs/architecture-of-an-ampersand-application/backend-framework.md b/docs/architecture-of-an-ampersand-application/backend-framework.md
deleted file mode 100644
index ed2ee27fd2..0000000000
--- a/docs/architecture-of-an-ampersand-application/backend-framework.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Backend framework
-
-This chapter contains technical details about the backend framework.
-
diff --git a/docs/architecture-of-an-ampersand-application/extensions/README.md b/docs/architecture-of-an-ampersand-application/extensions/README.md
deleted file mode 100644
index 6470251a4b..0000000000
--- a/docs/architecture-of-an-ampersand-application/extensions/README.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Extensions
-
-The prototype has some built-in extensions. Some are experimental, others are pretty stable. This chapter describes them.
-
-The extensions are described from a user perspective. You may expect enough information to use the extension you want. If not, please notify the authors.
-
-The extensions are _NOT_ described from an implementors perspective. If you wish to change the extensions, you will need more information than is contained in this text. Please contact the authors for that purpose.
-
diff --git a/docs/architecture-of-an-ampersand-application/extensions/the-execengine.md b/docs/architecture-of-an-ampersand-application/extensions/the-execengine.md
deleted file mode 100644
index 3039f29e0f..0000000000
--- a/docs/architecture-of-an-ampersand-application/extensions/the-execengine.md
+++ /dev/null
@@ -1,241 +0,0 @@
-# The ExecEngine
-
-This chapter is meant for Ampersand users that want to build prototypes that automatically fix violations for specific rules. The idea behind this is quite simple: all it takes is another way of specifying violation texts. In practice, however, it takes some effort to learn how to do this correctly. Therefore, we only encourage you to do this if you are sufficiently motivated to spend this effort, i.e. if you are convinced it is worth your while.
-
-Before studying this chapter, make sure you know how to predict violations. You need to understand how Ampersand computes violations, given a certain population.
-
-## Automated rules
-
-Did you ever wonder how you can make your computer prevent rules from being violated? For that purpose, you must specify what your prototype will do the moment it signals a violation. This chapter tells you how.
-
-In essence, an Ampersand prototype is a database application that helps its users to keep rules satisfied. Keeping a rule satisfied happens in one of the following ways: 1. Your prototype imposes a rule. Violations are not tolerated. The prototype does not accept any change of data that violates the rule. As a result, the rule remains satisfied all the time. Such rules are called _invariants_. 2. Your prototype signals each violation to a designated role. The signal does not go away until the user has eliminated the violation. The rule is called _process rule_ because it prompts users to do some work. Notice that a violation of a process rule may persist. That is because it is meant to be resolved by persons rather than a computer. 3. Your prototype restores a violation the moment it occurs. It does so by means of a built-in robot, which we call the ExecEngine. Such rules are called _automated_. 4. The rule cannot be violated because of the way Ampersand is built. These rules are called _laws_. No effort is needed to maintain them, because they are always true.
-
-This chapter is about the third category: automated rules. The idea is to prevent violations by acting in time, to satisfy the violated rule. This is nice for your users, who have no concern with those violations.
-
-This chapter introduces automated rules by example. We will first create a rule, which a user must keep satisfied. We will then automate that process by adding instructions for the ExecEngine.
-
-### Learn by experimenting
-
-Most of the examples are taken from the demo script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/Examples/ProjectAdministration). You can compile and run this script, and reproduce several of the examples that follow.
-
-### Example \(`InsPair` and `DelPair`\)
-
-Consider the following example:
-
-```text
-RELATION pl[Project*Person] MEANING "A project can have project leaders."
-RELATION member[Project*Person] MEANING "A person can do actual work within a project."
-RELATION coworker[Person*Person] MEANING "Two people are co-workers in a project."
-```
-
-The following rule defines coworkers. Two different persons are coworker if they work in the same project. As a person can be either a project leader or a member, we get this rule:
-
-```text
-RULE coworker = (pl\/member)~;(pl\/member)-I
-```
-
-This rule basically says that `coworker` is shorthand for the much more complicated term `(pl\/member)~;(pl\/member)-I`. Quite useful indeed. Now suppose this rule is satisfied in the system. Then some manager assigns a new person, Harry, to the project Zeus-III. To administer that fact in the system, he adds a pair `("Zeus-III", "Harry")` to the relation `member`. Now there is a problem. The prototype will not accept this input, because our rule is violated. For all present workers in the project now have Harry as a new coworker. That should be administered in the relation `coworker` in order to satisfy the rule.
-
-One way to do that is to allow the manager to edit the relation coworker. This is not very convenient for that manager. He will be irritated, as he is forced to enter a number of pairs into the relation `coworker` that is equal to the number of persons in the project plus the number of projectleaders of that project. This rule is typically a candidate for automation.
-
-We have to consider that whenever a person is added to the project, that person must be added to `coworker` as well. But when a person is discharged from the project, that person must be removed from `coworker`. We can split the rule in two, knowing that `r=s` is always equivalent to both `r|-s` and `s|-r`.
-
-```text
-ROLE "ExecEngine" MAINTAINS r1
-RULE r1: (pl\/member)~;(pl\/member)-I |- coworker
-VIOLATION (TXT "InsPair;coworker;Person;", SRC I, TXT ";Person;", TGT I)
-
-ROLE "ExecEngine" MAINTAINS r2
-RULE r2: coworker |- (pl\/member)~;(pl\/member)-I
-VIOLATION (TXT "DelPair;coworker;Person;", SRC I, TXT ";Person;", TGT I)
-```
-
-Let us discuss both rules, starting with the first one. The `ROLE` statement assigns rule `r1` to the ExecEngine. The instruction for the ExecEngine is given in the `VIOLATION` string. It will be executed for each violation of rule `r1`.
-
-Elaborating on this example, just which violations will the ExecEngine resolve? Suppose the project has Alfred and Bob on the team before Harry is assigned. This means that the relation `coworker` contains `("Alfred", "Bob")` and `("Bob", "Alfred")` for starters. When the pair `("Zeus-III", "Harry")` is added to the relation `member`, we get the following violations: `("Alfred", "Harry")`, `("Harry", "Alfred")`, `("Bob", "Harry")`, and `("Harry", "Bob")`. So, the following instructions will be given to the ExecEngine:
-
-```text
-"InsPair;coworker;Person;Alfred;Person;Harry"
-"InsPair;coworker;Person;Harry;Person;Alfred"
-"InsPair;coworker;Person;Bob;Person;Harry"
-"InsPair;coworker;Person;Harry;Person;Bob"
-```
-
-Note that the violations of rule `r1` are precisely the pairs the ExecEngine must add to `coworker` to satisfy rule `r1`. The function `InsPair` is a predefined ExecEngine function, that adds to the population of a relation. The corresponding function `DelPair` removes pairs from the population of a relation. In the example, it is used to remove people from `coworker` that no longer share a project.
-
-**Notes**:
-
-* The examples use `SRC I` or `TGT I` to produce atoms that are to be inserted or deleted. However, `I` may be any term whose source concept is the same as that of the preceeding `SRC` or `TGT`.
-* The `SRC <term>` and `TGT <term>` is a set of pairs \(a,b\), where a is the source atom or target atom of the violation and b is a set of atoms that is the result of `<term>`. In the examples given, this set of atoms has cardinality 1 \(which is most often the case\). However, if it is empty, that is considered regular behaviour, and this will hence not result in an error. Also, if it has a cardinality > 1, then `InsPair` will insert them all whereas `DelPair` will produce an error.
-
-## Example \(`InsAtom`\) and \(`{EX}`\)
-
-Consider the following example:
-
-```text
-RELATION pl[Project*Person] MEANING "A project can have project leaders."
-RELATION project[Assignment*Project] [UNI,TOT] MEANING "Every Assignment must apply to one project"
-RELATION assignee[Assignment*Person] [UNI,TOT] MEANING "Every Assignment must apply to one person"
-```
-
-The following rule states that for every project leader, an assignment must exist that applies to one person and one project, basically assigning that person to be a project leader for the Project.
-
-```text
-RULE "Require Assignment" : pl |- project~;assignee
-```
-
-This calls for two different things: first, the automated creation of an atom in the concept `Assignment`, and second the consecutive population of relations `project` and `assignee` using this newly created atom.
-
-This is specified as follows:
-
-```text
-ROLE "ExecEngine" MAINTAINS "Create Assignment"
-RULE "Create Assignment" : pl |- project~;assignee
-VIOLATION (TXT "{EX} InsAtom;Assignment"
- ,TXT "{EX} InsPair;project;Assignment;_NEW;Project;", SRC I
- ,TXT "{EX} InsPair;assignee;Assignment;_NEW;Person;", TGT I
- )
-```
-
-First, note that we have three consecutive statements: an `InsAtom` command followed by two `InsPair`s. Using the phrase `{EX}` in front of each statement allows the interpreter of the violation texts to recognize each individual command and its arguments. In order to ensure that you do not forget about this, you may want to consider habituating yourself to _always_ use {EX} before any function.
-
-The first statement assigns the rule `Create Assignment` to the ExecEngine. The prototype will send all violations of this rule to the ExecEngine. The rule says that for every project with a project leader, there must be an assignment. Without that assignment, the rule is violated. The `VIOLATION` statement specifies that a new `Assignment` must be made for each violation. For that purpose, we use the predefined function `InsAtom`. This function takes a single argument, being the concept within which an atom has to be generated \(`Assignment` in the example\).
-
-The second statement calls the `InsPair` function in order to populate the relation `project`, in the manner we described above. Note that at the position where we want to specify the newly created Assignment atom, we use the phrase `_NEW`. The third statement calls the `InsPair` function in a similar fashion, and thus populates the relation `assignee`.
-
-Note that
-
-* in an `InsPair` \(or `DelPair`\), the source-atom or the target-atom \(or both\) can be the keyword `_NEW`.
-* the keyword `_NEW` refers to the last atom that was created by the \(last\) `InsAtom` statement that was executed in the violation.
-* when using `_NEW`, the corresponding concept \(obviously\) MUST be the same as the concept as specified in the `InsAtom` statement.
-
-Here is how it works. Suppose the pair `("Zeus-III", "Rhea")` is added to the relation `pl`, meaning that `Rhea` is being made a project leader of project `Zeus-III`. This produces a violation `("Zeus-III", "Rhea")` of the rule `Create Assignment`. The associated VIOLATION statement produces the text
-
-```text
- {EX} InsAtom;Assignment{EX} InsPair;project;Assignment;_New;Project;Zeus-III{EX} InsPair;assignee;Assignment;_NEW;Person;Rhea
-```
-
-which is passed to the ExecEngine, which splits the text in three statements
-
-```text
- InsAtom;Assignment
- InsPair;project;Assignment;_New;Project;Zeus-III
- InsPair;assignee;Assignment;_NEW;Person;Rhea
-```
-
-and subsequently executes them. Executing the `InsAtom` statement creates a new atom in concept `Assignment` \(let's say it is `Assignment_3495812395`. The keywords `_NEW` in the InsPair statements are then replaced by `Assignment_3495812395`, so that `("Assignment_3495812395", "Zeus-III")` is inserted into relation `project[Assignment*Project]`, and `("Assignment_3495812395", "Rhea")` is inserted into relation `assignee[Assignment*Person]`.
-
-## Example \(`DelAtom`\)
-
-In our example, whenever a project participant is discharged from his task, the corresponding Assignment needs to be deleted. We can do this by means of an automated rule:
-
-```text
-ROLE "ExecEngine" MAINTAINS "Delete Assignment"
-RULE "Delete Assignment" : project~;assignee |- pl\/member
-VIOLATION ( TXT "DelAtom;Assignment;", SRC I)
-```
-
-The function 'DelAtom' is predefined, and takes two arguments: 1. the concept from which an atom is to be deleted; 2. the actual atom to be deleted.
-
-Note that when an atom is deleted, also every pair \(in any relation\) is deleted if either its source atom or target atom is the deleted atom.
-
-## Example \(`_;`\)
-
-When you try to create or delete pairs with atoms that contain texts, you may find that some texts contain the semi-colon. When such a text is used in a violation statement, this will be interpreted as an argument separator, causing all sorts of unexpected results. This can be prevented by using `_;` rather than `;` as an argument separator. However, the ExecEngine must be made aware that this alternative argument separator is used. This is done by mentioning it immediately at the beginning of a function call, as in the below example:
-
-```text
-VIOLATION (TXT "{EX}_;InsPair_;r1_;A_;", SRC I, TXT "_;B_;", TGT I)
-```
-
-Of course, if the SRC or TGT atom is a text that contains the characters `_;`, the problem still remains...
-
-## Example \(`TransitiveClosure`\)
-
-Consider the `r :: A * A [IRF,ASY]`. In relation algebra, terms such as `r+` or `r*` are allowed, designating the transitive closure of `r`. The `+` and `*` operators are currently not supported in Ampersand.
-
-This section describes a workaround that allows you to use transitive closures.To do so, we simply define a relation `rPlus :: A * A` and/or `rStar :: A * A`, and define the following automated rules to populate these relations:
-
-```text
- ROLE ExecEngine MAINTAINS "Grow rPlus"
- RULE "Grow rPlus": r;rPlus \/ rPlus;r |- rPlus
- VIOLATION (TXT "{EX} InsPair;rPlus;A;", SRC I, TXT ";A;", TGT I)
-
- ROLE ExecEngine MAINTAINS "Shrink rPlus"
- RULE "Shrink rPlus": rPlus |- r;rPlus \/ rPlus;r
- VIOLATION (TXT "{EX} DelPair;rPlus;A;", SRC I, TXT ";A;", TGT I)
-
- ROLE ExecEngine MAINTAINS "Grow rStar"
- RULE "Grow rStar": r \/ r;rStar \/ rStar;r |- rStar
- VIOLATION (TXT "{EX} InsPair;rStar;A;", SRC I, TXT ";A;", TGT I)
-
- ROLE ExecEngine MAINTAINS "Shrink rStar"
- RULE "Shrink rStar": rStar |- r \/ r;rStar \/ rStar;r
- VIOLATION (TXT "{EX} DelPair;rStar;A;", SRC I, TXT ";A;", TGT I)
-```
-
-While this works \(certainly in theory\), a practical issue is that it quickly becomes very timeconsuming as the population of `r` grows, up to an unacceptable level. Also, Ampersand prototypes have a time limit \(30 or 60 seconds\) for an ExecEngine run. In order to make transitive closures a bit more practicable \(but certainly not workable for 'real' software\), we can use the predefined ExecEngine function `TransitiveClosure`, as follows:
-
-```text
- rCopy :: A * A
- MEANING "a copy of the relation `r`, needed to detect deletions in `r`"
-
- rPlus :: A * A
- ROLE ExecEngine MAINTAINS "Warshall on r"
- RULE "Warshall on r": rCopy = r
- VIOLATION (TXT "{EX} TransitiveClosure;r;A;rCopy;rPlus")
-```
-
-What this does is the following. Any time that `r` is being \(de\)populated, the rule `Warshall on r` is violated. This calls the \(predefined\) function `TransitiveClosure` with its four arguments, the result of which is that 1. the relation `rPlus` is computed as the \(smallest\) transitive closure of `r` \(using the Warshall algorithm\); 2. the relation `rCopy` is made to have the same population as `r`, thereby resolving all violations of the rule.
-
-Note that if you want to use \(the equivalent of\) `r*` somewhere in an term, the most practical way is to use the term `(I \/ rPlus)` at that spot.
-
-### HELP! I got errors!
-
-As an Ampersand user, you are used to getting error messages from the compiler. Yet, errors in rules for the Exec-engine are not signalled by the compiler. Instead, you get runtime error message that some inexperienced users find hard to work with, as it requires some knowledge of the backgrounds.
-
-Here are some tips. 1. Most \(all?\) predefined functions check for a valid number of arguments. If the error message relates to the number of arguments, 1. you have missed out on a `;`. The function `NewStruct` is well-known to produce this error, because of the wealth of arguments allowed. Learning and maintaining a strict discipline regarding how you write such \(e.g. `NewStruct`\) statements is a big help in preventing this error from occurring. 2. you may have to many `;`s. Of course, you may just mistakenly having written too many `;`s. Another, less known cause is where a violation occurs on an atom that happens to be a text containing one or more `;` characters. This will cause the ExecEngine to interpret the text as multiple arguments, which \(usually\) results in an illegal number of arguments error. The cure is to use the `_;` separator rather than the `;` separator \(see the appropriate section above\). 2. Most \(all?\) predefined functions that have arguments to specify a relation definition, will check \(at runtime\) whether or not this relation is actually defined \(at define-time\). Misspellings in relation or concept names \(e.g. capitalizations\) often cause this error. 3. You should specify a relation just with its name, e.g. `project` \(not: `project[Assignment*Project]`\). The reason for this is that it \(currently\) is the ExecEngine itself that parses the violation string \(rather than the Ampersand compiler\). This very simple parser does not handle `[Assignment*Project]`-like constructs. 4. For the same reason \(simple ExecEngine parser\), there is no type checking for the ExecEngine functions. This means that you must check yourself whether or not the type of atom\(s\) you want to insert or delete match with the source or target atom of the relation you try to \(de\)populate. 5. Look at the log window to get more information on what is actually happening when the ExecEngine executes. You can turn it on by clicking on the left-most icon of the icon-list that is at the right hand side in the menu bar. There, you turn on the 'Show log window'. In the log window, you can select what you do and do not see. Options you may want to select include 'ExecEngine', 'RuleEngine' and 'Database'. 6. If everything else fails, read the error messages and log lines slowly and carefully, as they \(sometimes unexpectedly\) do provide information that may actually help you to resolve the issue at hand.
-
-For the time that researchers are working on this problem, you will have to live with all this. It makes programming of automated rules initially error-prone and time consuming, but when you get the hang of it, it gets better. Still, the best piece of advice we can currently give here is:
-
-* Keep automated rules simple.
-* Test thoroughly.
-
-### Ways to run the ExecEngine \(one or more times\)
-
-The ExecEngine currently is a simple one. Whenever it executes, it evaluates the automated rules one after another. Whenever an automated rule produces violations, the associated violation text is executed for every such violation.
-
-While rules are most often evaluated in the order in which they are defined, you really should not make any assumptions about the evaluation order \(nor about the order in which violations of a rule are processed\). Hence, it may happen that the violations are processed 'out of order', resulting in violations of automated rules that could 'easily' have been fixed.
-
-To overcome this issue, the ExecEngine \(by default\) simply runs itself again, until all automated rules have no violations any more, or until the maximum amount of such reruns has been reached - this limit is set to guarantee that execution terminates. The default number of maximum reruns is 10 \(decimal\). You can modify this setting in `LocalSettings.php`, , by \(including and/or\) modifying the following texts:
-
-```text
- Config::set('maxRunCount', 'execEngine', 10);
-```
-
-For research or debugging purposes, it may sometimes be neccesary to have further control over the manner in which the ExecEngine does. There are three possibilities for running the ExecEngine:
-
-1. Automatically. This is the default behaviour. Turning the autoRerun feature off means that the ExecEngine will always run only once when called. You can specify this in the file `LocalSettings.php`, by replacing the text `true` by `false` in the line that contains the text:
-
- `Config::set('autoRerun', 'execEngine', true);`
-
-2. Manually. This is when you, as a user, clik on the `refresh/reset options` icon in a prototype, and the select `Run execution engine`. Note that if you also use logins, you must have been assigned a role that allows you to do this, or you won't see this option.
-3. By using the ExecEngine function `RerunExecEngine`, which takes one argument \(an explanatory text, that is used for logging - see the example below\). Whenever the ExecEngine calls this function, a flag is set requesting a rerun. When, at the end of an ExecEngine run, this flag is set, the ExecEngine will run itself again.
-
-Here is an example of how `RerunExecEngine` can be used to create a transitive closure:
-
-```text
- r :: A * A [ASY]
- rStar :: A * A -- This will contain a transitive closure
-
- ROLE ExecEngine MAINTAINS "InsPair on rStar"
- RULE "InsPair on rStar": r \/ r;rStar \/ rStar;r |- rStar
- VIOLATION (TXT "{EX} InsPair;rStar;A;", SRC I, TXT ";A;", TGT I
- ,TXT "{EX} RerunExecEngine;InsPair on rStar"
- )
- ROLE ExecEngine MAINTAINS "DelPair on rStar"
- RULE "DelPair on rStar": rStar |- r \/ r;rStar \/ rStar;r
- VIOLATION (TXT "{EX} DelPair;rStar;A;", SRC I, TXT ";A;", TGT I
- ,TXT "{EX} RerunExecEngine;DelPair on rStar"
- )
-```
-
diff --git a/docs/architecture-of-an-ampersand-application/hooks.md b/docs/architecture-of-an-ampersand-application/hooks.md
deleted file mode 100644
index 22fae9faaf..0000000000
--- a/docs/architecture-of-an-ampersand-application/hooks.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Hooks
-
-Hookpoint use the following naming convention:
-
-* camelCasing
-* start with _pre_ or _post_ to define if hooks are called before or after the following position
-* specify classname or file where hookpoint is positioned
-* specify functionname where hookpoint is positioned
-* optionally specify postion within function where hookpoint is positioned
-
-Current list of hookpoints:
-
-| Hookpoint | Extensions that use it |
-| :--- | :--- |
-| postDatabaseReinstallDB | ExecEngine |
-| postDatabaseUpdate | Mutation \(experimental\), Mqtt \(experimental\) |
-| postDatabaseInsert | Mutation \(experimental\), Mqtt \(experimental\) |
-| postDatabaseDelete | Mutation \(experimental\), Mqtt \(experimental\) |
-| preDatabaseCloseTransaction | ExecEngine |
-| | postDatabaseCloseTransaction |
-| postDatabaseAddAtomToConceptInsert | Mqtt \(experimental\) |
-| | postDatabaseAddAtomToConceptSkip |
-| postDatabaseDeleteAtom | Mqtt \(experimental\) |
-| | postDatabaseStartTransaction |
-| postDatabaseCommitTransaction | Mqtt \(experimental\) |
-| | postDatabaseRollbackTransaction |
-
-More hookpoints will be defined when needed.
-
diff --git a/docs/Figures/InterfaceAlphaBoardFormatted.jpg b/docs/assets/InterfaceAlphaBoardFormatted.jpg
similarity index 100%
rename from docs/Figures/InterfaceAlphaBoardFormatted.jpg
rename to docs/assets/InterfaceAlphaBoardFormatted.jpg
diff --git a/docs/assets/InterfaceAlphaBoardNested.jpg b/docs/assets/InterfaceAlphaBoardNested.jpg
new file mode 100644
index 0000000000..d95b3e3cee
Binary files /dev/null and b/docs/assets/InterfaceAlphaBoardNested.jpg differ
diff --git a/docs/Figures/InterfaceAlphaBoardNestedCRUD.jpg b/docs/assets/InterfaceAlphaBoardNestedCRUD.jpg
similarity index 100%
rename from docs/Figures/InterfaceAlphaBoardNestedCRUD.jpg
rename to docs/assets/InterfaceAlphaBoardNestedCRUD.jpg
diff --git a/docs/Figures/InterfaceLovellEditable.jpg b/docs/assets/InterfaceLovellEditable.jpg
similarity index 100%
rename from docs/Figures/InterfaceLovellEditable.jpg
rename to docs/assets/InterfaceLovellEditable.jpg
diff --git a/docs/Figures/InterfaceLovellRaw.jpg b/docs/assets/InterfaceLovellRaw.jpg
similarity index 100%
rename from docs/Figures/InterfaceLovellRaw.jpg
rename to docs/assets/InterfaceLovellRaw.jpg
diff --git a/docs/Figures/InterfaceLovellTabsCRUD.png b/docs/assets/InterfaceLovellTabsCRUD.png
similarity index 100%
rename from docs/Figures/InterfaceLovellTabsCRUD.png
rename to docs/assets/InterfaceLovellTabsCRUD.png
diff --git a/docs/assets/Untitled Diagram (2).png b/docs/assets/Untitled Diagram (2).png
deleted file mode 100644
index df889b8102..0000000000
Binary files a/docs/assets/Untitled Diagram (2).png and /dev/null differ
diff --git a/docs/assets/Untitled Diagram (4).png b/docs/assets/Untitled Diagram (4).png
deleted file mode 100644
index cafa54ab52..0000000000
Binary files a/docs/assets/Untitled Diagram (4).png and /dev/null differ
diff --git a/docs/assets/Untitled Diagram (5).png b/docs/assets/Untitled Diagram (5).png
deleted file mode 100644
index 3e68dc5dc0..0000000000
Binary files a/docs/assets/Untitled Diagram (5).png and /dev/null differ
diff --git a/docs/assets/Untitled Diagram (6).png b/docs/assets/Untitled Diagram (6).png
deleted file mode 100644
index 48f885a825..0000000000
Binary files a/docs/assets/Untitled Diagram (6).png and /dev/null differ
diff --git a/docs/assets/Untitled Diagram (8).png b/docs/assets/Untitled Diagram (8).png
deleted file mode 100644
index 2c726e6dfe..0000000000
Binary files a/docs/assets/Untitled Diagram (8).png and /dev/null differ
diff --git a/docs/assets/views_controllers_services.png b/docs/assets/views_controllers_interfaces.png
similarity index 100%
rename from docs/assets/views_controllers_services.png
rename to docs/assets/views_controllers_interfaces.png
diff --git a/docs/conceptual/automated-rules.md b/docs/conceptual/automated-rules.md
index f02271b62a..0ae229aaea 100644
--- a/docs/conceptual/automated-rules.md
+++ b/docs/conceptual/automated-rules.md
@@ -79,7 +79,8 @@ PATTERN "Demo of Sequences"
ENDPATTERN
INTERFACE overview(insSeq, seq, seqHead, madeIn) : '_SESSION'
-ROWS[ "Name your new sequence here:" : insSeq
+BOX<TABLE>
+ [ "Name your new sequence here:" : insSeq
, Sequences : V[SESSION*Sequence]
BOX <TABLE>
[ sequence : name
@@ -98,7 +99,7 @@ ROWS[ "Name your new sequence here:" : insSeq
ENDCONTEXT
~~~~~~~~
-The Ampersand-compiler can translate binary relations together with multiplicity restrictions into the data model of a MySQL-database. Relation algebra terms are used in rules and services. Rules are constraints on the data stored in the relations. Each service is a “window” on the data set, in which data to be displayed is described in terms of relation algebra terms. The example in Figure 1 is reasonably small: it contains 8 relations with 13 multiplicity restrictions, 6 rules, and one service. Every rule in Ampersand is a constraint, but the enforcement of constraints by the software can be one of the following options:
+The Ampersand-compiler can translate binary relations together with multiplicity restrictions into the data model of a MySQL-database. Relation algebra terms are used in rules and interfaces. Rules are constraints on the data stored in the relations. Each interface is a “window” on the data set, in which data to be displayed is described in terms of relation algebra terms. The example in Figure 1 is reasonably small: it contains 8 relations with 13 multiplicity restrictions, 6 rules, and one interface. Every rule in Ampersand is a constraint, but the enforcement of constraints by the software can be one of the following options:
1. A rule has to be satisfied at all times. Such rules are called invariants. When violated, the system produces an error message and blocks the transaction in which the violation has occurred.
diff --git a/docs/conceptual/theory.md b/docs/conceptual/theory.md
index 86cdef0d30..b1b916dccb 100644
--- a/docs/conceptual/theory.md
+++ b/docs/conceptual/theory.md
@@ -14,16 +14,16 @@ Information systems are typically used by actors (both users and
computers) who are distributed and work with data all the time. As a
consequence, the data in a system changes continually. In practice,
actors "talk to" the system through an ingress mechanism, which connects
-each user to the right service(s). The ingress function is provided by
+each user to the right interface(s). The ingress function is provided by
the deployment platform, so it is beyond the scope of this paper. Also,
-every service runs independent of other services, meaning that each
-service can be stopped, (re)started and substituted without disrupting
-the other services.
+every interface runs independent of other interfaces, meaning that each
+interface can be stopped, (re)started and substituted without disrupting
+the other interfaces.
Every system contains a dataset, which represents the state of the
-system. Every service produces and consumes events that may change the
+system. Every interface produces and consumes events that may change the
state of the system. This state is represented in a persistent store,
-aka the database [^3]. Events that the system detects may cause the
+aka the database. Events that the system detects may cause the
state to change.
@@ -37,7 +37,7 @@ database management systems refer to as integrity rules. The purpose of
integrity rules is to keep the constraints they represent satisfied.
-An *information system* is a combination of dataset, schema, and functionality. Each is defined in a separate section.
+An [information system](#information-systems-sctinformation-systems) is a combination of dataset, schema, and functionality. Each is defined in a separate section.
## Datasets {#sct:Datasets}
@@ -203,7 +203,7 @@ As before, a suffix disambiguates the elements of this definition when needed.
*An information system $\mathscr{S}$ is a tuple
$\langle\mathscr{D},\mathscr{Z},\mathcal{O},\text{\it maint}\rangle$,
-in which*
+in which:*
- *dataset
$\mathscr{D}=\langle{\mathcal{T}},{\text{\it inst}}\rangle$ as
@@ -254,10 +254,10 @@ role(s) that are administered in $\text{\it maint}$ to do something
about it.
Automatic enforcement is specified by the developer with a special
-syntax, the *enforce rule*. An enforce rule specifies not only the rule,
+syntax, the *enforcement rule*. An enforcement rule specifies not only the rule,
but also the way to restore invariance. The system features an engine
-that restores invariance of all enforce rules without unneccessary
-delay. Whenever the dataset violates an enforce rule, this engine will
+that restores invariance of all enforcement rules without unneccessary
+delay. Whenever the dataset violates an enforcement rule, this engine will
make other changes to the dataset to satisfy that rule. Hence, the rule
is not satisfied during a small, finite amount of time.
@@ -352,7 +352,7 @@ so this is a dataset $\mathscr{D}$ as
introduced before.
The Ampersand compiler generates a schema $\mathscr{Z}$, which contains
-concepts, relations, and rules. It defines the set of concepts:
+concepts, relations and rules. It defines the set of concepts:
$\mathcal{C}=\{ {\tt Module}, {\tt Course}, {\tt Student}\}$
@@ -389,9 +389,9 @@ The following table compares the language used in the world of information syste
| rules | script | program | theory |
| data | population | state | model |
| formal statement | term | condition | term |
-| generator | generator | compiler |
-| store | database | database |
-| service | service | service |
+| generator | generator | compiler | |
+| store | database | database | |
+| interface | interface | interface | |
The following theoretical topics are relevant for Ampersand.
diff --git a/docs/docker/README.md b/docs/docker/README.md
index a3b3f1e39a..eeee543d3d 100644
--- a/docs/docker/README.md
+++ b/docs/docker/README.md
@@ -24,7 +24,7 @@ Ampersand uses the following container images:
4. **[ampersandtarski/ampersand-rap](https://hub.docker.com/r/ampersandtarski/ampersand-rap)**
This image features the RAP development system, which compiles Ampersand scripts into prototypes and documentation.
RAP is a tool that lets you analyze Ampersand models, generate functional specifications, and make prototypes of information systems.
- It is the primary tool for students at the [Open University of the Netherlands](www.ou.nl) in the course [Rule Based Design](https://www.ou.nl/-/IM0403_Rule-Based-Design).
+ It is the primary tool for students at the [Open University of the Netherlands](https://www.ou.nl) in the course [Rule Based Design](https://www.ou.nl/-/IM0403_Rule-Based-Design).
This image is used by the [docker-compose.yml file](https://github.com/AmpersandTarski/RAP/blob/master/docker-compose.yml) that configures the RAP system to deploy RAP.
5. **[mariadb:10.4](https://hub.docker.com/_/mariadb)**
This image features the MariaDB database management system.
diff --git a/docs/exercises/delivery.md b/docs/exercises.md
similarity index 58%
rename from docs/exercises/delivery.md
rename to docs/exercises.md
index 3e2bcb2d84..1c5fa6682e 100644
--- a/docs/exercises/delivery.md
+++ b/docs/exercises.md
@@ -1,4 +1,16 @@
-# Delivery
+---
+description: Under construction
+---
+
+# Exercises
+
+This chapter contains material to help you mature your skills in Ampersand. They are somewhat larger than the exercises that are embedded in the theory. That makes these exercises suitable for classroom projects.
+
+There may be exercises in another language than English, usually for a good reason.
+
+The [VOG \(Verklaring Omtrent Gedrag\)](#VOG). This exercise requires you to read pieces of Dutch legislation, so this exercise is in Dutch.
+
+## Delivery
Consider the following script. You can compile and run it op een RAP server.
@@ -208,12 +220,48 @@ BOX [ "Client" : orderedBy
ENDCONTEXT
```
-## Assignment
+### Assignment
This script contains a `RULE` called `orderInAssortment`. By editing fields you can add orders, clients, providers, etc. Find out what `RULE orderInAssortment` means by trying to violate that rule. Why does this rule exist? Describe the meaning and the purpose of this rule. It may help to play with the prototype and discussing this rule with your peers. Add your meaning and purpose to the script and make sure it compiles and runs.
-## What have you learned?
+### What have you learned?
1. By playing with the prototype, you have learned the meaning of `RULE orderInAssortment`.
-2. You have learned how to include a purpose and a meaning with a rule. Remember that you can add a purpose not just for any rule, but for relations, concepts, services and contexts as well.
+2. You have learned how to include a purpose and a meaning with a rule. Remember that you can add a purpose not just for any rule, but for relations, concepts, interfaces and contexts as well.
+
+
+## VOG \(in Dutch\)
+
+In this assignment you will practice the analysis of a legal procedure by using Ampersand. Since the legal procedure used here is in Dutch, this assignment is only given in the Dutch language. The purpose of this assignment is to practice the use of Ampersand in a real-life situation. Before the assignment, your tutor will explain the way of working for this type of analysis. During the assignment, your tutor will occasionally explain features of Ampersand that you might need.
+
+In deze opdracht oefent u met het analyseren van wet- en regelgeving. Dit is een typerend voorbeeld voor de manier waarop Ampersand in de praktijk kan worden gebruikt. Het resultaat van deze opdracht is een conceptuele analyse van het proces van aanvragen en verstrekken van de Verklaring Omtrent Gedrag \(VOG\).
+
+De Verklaring Omtrent Gedrag - ten onrechte door sommigen "verklaring van goed gedrag" genoemd - is het onderwerp van deze casus. Wat de VOG voor burgers betekent beantwoordt overheidsdienst "Justis" in haar [voorlichting op internet](https://www.justis.nl/producten/vog/faq/faq-over-vog-np/). De formele regels hierover staan in de wet en regelgeving, zoals ontsloten op wetten.nl. [Paragraaf 1 van de Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949¶graaf=1) leidt dit onderwerp in:
+
+> Het Centraal Orgaan Verklaring Omtrent het Gedrag \(COVOG\) geeft op grond van de [Wet justitiële en strafvorderlijke gegevens](http://wetten.overheid.nl/jci1.3:c:BWBR0014194&g=2017-04-25&z=2017-04-25) \(Wjsg\) namens de Minister van Veiligheid en Justitie verklaringen omtrent het gedrag \(VOG\) af aan natuurlijke personen \(VOG-NP\) en rechtspersonen \(VOG-RP\).
+>
+> Bij een VOG-aanvraag wordt onderzoek gedaan naar het justitiële verleden van een natuurlijke persoon of een rechtspersoon en zijn bestuurders, vennoten, maten of beheerders. Daarbij wordt het belang van de aanvrager afgewogen tegen het risico voor de samenleving in het licht van het doel van de aanvraag. Naar aanleiding hiervan wordt verklaard of al dan niet is gebleken van bezwaren tegen die natuurlijke persoon of rechtspersoon en wordt de VOG geweigerd respectievelijk verstrekt.
+
+In deze casus wordt in tweetallen gewerkt. Je maakt een Ampersand-script die de regels rond het aanvragen en afgeven van de VOG weergeven.
+
+Scope 1: de administratieve afhandeling. Dit betreft hetgeen beschreven is in [paragraaf 4 van de Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949¶graaf=4). We beperken ons tot de elektronische procedure voor natuurlijke personen.
+
+Scope 2: beoordeling van de aanvraag. Dit betreft hetgeen beschreven is in [paragraaf 3 van de Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949¶graaf=3). We beperken ons tot aanvragen van natuurlijke personen.
+
+### Opdracht
+
+Bestudeer \(voor zover relevant en voor zover de tijd het toelaat\) de wettelijke bronnen en verwerk deze in een Ampersand-script. Dit werkstuk kun je te zijner tijd laten uitgroeien tot een volwaardig prototype voor een systeem dat VOG-aanvragen registreert en afhandelt.
+
+### Beoordeling
+
+Indien de docent deze opdracht beoordeelt, zullen de volgende criteria worden toegepast:
+1. Is het ingeleverde conceptueel model compileerbaar in Ampersand?
+2. Zijn er concepten, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag noodzakelijk zijn en die niet in het script aanwezig zijn?
+3. Zijn er relaties, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag noodzakelijk zijn en die niet in het script aanwezig zijn?
+4. Zijn er concepten in het script aanwezig, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag overbodig zijn?
+5. Zijn er relaties in het script aanwezig, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag overbodig zijn?
+6. Zijn er regels in [Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949), die niet in het conceptuele model voorkomen?
+7. Zijn er regels, die niet traceerbaar zijn naar een regel in [Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949)
+8. Is van elke relatie en van elke regel de betekenis vastgelegd in een `MEANING`?
+9. Is van elke relatie en van elke regel vastgelegd waartoe hij bestaat, d.m.v. een `PURPOSE`?
diff --git a/docs/exercises/README.md b/docs/exercises/README.md
deleted file mode 100644
index af2026742b..0000000000
--- a/docs/exercises/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-description: Under construction
----
-
-# Exercises
-
-This chapter contains material to help you mature your skills in Ampersand. They are somewhat larger than the exercises that are embedded in the theory. That makes these exercises suitable for classroom projects.
-
-There may be exercises in another language than English, usually for a good reason.
-
-Currently, there is only one exercise, the [VOG \(Verklaring Omtrent Gedrag\)](./vog-in-dutch). This exercise requires you to read pieces of Dutch legislation, so this exercise is in Dutch.
-
diff --git a/docs/exercises/vog-in-dutch.md b/docs/exercises/vog-in-dutch.md
deleted file mode 100644
index 9ff2307c0c..0000000000
--- a/docs/exercises/vog-in-dutch.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# VOG \(in Dutch\)
-
-In this assignment you will practice the analysis of a legal procedure by using Ampersand. Since the legal procedure used here is in Dutch, this assignment is only given in the Dutch language. The purpose of this assignment is to practice the use of Ampersand in a real-life situation. Before the assignment, your tutor will explain the way of working for this type of analysis. During the assignment, your tutor will occasionally explain features of Ampersand that you might need.
-
-In deze opdracht oefent u met het analyseren van wet- en regelgeving. Dit is een typerend voorbeeld voor de manier waarop Ampersand in de praktijk kan worden gebruikt. Het resultaat van deze opdracht is een conceptuele analyse van het proces van aanvragen en verstrekken van de Verklaring Omtrent Gedrag \(VOG\).
-
-De Verklaring Omtrent Gedrag - ten onrechte door sommigen "verklaring van goed gedrag" genoemd - is het onderwerp van deze casus. Wat de VOG voor burgers betekent beantwoordt overheidsdienst "Justis" in haar [voorlichting op internet](https://www.justis.nl/producten/vog/faq/faq-over-vog-np/). De formele regels hierover staan in de wet en regelgeving, zoals ontsloten op wetten.nl. [Paragraaf 1 van de Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949¶graaf=1) leidt dit onderwerp in:
-
-> Het Centraal Orgaan Verklaring Omtrent het Gedrag \(COVOG\) geeft op grond van de [Wet justitiële en strafvorderlijke gegevens](http://wetten.overheid.nl/jci1.3:c:BWBR0014194&g=2017-04-25&z=2017-04-25) \(Wjsg\) namens de Minister van Veiligheid en Justitie verklaringen omtrent het gedrag \(VOG\) af aan natuurlijke personen \(VOG-NP\) en rechtspersonen \(VOG-RP\).
->
-> Bij een VOG-aanvraag wordt onderzoek gedaan naar het justitiële verleden van een natuurlijke persoon of een rechtspersoon en zijn bestuurders, vennoten, maten of beheerders. Daarbij wordt het belang van de aanvrager afgewogen tegen het risico voor de samenleving in het licht van het doel van de aanvraag. Naar aanleiding hiervan wordt verklaard of al dan niet is gebleken van bezwaren tegen die natuurlijke persoon of rechtspersoon en wordt de VOG geweigerd respectievelijk verstrekt.
-
-In deze casus wordt in tweetallen gewerkt. Je maakt een Ampersand-script die de regels rond het aanvragen en afgeven van de VOG weergeven.
-
-Scope 1: de administratieve afhandeling. Dit betreft hetgeen beschreven is in [paragraaf 4 van de Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949¶graaf=4). We beperken ons tot de elektronische procedure voor natuurlijke personen.
-
-Scope 2: beoordeling van de aanvraag. Dit betreft hetgeen beschreven is in [paragraaf 3 van de Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949¶graaf=3). We beperken ons tot aanvragen van natuurlijke personen.
-
-## Opdracht
-
-Bestudeer \(voor zover relevant en voor zover de tijd het toelaat\) de wettelijke bronnen en verwerk deze in een Ampersand-script. Dit werkstuk kun je te zijner tijd laten uitgroeien tot een volwaardig prototype voor een systeem dat VOG-aanvragen registreert en afhandelt.
-
-## Beoordeling
-
-Indien de docent deze opdracht beoordeelt, zullen de volgende criteria worden toegepast:
-
-1. Is het ingeleverde conceptueel model compileerbaar in Ampersand?
-2. Zijn er concepten, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag noodzakelijk zijn en die niet in het script aanwezig zijn?
-3. Zijn er relaties, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag noodzakelijk zijn en die niet in het script aanwezig zijn?
-4. Zijn er concepten in het script aanwezig, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag overbodig zijn?
-5. Zijn er relaties in het script aanwezig, die in een adminstratie voor het uitreiken van verklaringen omtrent gedrag overbodig zijn?
-6. Zijn er regels in [Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949), die niet in het conceptuele model voorkomen?
-7. Zijn er regels, die niet traceerbaar zijn naar een regel in [Beleidsregels VOG-NP-RP 2013](http://wetten.overheid.nl/jci1.3:c:BWBR0032949)
-8. Is van elke relatie en van elke regel de betekenis vastgelegd in een `MEANING`?
-9. Is van elke relatie en van elke regel vastgelegd waartoe hij bestaat, d.m.v. een `PURPOSE`?
-
diff --git a/docs/future-plans.md b/docs/future-plans.md
index c62207f2bc..08ab7d76ac 100644
--- a/docs/future-plans.md
+++ b/docs/future-plans.md
@@ -23,7 +23,7 @@ One purpose of Ampersand is to generate a web-application. Currently, the genera
-The architecture is explained in more detail in [this chapter](./architecture-of-an-ampersand-application/).
+The architecture is explained in more detail in [this chapter](./reference-material/architecture-of-an-ampersand-application).
## NoSQL storage
@@ -51,7 +51,7 @@ This communication will be greatly simplified if Open API documentation can be g
### Purpose
To take an API in production, it needs to be documented. For this purpose we want to generate Open API documentation.
-.png>)
+
@@ -68,7 +68,7 @@ Ampersand and semantic web technologies have much in common. To explore this top
To generate reactive web-applications instead of a classical object-oriented web-application is why we want to refactor the Ampersand front-end.
The current front-end is based on the Angular-JS framework. To enter the world of reactive programming, we want to refactor the front-end.
-.png>)
+
This issue is currently underway, sponsored in kind by Ordina. We expect the first results in the summer of 2023.
diff --git a/docs/reference-material/the-language-ampersand/best-practices.md b/docs/guides/best-practices.md
similarity index 99%
rename from docs/reference-material/the-language-ampersand/best-practices.md
rename to docs/guides/best-practices.md
index 0c194bd90c..f357a02f7f 100644
--- a/docs/reference-material/the-language-ampersand/best-practices.md
+++ b/docs/guides/best-practices.md
@@ -1,4 +1,4 @@
-# Best Practices
+# Best practices For Ampersand Modellers
## Use `PURPOSE`-statements abundantly
diff --git a/docs/installing-ampersand/deploying-your-prototype.md b/docs/guides/deploying-your-prototype.md
similarity index 94%
rename from docs/installing-ampersand/deploying-your-prototype.md
rename to docs/guides/deploying-your-prototype.md
index 8166ce7d3f..3d99bfb6c6 100644
--- a/docs/installing-ampersand/deploying-your-prototype.md
+++ b/docs/guides/deploying-your-prototype.md
@@ -92,5 +92,5 @@ docker images
* Check if there is a firewall that blocks the port from internet. Make sure that port 80 is open for http-traffic.
* Check the port settings and adapt `docker-compose.yml` if you must use a port other than port 80.
* Use a recent browser. We have developed Ampersand on FireFox and tested it on FireFox and Chrome, so you should be fine with one of these two.
-* If you have trouble with the database (e.g. you cannot login, or do not have the correct authorization), check out the [instructions](installing-the-tools-manually.md) for creating a properly authorized user `ampersand` for the database. As you can see in `docker-compose.yml`, the database itself is accessible through port 8080.
+* If you have trouble with the database (e.g. you cannot login, or do not have the correct authorization), you need to create a properly authorized user `ampersand` for the database. As you can see in `docker-compose.yml`, the database itself is accessible through port 8080.
* It is a good idea to deploy your webapplication to localhost for testing. However, if you use a subdomain (e.g. my.ampersand.app.localhost) you will find that your `hosts`-file does not support wildcard redirection. You can do this by installing a local dns server (details on [http://passingcuriosity.com/2013/dnsmasq-dev-osx/](http://passingcuriosity.com/2013/dnsmasq-dev-osx/))
diff --git a/docs/reference-material/frequently-asked-questions.md b/docs/guides/frequently-asked-questions.md
similarity index 83%
rename from docs/reference-material/frequently-asked-questions.md
rename to docs/guides/frequently-asked-questions.md
index 4ca8bdba1c..af108df4be 100644
--- a/docs/reference-material/frequently-asked-questions.md
+++ b/docs/guides/frequently-asked-questions.md
@@ -1,7 +1,3 @@
----
-title: Frequently Asked Questions
-id: frequently-asked-questions
----
# Frequently Asked Questions
This page tries to help you by anticipating on the questions you might have.
@@ -14,8 +10,8 @@ Some questions in this page do not have an answer yet. Please consider that as o
* How can I inspect the database underneath an Ampersand application?
## Deployment
-* How can I deploy an Ampersand application on my laptop?
-* How can I deploy an Ampersand application on a virual machine (i.e. a server)
+* [How can I deploy an Ampersand application on my laptop?](installing-ampersand.md)
+* [How can I deploy an Ampersand application on a virual machine (i.e. a server)](installing-ampersand.md)
* How can I deploy an Ampersand application on Kubernetes?
## Data
diff --git a/docs/installing-ampersand/installing-the-tools-manually.md b/docs/guides/installing-ampersand.md
similarity index 65%
rename from docs/installing-ampersand/installing-the-tools-manually.md
rename to docs/guides/installing-ampersand.md
index ca535d9bbe..ad144c6a1f 100644
--- a/docs/installing-ampersand/installing-the-tools-manually.md
+++ b/docs/guides/installing-ampersand.md
@@ -1,23 +1,55 @@
----
-description: >-
- Please make sure you have a good reason to do this manually. Using the
- automated procedures is much easier...
----
+# Installing Ampersand
-# Installing the tools manually
+Ampersand is great for rapid prototyping. We advise you to use Ampersand on the web because it works without installing anything. But sometimes you want to run your prototypes on your own computer\(s\). For different purposes there are different ways of doing that. This chapter shows you how.
+
+## How to edit Ampersand scripts
+
+You can use any text editor to create Ampersand scripts.
+However, for those that use the [Visual Studio Code \(vscode\)](https://code.visualstudio.com/) editor, there is language support.
+Search for the [vscode extension](https://marketplace.visualstudio.com/items?itemName=AmpersandTarski.language-ampersand) "Ampersand language support" and install it, and then choose the coloring theme called "Ampersand".
+
+## How to use Ampersand on your own laptop
+
+Using Ampersand offline does not require you to install Ampersand.
+Ampersand runs in Docker so you can use it independently and on almost any platform. [Here is an explanation of how to do this \(don't mind the title of that page\)](deploying-your-prototype.md). It can be summarized as follows:
+
+1. Make sure Docker runs on your laptop or install it if it doesn't.
+2. Copy the files `Dockerfile` and `docker-compose.yml` and adapt them for your own Ampersand prototype. [Read this](deploying-your-prototype.md) if you don't know where to find them.
+3. Run your `.adl`-file on the Docker platform.
+
+### How to compile Ampersand programs manually
+
+To run an Ampersand program, DIY-engineers will need a webserver that can run javascript, PHP7, the PHP composer, and a \(My\)SQL or MariaDB database server. For generating functional specifications, you might use LaTeX, Markdown, Word .docx and other formats. This chapter gives an overview of the Ampersand production line for whoever needs to circumvent the automated process.
+
+### How to install your own copy of RAP4 on a server of your own choosing
+
+RAP4 is an Ampersand repository, in which multiple users can store and use their Ampersand scripts. Consult [the tools we use at Ampersand](../the-tools-we-use/tools-used-in-the-ampersand-project.md). This is work in progress.
+
+### How to change Ampersand itself
+
+If you want to change the Ampersand compiler for your own purposes, you need access to the source files, and a Haskell development environment. This section still has to be written. It will describe the software process for developing Ampersand itself.
+
+The remainder of this chapter explains in detail all the things you need to get you up and running with Ampersand. The instructions presume that you are familiar with your own computer(s).
+
+
+## Installing the Ampersand compiler manually
+1. All graphical output is created using [**GraphViz**](http://www.graphviz.org/). You need to install it.
+
+:::info
+Make sure _dot_ and _neato_ are in your path (set the $PATH environment variable if necessary).
+:::
-1. All graphical output is created using [**GraphViz**](http://www.graphviz.org/). You need to install it. **Make sure** _**dot**_ **and** _**neato**_ **are in your path** (set the $PATH environment variable if necessary). Also, if you compile it from source, make sure you install it with gts support.
2. There are several formats that you can generate a functional specification document in. Currently, the best results can be obtained in [docx ](https://www.lifewire.com/docx-file-2620750)or [LaTeX (PDF)](https://en.wikipedia.org/wiki/LaTeX). Depending on your taste, you need appropriate software:
1. For docx, you could of course use Microsoft Word, but there are [other options](https://www.maketecheasier.com/open-docx-file-without-microsoft-office/) as well.
2. If you want to generate PDF files, using LaTeX, you need a LaTeX compiler. On Windows, we recommend [**MiKTeX**](http://miktex.org/). On Linux and MacOS, we recommend [**texlive**](https://www.tug.org/texlive/).
Ampersand models are written as source code files. Hence, you need a text editor in which you can do so. We recomend [Visual Studio Code](https://code.visualstudio.com/docs/setup/setup-overview), which has [a nice extention for Ampersand scripts](https://marketplace.visualstudio.com/items?itemName=AmpersandTarski.language-ampersand). You could however use any text editor that you are familiar with, as long as you make sure it saves files as [UTF8 ](https://en.wikipedia.org/wiki/UTF-8)format.
-## Installing an Ampersand compiler
+### Installing an Ampersand compiler
The following instructions presume that you are familiar with the basics of your own computer.
-### The easy way: Use a prebuilt executable file
+#### The easy way: Use a prebuilt executable file
The easiest way is by use of available executables. We release frequently. Have a look at [our latest release](https://github.com/AmpersandTarski/Ampersand/releases). For Windows users, there is a file called ampersand.exe in the release. Put it on your disk on a location of your choice, for example /Ampersand/bin/. Make sure [your `$PATH`(or: `PATH`) environment variable contains this location](https://www.google.com/search?q=setting+your+path+variable), so the command "ampersand" is known on the command line. That's all. Note that double-clicking`ampersand.exe`will not work, because it is a command line tool.
@@ -25,14 +57,22 @@ Here is a way to test whether or not you have succeeded: open a command line too
Now you can compile and check your Ampersand scripts. However, you are likely to want to do more with such scripts. Currently it is possible to generate functional specifications and/or functional prototypes from such scrips. You will need to install some additional software in order to do that.
-### Additional software for generating functional SPECIFICATIONS:
+#### Additional software for generating functional SPECIFICATIONS:
-If you want to generate functional specifications from ampersand scripts, you need the following additional software (if you don't, don't bother installing them):
+If you want to generate functional specifications from ampersand scripts with pictures, you need the following additional software:
-1. In order to generate PDF files that contain your functional specification, you need a LaTeX compiler. On Windows, we recommend [**MiKTeX**](http://miktex.org/). On Linux and MacOS, we recommend [**texlive**](https://www.tug.org/texlive/).
-2. All graphical output is created using [**GraphViz**](http://www.graphviz.org/). You need to install it. **Make sure** _**dot**_ **and** _**neato**_ **are in your path** (set the $PATH environment variable if necessary). Also, if you compile it from source, make sure you install it with gts support.
+1. All graphical output is created using [**GraphViz**](http://www.graphviz.org/). You need to install it.
-### Additional software for generating functional PROTOTYPES
+:::caution
+Make sure _dot_ and _neato_ are in your path (set the $PATH environment variable if necessary).
+:::
+
+If you want to generate functional specifications from ampersand scripts in LaTeX, you need the following additional software (if you don't, don't bother installing them):
+
+1. On Windows, we recommend [**MiKTeX**](http://miktex.org/).
+2. On Linux and MacOS, we recommend [**texlive**](https://www.tug.org/texlive/).
+
+#### Additional software for generating functional PROTOTYPES
If you want to generate functional prototypes from ampersand scripts, you need the following additional software (if you don't, don't bother installing them):
@@ -53,12 +93,12 @@ If you want to generate functional prototypes from ampersand scripts, you need t
* The webserver must run on `localhost` . By default you will use port 80, but you could change that if required. See the documentation of you webserver.
2. You will also need to install [**Composer**](https://getcomposer.org/download/), because at runtime, the prototype has dependencies of libraries . Composer will take care of that.
-### The less easy way: Installing from Source
+#### The less easy way: Installing from Source
If there is no executable for your operating system, or if you prefer to build an Ampersand compiler yourself, follow these steps:
> 1. Install stack, the haskell tool stack. [instructions are here](http://docs.haskellstack.org/en/stable/install\_and\_upgrade.html)
-> 2. use [git](https://git-scm.com/) to clone the latest version of Ampersand. The code can be found at [github](https://github.com/AmpersandTarski/Ampersand/tree/master). (the master branch is our stable branch)
+> 2. use [git](https://git-scm.com/) to clone the latest version of Ampersand. The code can be found at [github](https://github.com/AmpersandTarski/Ampersand/tree/main). (the main branch is our stable branch)
> 3. Open a command line terminal, and go to the directory that contains the file named `ampersand.cabal`
> 4. Then, close your command line terminal and reopen another one (this helps to reload the environment variables that the `stack` installation may have added or modified),
> 5. Let `stack` install everything you need to compile (see the Notes below!) by executing:
@@ -71,17 +111,17 @@ This will build an Ampersand-compiler named "ampersand.exe" and install it into
Testing your installation
* Open a [command prompt](http://www.c3scripts.com/tutorials/msdos/open-window.html).
-* Type "Ampersand --version". The expected behaviour is that Ampersand replies with the version of Ampersand. It will look something like:
+* Type "Ampersand --version". The expected behavior is that Ampersand replies with the version of Ampersand. It will look something like:
```
C:> ampersand.exe --version
- Ampersand v3.1.0[master:2fa348f*], build time: 08-Sep-15 14:04:58 West-Europa (z
- omertijd)
+ Ampersand v3.1.0[master:2fa348f*], build time: 08-Sep-15 14:04:58 West-Europa (zomertijd)
```
+:::tip
+The version number is important to specify, whenever you have a question of like to report an issue. It <b>really</b> helps us when you add the version number, **including everything between the brackets** when you contact us.
+:::
- The version number is important to specify, whenever you have a question of like to report an issue. It **really** helps us when you add the version number, **including everything between the brackets** when you contact us.
-
-## Test to see if you can build your first prototype
+### Test to see if you can build your first prototype
Ampersand allows you to generate a working prototype of your ampersand model. An Ampersand prototype is a website that requires a webserver to run on and a (My)SQL database server. This chapter describes the prerequisites for getting such prototypes up, and running.
@@ -98,9 +138,9 @@ MEANING "My name can be known in the current session."
ROLE User MAINTAINS "Please click on 'Registration' to specify your name"
RULE "Please click on 'Registration' to specify your name": "_SESSION"[SESSION] |- sessionMyName;sessionMyName~
-VIOLATION (TXT "You can find the 'Registration' item in the navigationbar (top of the screen).")
+VIOLATION (TXT "You can find the 'Registration' item in the navigation bar (top of the screen).")
-INTERFACE Registration: "_SESSION"[SESSION] cRud ROWS
+INTERFACE Registration: "_SESSION"[SESSION] cRud BOX<TABLE>
[ "My name is" : sessionMyName cRUd
]
@@ -111,7 +151,7 @@ VIOLATION (TXT "{EX} SetNavToOnCommit;/Hello_44__32_World"
,TXT "{EX} InsPair;sayHelloReq;SESSION;", SRC I, TXT ";SESSION;", TGT I
)
-INTERFACE "Hello, World": "_SESSION"[SESSION] cRud ROWS
+INTERFACE "Hello, World": "_SESSION"[SESSION] cRud BOX<TABLE>
[ "Hello, world. My name is" : sessionMyName cRud
]
@@ -128,13 +168,11 @@ Then, you can generate the prototype website for the script in file `myModel.adl
ampersand --proto myModel.adl
```
-This creates a directory `myModel.proto` (in the current directory), that contains the prototype website. Obviously, you will need a web server and a database server to run the prototype. This is discussed at [Installing Ampersand](installing-the-tools-manually.md).
+This creates a directory `myModel.proto` (in the current directory), that contains the prototype website. Obviously, you will need a web server and a database server to run the prototype.
Usually, you would have some demands regarding particulars of the generation. For example, you may want to generate the website in a specific directory, specify a particular CSS file for this website, etc. For the complete syntax of the Ampersand executable, see the chapter about the [command line interface](../the-command-line-tool/)\*\*\*\*
**Notes:**\
1\. Do **not** use Hackage to get ampersand. It does not contain all non-haskell files. (See [issue #213](https://github.com/AmpersandTarski/ampersand/issues/213))\
2\. `stack` memory usage may require other applications to be terminated (e.g. on 8GB Windows systems). If `stack` terminates prematurely, re-invoking the command will pick-up where it stopped.\
-3\. `stack` may terminate on various errors [(See this issue)](https://github.com/commercialhaskell/stack/issues/2617), e.g. that it doesn't have permission to access or rename files. Again, if `stack` terminates prematurely, re-invoking the command will pick-up where it stopped. Users have mentioned having to restart `stack` several times before it would finally complete building Ampersand.exe.
-
-#### Footnotes
+3\. `stack` may terminate on various errors [(See this issue)](https://github.com/commercialhaskell/stack/issues/2617), e.g. that it doesn't have permission to access or rename files. Again, if `stack` terminates prematurely, re-invoking the command will pick-up where it stopped. Users have mentioned having to restart `stack` several times before it would finally complete building Ampersand.exe.
\ No newline at end of file
diff --git a/docs/guides/onboarding.md b/docs/guides/onboarding.md
new file mode 100644
index 0000000000..2196a728d4
--- /dev/null
+++ b/docs/guides/onboarding.md
@@ -0,0 +1,72 @@
+# Onboarding
+
+> Welcome to the Ampersand team!
+
+Below you wil find a list of activities to get a new contributor up-to speed with Ampersand development.
+
+- Schedule a meeting with [Stef Joosten](<mailto:Stef.Joosten@ordina.nl?subject=Request demo meeting>) to get an explanation and demo about the Ampersand project.
+- Contact [Han Joosten](<mailto:Han.Joosten@ordina.nl?subject=Request for access to ampersand project&body=Hi Han,%0D%0A%0D%0AI am contacting you to get access to the following:%0D%0A - An invite to the upcoming sprint review meeting to meet the team.%0D%0A - Access to the github repository, _YOUR_GITHUB_ACCOUNTNAME_OR_ACCOUNTLINK_.%0D%0A - Invites to the different sprint meetings that are currently scheduled.%0D%0A - Adding me to the Ampersand-whatsapp group, my phone number is: YOUR_PHONE_NUMBER.>) for the following options to get access to the full ampersand project.
+ - Join the upcoming sprint review meeting to meet the team.
+ - Request access to the GitHub repository as [described below](#github-memberships).
+ - Get invited to the different sprint meetings through teams as [described below](#microsoft-teams-memberships).
+- Clone the needed repositories [described below](#github-workflow-and-info)
+
+## GitHub memberships
+
+Ensure you have a GitHub account. This can be a 'professional' account connected to your Ordina email or any other account.
+
+Request membership to
+
+- [AmpersandTarski](https://github.com/orgs/AmpersandTarski/people) organization and
+- [Ordina A-team](https://github.com/orgs/AmpersandTarski/teams/ordina-a-team/members).
+
+:::tip
+Make sure when you contact Han about this that you provide him with your Github account name (or URL to your GitHub profile page).
+:::
+
+## Microsoft Teams memberships
+
+The Ampersand team members and also some old members can be found in the teams group channel.
+
+- Membership Microsoft Teams project [Project A & NUT-Vluchtelingen open source
+ ](https://teams.microsoft.com/l/team/19%3ayM9P1tFiWIADqDUbLDyX7ksB1Oavi04StkxyS6grh7A1%40thread.tacv2/conversations?groupId=09b86f1c-3ba6-411d-9b16-f0915eb2ed8a&tenantId=a254b169-0a6b-47f9-af4c-169704421c2e).
+- Owner permissions on that project (seems to be current practice).
+- Tagged as _AmpersandTarski A-team_ (facilitates initiating chats).
+
+## Meetings
+
+Request invitations to the regular (Microsoft Teams) meetings.
+
+These are currently:
+
+- NUTwente/Ampersand wekelijkse overleg; every monday 11:30, 1 hour.
+- Daily standup; tuesday till friday 11:30, 30 minutes
+- A-team: Sprint review; at end of sprint, friday 9:00, 50 minutes
+- A-team: Sprint retrospective; at end of sprint, friday 10:00, 50 minutes
+- A-team: Sprint planning; at end of sprint, friday 11:00, 50 minutes
+
+## Github workflow and info
+
+To work on the project you wil need a local version of the different repositories depending on what you are going to work on. Below is a short description of all the different repositories and what they are used for.
+
+### Ampersand
+
+[The ampersand repository](https://github.com/AmpersandTarski/Ampersand) contains the ampersand application that compiles and builds ampersand applications.
+
+### Prototype
+
+[The prototype repository](https://github.com/AmpersandTarski/prototype) makes sure that a ampersand application has a visual interface for the user to interact with your applications.
+
+### RAP
+
+[The RAP repository](https://github.com/AmpersandTarski/RAP) is an ampersand application that can be used to create a new ampersand application. This app is mainly used by the Open University of the Netherlands in the course Rule Based Design.
+
+### AmpersandTarski.github.io
+
+[The AmpersandTarski.github.io repository](https://github.com/AmpersandTarski/AmpersandTarski.github.io) is used to create the docusaurus documentation webpage. It pulls the different documents from the docs folders of all the repositories. While working this way we need to make sure to work in the correct docs folders.
+
+> For Example a document that references or is meant for RAP needs to be in the RAP repository docs folder.
+
+:::info
+Make sure to work in the ***documentation branch*** while creating or editing documentation to prevent unnecessary usage of the pipelines.
+:::
\ No newline at end of file
diff --git a/docs/installing-ampersand/README.md b/docs/installing-ampersand/README.md
deleted file mode 100644
index c9b91521a5..0000000000
--- a/docs/installing-ampersand/README.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Installing Ampersand
-
-Ampersand is great for rapid prototyping. We advise you to do that on the web. But sometimes you want to run your prototypes on your own computer\(s\). For different purposes there are different ways of doing that. This chapter shows you how.
-
-## How to edit Ampersand scripts
-
-You can use any text editor to create Ampersand scripts. However, for those that use the [Visual Studio Code \(vscode\)](https://code.visualstudio.com/) editor, there is language support. All you have to do is search for the vscode extension "Ampersand \(ADL\) language support" and install it, and then choose the coloring theme called "Ampersand".
-
-## How to use Ampersand on your own laptop
-
-Using Ampersand offline does not require you to install Ampersand. Ampersand runs in Docker so you can use it independently and on almost any platform. [Here is an explanation of how to do this \(don't mind the title of that page\)](deploying-your-prototype.md). It can be summarized as follows:
-
-1. Make sure Docker runs on your laptop or install it if it doesn't.
-2. Copy the files `Dockerfile` and `docker-compose.yml` and adapt them for your own Ampersand prototype. [Read this](deploying-your-prototype.md) if you don't know where to find them.
-3. Run your `.adl`-file on the Docker platform.
-
-### How to compile Ampersand programs manually
-
-DIY-engineers will find instructions in section [Installing the tools manually](installing-the-tools-manually.md). You need a webserver that can run javascript, PHP7, the PHP composer, and a \(My\)SQL or MariaDB database server. For generating functional specifications, you might use LaTeX, Markdown, Word .docx and other formats. This chapter gives an overview of the Ampersand production line for whoever needs to circumvent the automated process.
-
-### How to install your own copy of RAP4 on a server of your own choosing
-
-RAP4 is an Ampersand repository, in which multiple users can store and use their Ampersand scripts. Consult [the tools we use at Ampersand](https://ampersandtarski.gitbooks.io/the-tools-we-use-for-ampersand/content/installation_of_rap.html). This is work in progress.
-
-### How to change Ampersand itself
-
-If you want to change the Ampersand compiler for your own purposes, you need access to the source files, and a Haskell development environment. This section still has to be written. It will describe the software process for developing Ampersand itself.
-
-The remainder of this chapter explains in detail all the things you need to get you up and running with Ampersand. The instructions presume that you are familiar with your own computers.
-
diff --git a/docs/landingpage/1-interested-visitor.md b/docs/landingpage/1-interested-visitor.md
index 6d4986e17d..c5c514c375 100755
--- a/docs/landingpage/1-interested-visitor.md
+++ b/docs/landingpage/1-interested-visitor.md
@@ -53,7 +53,7 @@ That means that the result of evaluating a rule only depends on the context and
This feature characterizes Ampersand as different from *procedural* languages.
### Reactive
-Ampersand is a [reactive] language.
+Ampersand is a [reactive](../reactive-programming.md) language.
It does not follow pre-specified threads of action, but it reacts to events from outside and inside the system.
Reactive programming sets Ampersand apart from multi-threaded programming.
@@ -61,7 +61,7 @@ Reactive programming sets Ampersand apart from multi-threaded programming.
### Statically typed
All relations in a context together form a conceptual model.
The Ampersand compiler uses this model for type checking the rules you specify in an Ampersand script.
-The word ``static'' refers to type checking by the compiler.
+The word ''static'' refers to type checking by the compiler.
This prevents many runtime errors, presenting them at compile time as type errors.
Static typing is known to save modelers much effort and to enhance the quality of the generated code.
For a novice, static type checking can yield some frustration, which will quickly dissolve as your experience grows.
@@ -146,7 +146,7 @@ The governance of Ampersand is founded on the following principles:
* We continually draw on best practices from others to improve our productivity.
### Future directions
-We lay out the [future directions](ampersand/future-plans) in terms of research questions.
+We lay out the [future directions](../future-plans.md) in terms of research questions.
Such topics are usually discussed on Ampersand days or physical meetings of the core team.
[Stef Joosten](https://github.com/stefjoosten) has a final say in this, to ensure progress.
The following topics are on our wish-list
@@ -167,5 +167,5 @@ both have a "main" branch, which contains all releases as tags.
Contributors make pull requests to merge their branch into the main branch.
This merge also requires a code review by one of the core team members.
Automatic testing (by GitHub actions) ensures a minimal amount of hygiene.
-We merge only compilable code that passes the regression test.## What are the plans for the future?
+We merge only compilable code that passes the regression test.
## What do you need to use Ampersand?
diff --git a/docs/landingpage/2-student.md b/docs/landingpage/2-student.md
index 568558195f..e3b95fc6bd 100644
--- a/docs/landingpage/2-student.md
+++ b/docs/landingpage/2-student.md
@@ -3,11 +3,13 @@ title: For students
---
# What can I learn on this site?
+
If you are excited and eager to learn how to use Ampersand, you have come to the right place.
You can learn about the language Ampersand, and learn how to make a prototype of an information system and run it.
## Get started
-* Do the [tutorial](../tutorial-rap4), to get an idea of an Ampersand application
-* Learn about the [syntax of Ampersand](../reference-material/syntax-of-ampersand.md), to write correct Ampersand code.
-* Learn about [relation algebra](https://en.wikipedia.org/wiki/Relational_algebra) on Wikipedia, to understand more about this fascinating field of mathematics.
-* Find [exercises](../exercises/README.md) that help you improve your skills in specifying information systems.
+
+- Do the [tutorial](../tutorial-rap4), to get an idea of an Ampersand application
+- Learn about the [syntax of Ampersand](../reference-material/syntax-of-ampersand), to write correct Ampersand code.
+- Learn about [relation algebra](https://en.wikipedia.org/wiki/Relational_algebra) on Wikipedia, to understand more about this fascinating field of mathematics.
+- Find [exercises](../exercises.md) that help you improve your skills in specifying information systems.
diff --git a/docs/landingpage/3-ampersand-user.md b/docs/landingpage/3-ampersand-user.md
index 71d0a1dab5..f7aa2ff6df 100644
--- a/docs/landingpage/3-ampersand-user.md
+++ b/docs/landingpage/3-ampersand-user.md
@@ -3,16 +3,19 @@ title: For users of Ampersand
---
# How can I build an information system?
+
If you want to build information systems with Ampersand, you have come to the right place.
This page will help you build a working prototype of your information system and run it.
## Get started
-* Do the [tutorial](../tutorial-rap4), to get an idea of an Ampersand application
-* Understand the [architecture of an Ampersand application](../architecture-of-an-ampersand-application/README.md), so you can build, deploy, and maintain your Ampersand application better.
-* Learn about the [syntax of Ampersand](../reference-material/syntax-of-ampersand.md), to write correct Ampersand code.
-* Learn about [relation algebra](https://en.wikipedia.org/wiki/Relational_algebra) on Wikipedia, to understand more about this fascinating field of mathematics.
-* Learn about using the [Ampersand compiler](../the-command-line-tool.md) from your command line interface (CLI), if you need to use the compiler as a stand-alone application.
+
+- Do the [tutorial](../tutorial-rap4), to get an idea of an Ampersand application
+- Understand the [architecture of an Ampersand application](../reference-material/architecture-of-an-ampersand-application), so you can build, deploy, and maintain your Ampersand application better.
+- Learn about the [syntax of Ampersand](../reference-material/syntax-of-ampersand), to write correct Ampersand code.
+- Learn about [relation algebra](https://en.wikipedia.org/wiki/Relational_algebra) on Wikipedia, to understand more about this fascinating field of mathematics.
+- Learn about using the [Ampersand compiler](../the-command-line-tool.md) from your command line interface (CLI), if you need to use the compiler as a stand-alone application.
## Resources
-* There are many [modules available for re-use](../reusing-available-modules.md), which can save you time because they have been designed specifically for that purpose.
+
+- There are many [modules available for re-use](../reusing-available-modules.md), which can save you time because they have been designed specifically for that purpose.
diff --git a/docs/landingpage/4-scientist.md b/docs/landingpage/4-scientist.md
index 125bda1480..e37acc45da 100755
--- a/docs/landingpage/4-scientist.md
+++ b/docs/landingpage/4-scientist.md
@@ -9,10 +9,10 @@ We aim at generating "all the way", which means that specifications are as close
Interested? Here are some frequently asked questions. Click for the answers.
* [What is the purpose of Ampersand?](./1-interested-visitor.md#whyAmpersand)
-* [Which research papers have been produced?](/ampersand/research#Publications)
-* [Which research results have been produced?](/ampersand/research#Results)
-* [What is an information system according to Ampersand?](/ampersand/conceptual/theory.md)
+* [Which research papers have been produced?](../research#Publications)
+* [Which research results have been produced?](../research#Results)
+* [What is an information system according to Ampersand?](../conceptual/theory.md)
* [How is the Ampersand project being run?](./1-interested-visitor.md#Governance)
-* [What are the plans for the future?](ampersand/future-plans)
-* [What is needed?]
-* [Who are involved?]
+* [What are the plans for the future?](../future-plans)
+<!-- * [What is needed?] -->
+<!-- * [Who are involved?] -->
diff --git a/docs/landingpage/5-contributor.md b/docs/landingpage/5-contributor.md
index 476a6fec2f..ae8112cca0 100644
--- a/docs/landingpage/5-contributor.md
+++ b/docs/landingpage/5-contributor.md
@@ -3,13 +3,17 @@ title: For contributors
---
# Contributing to Ampersand
-Many people have contributed to the Ampersand project in the past,
-each in her or his own way.
-We're very proud of the results and we are amazed daily of the software that tiny specifications can produce.
-If you want to be part of it, contact @stefjoosten on Github to discuss your contribution.
+Many people have contributed to the Ampersand project in the past, each in her or his own way. We're very proud of the results and we are amazed daily of the software that tiny specifications can produce.
+
+If you want to be part of it, contact [stefjoosten](<mailto:Stef.Joosten@ordina.nl?subject=Request contribution meeting>) on Github to discuss your contribution.
Here are some links that are useful for contributors.
-# The tools we use
-* [Best Practices](../reference-material/the-language-ampersand/best-practices) describe the do's and don'ts that every contributor should know before committing a contribution.
-* [Architecture of an Ampersand Application](../architecture-of-an-ampersand-application/README.md) describes what kind of information system Ampersand produces.
\ No newline at end of file
+## Ordina A-team
+
+If you are already part of the Ordina A-team, you can find [onboarding documentation here](../guides/onboarding.md).
+
+## The tools we use
+
+- [Best Practices](../guides/best-practices) describe the do's and don'ts that every contributor should know before committing a contribution.
+- [Architecture of an Ampersand Application](../reference-material/architecture-of-an-ampersand-application) describes what kind of information system Ampersand produces.
diff --git a/docs/modeling/README.md b/docs/modeling/README.md
index 19c7d1172e..f47bcae61c 100644
--- a/docs/modeling/README.md
+++ b/docs/modeling/README.md
@@ -3,7 +3,7 @@
There can be many reasons for making an Ampersand model. Just a few examples are:
* You want to **study the conceptual structure** of something, to gain a better understanding or to acquire the jargon of a topic. Business analysts do it when starting on a new assignment. In a new environment with new people, unknown habits and a lot of catching up to do, they pick some documentation, courseware, legislature or other jargon-laden documentation and make an Ampersand model. Making sense of piles of new material goes much faster if you try to make an Ampersand model on the side.
-* You want to **design an application**. You make a model of the data, the rules and make one service for every service your store provides.
+* You want to **design an application**. You make a model of the data, the rules and make an interface for every service your store provides.
* You want to detect **flaws in an architecture**. Make an ampersand model of that architecture, and model every rule you want checked. Populate your model with data from the real architecture, and you can measure every flaw as it occurs.
* Your build-team wants clear working instructions, but there is no time to make **a functional specification**. You make your Ampersand model and derive the work instructions from the functional specification and the prototype that you have made.
* You need **correct software**. Develop your software in Ampersand and use the rules to establish correctness.
@@ -23,13 +23,13 @@ To specify an information system, take the following steps:\
1\. Agreement on the domain language;\
2\. Agreement on rules;\
3\. Validate rules;\
-4\. Define services.
+4\. Define interfaces.
## What is a model about?
An ampersand model describes the rules, relations and concepts that define a business system. Using this specification, a software system can be built that can hold structured information as a set of facts. Based on the rules, the set of facts can be checked automatically to detect violations of rules.
-In an Ampersand model, services can be defined too, enabling the definition of changes to the set of facts.
+In an Ampersand model, interfaces can be defined too, enabling the definition of changes to the set of facts.
# Architecture modeling{#architecture}
diff --git a/docs/modeling/data-modeling.md b/docs/modeling/data-modeling.md
index 92266294ba..7902c55147 100644
--- a/docs/modeling/data-modeling.md
+++ b/docs/modeling/data-modeling.md
@@ -8,14 +8,14 @@ In this section we will systematically extract concepts and relations based on d
Let us start by looking at an example:
-| | firstname | lastname | birth |
-| :--- | :--- | :--- | :--- |
-| 1 | Abraham | Lincoln | February 12, 1809 |
-| 2 | Barack | Obama | August 4, 1961 |
-| 3 | Calvin | Coolidge | July 4, 1872 |
-| 4 | Dwight | Eisenhower | October 14, 1890 |
+| | firstname | lastname | birth |
+| :-- | :-------- | :--------- | :---------------- |
+| 1 | Abraham | Lincoln | February 12, 1809 |
+| 2 | Barack | Obama | August 4, 1961 |
+| 3 | Calvin | Coolidge | July 4, 1872 |
+| 4 | Dwight | Eisenhower | October 14, 1890 |
-Since Ampersand works with [relations](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement), it must represent this table as relations. Three relations can do the job in the following manner:
+Since Ampersand works with [relations](../reference-material/syntax-of-ampersand#the-relation-statement), it must represent this table as relations. Three relations can do the job in the following manner:
```text
POPULATION firstname[President*Name] CONTAINS
@@ -46,7 +46,7 @@ In our example, each row in the spreadsheet represents a president. So, the sour
When things get bigger, it is useful to draw the relations on a whiteboard or in your notebook. This helps you keep overview. Here is how it is done:
- 
+
This drawing shows every relation als a line, drawn from source to target. The arrowhead in the middle is only to remind the reader of which is the source and which is the target concept. If you point the arrowhead from source to target, you will always know how the relation is defined.
@@ -54,23 +54,23 @@ This drawing shows every relation als a line, drawn from source to target. The a
Suppose we have a second table, which also has information
-| \[State\] | capital | president |
-| :--- | :--- | :--- |
-| Vermont | Plymouth | Coolidge |
-| Hawaï | Honolulu | Obama |
-| Kentucky | Frankfort | Lincoln |
-| New York | New York | Roosevelt |
-| Georgia | Atlanta | Carter |
+| \[State\] | capital | president |
+| :-------- | :-------- | :-------- |
+| Vermont | Plymouth | Coolidge |
+| Hawaï | Honolulu | Obama |
+| Kentucky | Frankfort | Lincoln |
+| New York | New York | Roosevelt |
+| Georgia | Atlanta | Carter |
This table is similar with respect to the interpretation of a row: here too, each row represents a president. However, the presidents aren't numbered in this table, so we have to add these numbers.
-| | \[State\] | capital | president |
-| :--- | :--- | :--- | :--- |
-| 3 | Vermont | Plymouth | Coolidge |
-| 2 | Hawaii | Honolulu | Obama |
-| 1 | Kentucky | Frankfort | Lincoln |
-| 5 | New York | New York | Roosevelt |
-| 6 | Georgia | Atlanta | Carter |
+| | \[State\] | capital | president |
+| :-- | :-------- | :-------- | :-------- |
+| 3 | Vermont | Plymouth | Coolidge |
+| 2 | Hawaii | Honolulu | Obama |
+| 1 | Kentucky | Frankfort | Lincoln |
+| 5 | New York | New York | Roosevelt |
+| 6 | Georgia | Atlanta | Carter |
Numbering rows has the advantage that it is easier to recognise a president.
@@ -161,9 +161,9 @@ RELATION birth[President*State] [UNI]
Two properties are relevant for the data model: univalent \(`UNI`\) and injective \(`INJ`\):
-* Relation `r[A*B] [UNI]` means that there is at most one pair $$(a,b)$$ in the relation for every $$a$$ in `A`.
-* Relation `r[A*B] [INJ]` means that there is at most one pair $$(a,b)$$ in the relation for every $$b$$ in B.
-* Relation `r[A*B] [UNI,INJ]` means the relation is both univalent and injective.
+- Relation `r[A*B] [UNI]` means that there is at most one pair $$(a,b)$$ in the relation for every $$a$$ in `A`.
+- Relation `r[A*B] [INJ]` means that there is at most one pair $$(a,b)$$ in the relation for every $$b$$ in B.
+- Relation `r[A*B] [UNI,INJ]` means the relation is both univalent and injective.
We have to do this for every relation:
@@ -211,11 +211,10 @@ In [this video](https://youtu.be/ruO4UgjA11E) you sit in in a private lecture in
After finishing your assignment, you have learned:
-* why it makes sense to analyse actual data samples for creating a data model;
-* how to analyze spreadsheet data and produce relations from it;
-* why it is necessary to document meaning for each relation;
-* how to constrain relations with univalence and injectivity;
-* how easily mistakes are made \(by using the Ampersand compiler in the assignment\);
-* how Ampersand's messages help you fix mistakes;
-* how to make Ampersand create a data model based on your data analysis.
-
+- why it makes sense to analyse actual data samples for creating a data model;
+- how to analyze spreadsheet data and produce relations from it;
+- why it is necessary to document meaning for each relation;
+- how to constrain relations with univalence and injectivity;
+- how easily mistakes are made \(by using the Ampersand compiler in the assignment\);
+- how Ampersand's messages help you fix mistakes;
+- how to make Ampersand create a data model based on your data analysis.
diff --git a/docs/reference-material/README.md b/docs/reference-material/README.md
new file mode 100644
index 0000000000..d8b9028c37
--- /dev/null
+++ b/docs/reference-material/README.md
@@ -0,0 +1 @@
+This section describes the full language Ampersand. Please use it as a reference rather than an introductory course.
\ No newline at end of file
diff --git a/docs/reference-material/The-language-Ampersand.md b/docs/reference-material/The-language-Ampersand.md
deleted file mode 100644
index e543de0886..0000000000
--- a/docs/reference-material/The-language-Ampersand.md
+++ /dev/null
@@ -1,282 +0,0 @@
----
-title: The Language Ampersand
-id: language
-description: Syntax and Semantics, including metasyntax.
----
-
-* [The language Ampersand](ampersand/the-language-ampersand/)
- * [How to read syntax statements](ampersand/the-language-ampersand/how-to-read-syntax-statements)
- * [Truth](ampersand/the-language-ampersand/truth)
- * [Atoms](ampersand/the-language-ampersand/atoms)
- * [Terms](ampersand/the-language-ampersand/terms/)
- * [Semantics](ampersand/the-language-ampersand/terms/semantics)
- * [Semantics in logic](ampersand/the-language-ampersand/terms/semantics#semantics-in-logic)
- * [Primitive terms](ampersand/the-language-ampersand/terms/semantics#primitive-terms-in-logic)
- * [Boolean operators](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-logic)
- * [Relational operators](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-logic)
- * [Residual operators](ampersand/the-language-ampersand/terms/semantics#residual-operators-in-logic)
- * [Semantics in natural language](ampersand/the-language-ampersand/terms/semantics#semantics-in-natural-language)
- * [Primitive terms in natural language](ampersand/the-language-ampersand/terms/semantics#primitive-terms-in-natural-language)
- * [Boolean operators in natural language](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-natural-language)
- * [Relational operators in natural language](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-natural-language)
- * [Residual operators in natural language](ampersand/the-language-ampersand/terms/semantics#residual-operators-in-natural-language)
- * [Semantics in set theory](ampersand/the-language-ampersand/terms/semantics#semantics-in-set-theory)
- * [Primitive terms in set theory](ampersand/the-language-ampersand/terms/semantics#semantics-in-set-theory)
- * [Boolean operators in set theory](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-set-theory)
- * [Relational operators in set theory](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-set-theory)
- * [Semantics of terms, defined algebraically](ampersand/the-language-ampersand/terms/semantics#semantics-in-relational-algebra)
- * [Boolean operators in algebra](ampersand/the-language-ampersand/terms/semantics#boolean-operators-in-algebra)
- * [Relational operators in algebra](ampersand/the-language-ampersand/terms/semantics#relational-operators-in-algebra)
- * [Semantics visualized](ampersand/the-language-ampersand/terms/semantics#semantics-visualized)
- * [Boolean operators visualized](ampersand/the-language-ampersand/terms/semantics#boolean-operators-visualized)
- * [Relational operators visualized](ampersand/the-language-ampersand/terms/semantics#relational-operators-visualized)
- * [Residuals visualized](ampersand/the-language-ampersand/terms/semantics#residual-operators-visualized)
- * [Context](ampersand/the-language-ampersand/context)
- * [Syntactical Conventions](ampersand/the-language-ampersand/syntactical-conventions/)
- * [Language support](ampersand/the-language-ampersand/syntactical-conventions/language-support)
- * [Patterns](ampersand/the-language-ampersand/patterns)
-## Services
-
-### Purpose
-Services are meant to expose functionality and data from a [context](./the-language-ampersand/context.md), to let users or information systems interact with the system by creating, reading, updating, and deleting data.
-
-### Description
-A service is a component of an information system that exposes functionality and data from a [context](./the-language-ampersand/context.md), to let users or information systems interact by creating, reading, updating, and deleting data. The first [example](../Examples.md#example-service-structure) introduces a simple service informally. Another [example](../Examples.md#service-introductory-example) introduces the main features of a service with nested interfaces.
-
-A *service* is a component of an information system. During the time that this service can actually be used, we say it is *deployed*. We also call this the *lifetime* of a service. A typical instance of a service is a user interface based on HTML-CSS that runs in a browser. But an application program interface \(API\) that serves other computers with web services is a perfectly valid instance as well.
-
-Please note that the keyword `INTERFACE` is still used. That may be confusing. In a future release of Ampersand the keyword `INTERFACE` will become obsolete and the word `SERVICE` will be used.
-
-### Syntax and Meaning {#syntax-of-interface-statement}
-Note: The service definition must be outside a pattern
-
-A service specification has the following structure. It is identical for user interfaces (`INTERFACE`) and application programming interfaces (`API`).
-
-```
-INTERFACE <name> <forRoles>? : <term> <crud>? <view>? <subinterface>?
-API <name> <forRoles>? : <term> <crud>? <view>? <subinterface>?
-```
-
-The name of a service must be unique within the context. The term defines the atoms to which the interface can be applied. The (optional) crud annotation constrains the possible interactions a user can do. The (optional) views determine what the service will look like. If no view is specified, the service will look like the screenshot above. Finally the sub-interface contains all the contents, i.e. the fields, field names and the constraints on them.
-
-The hierarchy of boxes in a service comes from the following (recursive) syntax of `<subinterface>`.
-
-A sub-interface may be defined on the spot (by `<boxKey> <box>`) or it may link to another service to reuse its structure:
-
-```
-<subinterface> ::= <boxKey> <box>
- | LINKTO ( INTERFACE | API ) <name>
-```
-
-The boxKey is meant to tell the front-end application what the service looks like. The compiler uses templates to adapt an interface to specific needs regarding its HTML structure.
-
-```
-<boxKey> ::= BOX '<' <htmlname> '>'
- | BOX
-```
-
-If no htmlname is specified, Ampersand uses `BOX <FORM>` by default.
-
-A box is simply a list of service items (`ifcItem`) separated by commas. Each service item specifies a field in the service or a sub-interface.
-
-```
-<box> ::= '[' <ifcItem> ( ',' <ifcItem> )* ']'
-```
-
-Each service item has a label that must be unique within the box. After the colon there is either a term or a text. The term specifies which data is related to the field it specifies if it has no sub-interface. If it does, it specifies the atoms on which the box is applied.
-
-```
-<ifcItem> ::= <label> ':' <term> <crud>? <view>? <subinterface>?
- | <label> ':' <text>
-```
-
-You can specify that a service is available only to actors (i.e. computers or persons) in a specific role.
-```
-<forRoles> ::= FOR <roles>
-<roles> ::= <rolename> ',' <roles>
- | <rolename>
-```
-
-### Using a service
-On the user screen each atom is displayed in some form as data. If a service exists for that atom, that is shown to the user as a hyperlink to which you can navigate.
-
-When running an application in your browser, you are watching one user interface at any given moment in time. Each hyperlink on your screen represents an atom to which some service applies. To navigate to that user interface, you click on the hyperlink. You will see the service being applied solely to the atom you just clicked. To determine the atom\(s\) to which a service applies, each service has an _interface term_.
-
-Further examples:
-
-* a [client service](./Examples.md#services-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
-* a [login service](./Examples.md#services-example-login) to demonstrate how to get different interface structures under varying conditions.
-
-### CRUD annotations {#crud}
-CRUD annotations are used in services to constrain the functionality of fields and boxes in an `INTERFACE`-statement. This allows you to minimize the functionality for your users, to design for easy learning.
-
-Each CRUD annotation comes right after a [term](../terms/README.md), so we can always refer to "the term" to which a CRUD annotation belongs. A CRUD annotation constrains the things your user can do with the target atoms and the pairs of its term.
-
-The CRUD-annotation specifies Create, Read, Update, and Delete rights for the term it follows. Capital = allowed, Non-capital = not allowed. CRUD is the default, so if you specify nothing, everything is allowed. The following service definition illustrates this.
-
-```
-INTERFACE Overview : "_SESSION" cRud
-BOX <TABS>
- [ Students : V[SESSION*Student] cRuD
- BOX <TABLE>
- [ "Student" : I[Student] cRud
- , "Enrolled for" : isEnrolledFor cRUD
- , "Course" : takes CRUD
- ]
- , Course : V[SESSION*Course] cRuD -- used for a box
- BOX <TABLE>
- [ "Course" : I cRud -- used for a field
- , "Modules" : isPartOf~ -- CRUD is default
- ]
- , Modules : V[SESSION*Module] cRud
- BOX <TABLE>
- [ "Modules" : I cRuD
- , "Course" : isPartOf cRUd
- , "Students" : isEnrolledFor~ CRUD
- ]
- ]
-```
-
-The user interface defined by this service is shown as a screenshot below. Notice that the lowercase r in the annotation of the Students box prevents showing the underlying box. The full CRUD functionality in Course yields 'create' functionality (the green plus-button), 'remove pair' functionality (red minus button), and 'delete atom' functionality (the red trash can button). The lowercase c, u, and d in the Modules box prevents displaying that functionality in the user interface.
-
-
-
-The next sections give some more detailed information on the runtime semantics for CRUD annotations as implemented in Ampersand.
-
-#### Create
-
-| CRUD | for a box | for a field. |
-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| C |  A + (plus) button is displayed that lets you create a new atom, but only if the box-term is editable. |  Enter a new atom and a `+` button appears. Click the + to add that atom to the listed set of atoms. If you enter an atom that exists (Peter), you can select it. |
-| c | Atoms cannot be created | Atoms cannot be created |
-
-#### Read
-
-| Read | CRUD for boxes | | CRUD for fields |
-| ---- | ------------------- | - | ------------------- |
-| R | Read is allowed | | Read is allowed |
-| r | Read is not allowed | | Read is not allowed |
-
-#### Update
-
-| Update | CRUD for boxes | CRUD for fields |
-| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| U |  Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. |  Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. |
-| u | Update is not allowed | Update is not allowed |
-
-#### Delete
-
-| Delete | CRUD for boxes | CRUD for fields |
-| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| D |  Deleting a pair is done with the - (minus) button. Deleting an atom is done with the trash bin. |  Delete atom (tgt) and all pairs in which it is used. |
-| d | delete not allowed | delete not allowed |
-
-A top-level Update or Create are common in my own scripts, e.g. to create an overview of People and be able to create a new Person: `INTERFACE "People" : V[SESSION*Person] CRud COLS []`. And update is also possible.
-
-#### Things to remember
-
-1. The red minus is enabled by `U`. It unlinks an atom (by deleting a pair from a relation) and leaves the atom alone.
-2. The red trash bin is enabled by `D`. It removes an atom and all pairs in which that atom is used.
-
-Motivations for CRUD-functionality are found in the [GitHub discussions on CRUD](https://github.com/AmpersandTarski/Ampersand/issues?utf8=%E2%9C%93\&q=is%3Aissue+label%3Acrud+) functionality.
-
-
-### Layout of user interfaces
-Ampersand is meant for back-end design. It offers no features for front-end design. For that purpose we advise you use contemporary front-end tools for web-based applications. Your Ampersand application is [designed to be adaptable](../architecture-of-an-ampersand-application/README.md), especially for this purpose.
-
-However, Ampersand offers a few layout features that let you place items. It has three built-in layout options, [colums](./#column-layout), [rows](./#row-layout) and [tabs](./#tabular-layout), which you can mix freely.
-
-#### Table layout
-
-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 a service, which uses the table layout.
-
-```
-INTERFACE Overview : "_SESSION" cRud
-BOX <TABS>
- [ Students : V[SESSION*Student] cRuD
- BOX <TABLE>
- [ "Student" : I[Student] cRud
- , "Enrolled for" : isEnrolledFor cRUD
- , "Course" : takes CRUD
- ]
- , Course : V[SESSION*Course] cRuD
- BOX <TABLE>
- [ "Course" : I cRud
- , "Modules" : isPartOf~ CRUD
- ]
- , Modules : V[SESSION*Module] cRud
- BOX <TABLE>
- [ "Modules" : I cRuD
- , "Course" : isPartOf cRUd
- , "Students" : isEnrolledFor~ CRUD
- ]
- ]
-```
-
-This service shows three columns in the user interface, **Students**, **Course** and **Modules**. The first column is not readable, because the [CRUD annotation](#crud) blocks this column for reading. It would have shown students in each row, because the target of `V[SESSION*Student]`is `Student`. The second column shows courses in two columns, **Course** and **Modules**. The third column shows modules in three columns. This is what the user will see on the screen.
-
-
-
-#### ROW layout
-
-The row layout uses `BOX <FORM>` to instruct the front-end application to layout the user interface row by row. Here is an example of a service, which uses the row layout on the top level.
-
-```
-INTERFACE Overview : "_SESSION" cRud
-BOX <FORM>
- [ Students : V[SESSION*Student] cRuD
- BOX <FORM>
- [ "Student" : I[Student] CRUD
- , "Enrolled for" : isEnrolledFor cRUD
- , "Course" : takes CRUD
- ]
- , Course : V[SESSION*Course] CRUD
- BOX <FORM>
- [ "Course" : I cRud
- , "Modules" : isPartOf~ CRUD
- ]
- ]
-```
-
-This service shows three rows in the user interface, **Students**, **Course** and **Modules**. The first column shows students in each of its rows. Each student is shown in the column layout. The second row shows courses in two columns, **Course** and **Modules**. Please read about [templates](https://github.com/AmpersandTarski/prototype/tree/master/templates) if you are curious which other ways of displaying information there are besides `BOX <FORM>`. Please read the [explanation of CRUD annotations](../crud.md) if you are curious about the CRUD annotations. This is what the user will see on the screen.
-
-
-
-#### Tabs layout
-
-The column layout uses `BOX <TABS>` to instruct the front-end application to tabs in the user interface. Here is an example of a service, which uses the column layout.
-
-```
-INTERFACE Overview : "_SESSION" cRud
-BOX <TABS>
- [ Students : V[SESSION*Student] cRuD
- BOX <TABLE>
- [ "Student" : I[Student] CRUD
- , "Enrolled for" : isEnrolledFor cRUD
- , "Course" : takes CRUD
- ]
- , Course : V[SESSION*Course] CRUD
- BOX <TABLE>
- [ "Course" : I cRud
- , "Modules" : isPartOf~ CRUD
- ]
- , Modules : V[SESSION*Module] cRud
- BOX <TABLE>
- [ "Modules" : I cRuD
- , "Course" : isPartOf cRud
- , "Students" : isEnrolledFor~ CRUD
- ]
- ]
-```
-
-This service shows three tabs in the user interface, **Students**, **Course** and **Modules**. Only one tab is shown at a time, to avoid cluttered data. This is what the user will see on the screen.
-
-
-
-We have discussed the `COLS`, `ROWS`, and `TABS` layout options. Please note that these options do not change the semantics; whatever your options, Ampersand displays the same data in the same fields.
-
-If these options are not enough, you can [enhance your application with your own layouts](your-own-widgets-html-and-css.md).
-
-#### Your own widgets \(HTML and CSS\)
-You don't have to put up with the [Ampersand built-in layout options](https://github.com/AmpersandTarski/prototype/tree/master/templates) if they don't suit your purpose. You can change most anything by including your own code snippets. \(to be done...\).
-
diff --git a/docs/reference-material/architecture-of-an-ampersand-application.md b/docs/reference-material/architecture-of-an-ampersand-application.md
new file mode 100644
index 0000000000..2f3a3c57aa
--- /dev/null
+++ b/docs/reference-material/architecture-of-an-ampersand-application.md
@@ -0,0 +1,119 @@
+# Architecture of an Ampersand Application
+This chapter is intended for programmers who wish to know more about the software Ampersand generates.
+There can be many reasons, such as wanting to change the user experience, add or change functionality in views and/or controls, or simply to use the API of an Ampersand application.
+In this chapter you will find more details of the applications you generate.
+
+## Information systems
+
+In general, any information system has a structure like the one depicted below:
+
+
+
+An information system is meant to support users (e.g. Peter, Sally, Daisy).
+Differences among users can be handled by using roles (e.g. customerRep, sysMgr, MgmtSupporter).
+In this diagram, users are coloured to depict different roles.
+
+An information system provides services, each of which realizes a business function.
+An example is a service to produce a police report (i.e. the business function), which is to be used only by authorized police officers (i.e. the role).
+We distinguish user facing services and non-user facing services.
+User facing services (e.g. register a client, sanitize case files, login) can be made available for a limited number of roles,
+giving each user access to precisely the services he or she is meant to see.
+In the diagram, user-facing services are colored corresponding to the roles they serve.
+Non-user facing services are not coloredand are used exclusively by other software.
+Services can be either stateful or stateless.
+Ampersand stores the state in a database, so all of Ampersand's services are stateless.
+This allows scaling an interface manyfold to serve multiple users at a time.
+In the diagram, stateful services are drawn with a data container inside.
+
+Each service provides one or more interfaces to communicate with the rest of the world.
+We distinguish graphical user interfaces (GUIs) and application programming interfaces (APIs).
+
+Services communicate by means of streams or by means of remote calls.
+
+## Information systems generated by Ampersand
+Currently, Ampersand generates correct information systems with one stateful service, which is the database, and one stateless service, which contains the interfaces.
+
+
+
+An Ampersand information system is deployed as a whole. Therefore it qualifies as a "monolithic" system.
+Let us discuss the components.
+At run time, an Ampersand system is just a web-based application.
+It consists of a HTML/CSS layer and a front-end, both of which run in the browser of a user.
+It consists of a back-end with an API, which runs on a server.
+The API contains functionality to create, read, update, and delete business objects (e.g. a police report) directly.
+The back-end translates these in terms of database tables to database queries, which it runs on the database.
+The database may reside on a different server than the back-end.
+The Ampersand compiler generates the entire information system from an Ampersand script.
+For that purpose it generates views, controllers, an information model and a database model,
+all of which are input to a prototype framework, which yields a complete web application.
+
+
+
+
+## An Ampersand application deployed on a docker platform
+
+Let us look at a typical Ampersand Application called RAP3, as an example, to demonstrates how Ampersand applications work on a docker platform.
+We use docker to facilitate frequent deployment anywhere in a robust manner and to isolate the internals from the outside world.
+
+.png>)
+
+ The structure of RAP3 has been defined statically (in docker-compose) to allow automated maintenance in production.
+ The application itself is implemented as a stateless service, `rap3`.
+ It uses a database, `db`, for persistent storage. It is connected to the internet by a proxy which takes care of https and http traffic on ports 443 and 80 respectively. Two local networks separate data traffic to facilitate future work load balancing. The components `db`, `phpmyadmin`, and `proxy` are open source components which we have reused from the internet.
+
+## Software Architecture of an Ampersand application
+
+Let us take a look at the structure of any system that Ampersand generates.
+
+
+
+The green area is a database application that works as a stateful service.
+It ensures that all invariants are kept satisfied in production as changes to the database are being made.
+The integrity of the data is defined by the rules in the Ampersand script and perpetuously maintained in the back-end of the application.
+
+The framework is encapsulated by an application programming interface (API, the yellow area), which exports the functionality in a standardised way. Every application that interfaces through that API will therefore automatically preserve the integrity of data.
+
+On top of the API, the application comes with a front-end application (the blue area). This web-application has a conventional structure, based on the well-known [Model-View-Control (MVC) pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) used in many web-applications.
+
+The Ampersand compiler (the orange thing on the right) generates the application as a collection of HTML-pages (views) and JavaScript pages (controls), together with static code that is loaded from a framework. So the framework and the API are generic components, in which the semantics are "injected" as JSON files from the Ampersand compiler.
+
+The structure described above is reflected in the directory structure generated by Ampersand:
+
+
+
+So if you look in your directory, the generated application will look like this:
+
+
+
+## The ExecEngine
+The execengine runs with every prototype generated by Ampersand.
+Both enforcement rules and automated rules use the execengine to fix violations automatically.
+
+## Hooks
+
+Hookpoint use the following naming convention:
+
+* camelCasing
+* start with _pre_ or _post_ to define if hooks are called before or after the following position
+* specify classname or file where hookpoint is positioned
+* specify functionname where hookpoint is positioned
+* optionally specify postion within function where hookpoint is positioned
+
+Current list of hookpoints:
+
+| Hookpoint | Extensions that use it |
+| :--- | :--- |
+| postDatabaseReinstallDB | ExecEngine |
+| postDatabaseUpdate | Mutation \(experimental\), Mqtt \(experimental\) |
+| postDatabaseInsert | Mutation \(experimental\), Mqtt \(experimental\) |
+| postDatabaseDelete | Mutation \(experimental\), Mqtt \(experimental\) |
+| preDatabaseCloseTransaction | ExecEngine |
+| | postDatabaseCloseTransaction |
+| postDatabaseAddAtomToConceptInsert | Mqtt \(experimental\) |
+| | postDatabaseAddAtomToConceptSkip |
+| postDatabaseDeleteAtom | Mqtt \(experimental\) |
+| | postDatabaseStartTransaction |
+| postDatabaseCommitTransaction | Mqtt \(experimental\) |
+| | postDatabaseRollbackTransaction |
+
+More hookpoints will be defined when needed.
\ No newline at end of file
diff --git a/docs/reference-material/the-language-ampersand/atoms.md b/docs/reference-material/atoms.md
similarity index 54%
rename from docs/reference-material/the-language-ampersand/atoms.md
rename to docs/reference-material/atoms.md
index 7ca601818b..10fd3596a8 100644
--- a/docs/reference-material/the-language-ampersand/atoms.md
+++ b/docs/reference-material/atoms.md
@@ -16,47 +16,47 @@ An atom refers to an individual object in the real world, such as the student ca
The syntax of atoms is largely taken from [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) and corresponds to the syntax of [SQL](https://www.w3schools.com/sql/func_sqlserver_convert.asp) and [Excel](https://support.office.com/en-us/article/format-numbers-as-dates-or-times-418bd3fe-0577-47c8-8caa-b4d30c528309). \(Acknowledgement: the following text was [adapted from Wikipedia](https://en.wikipedia.org/wiki/ISO_8601)\)
-* Date and time values are ordered from the largest to smallest unit of time: year, month \(or week\), day, hour, minute, second, and fraction of second. The lexicographical order of the representation thus corresponds to chronological order, except for date representations involving negative years. This allows dates to be naturally sorting\|sorted by, for example, file systems.
-* Each date and time value has a fixed number of digits that must be padded with leading zeros.
-* Representations can be done in one of two formats - a basic format with a minimal number of separators or an extended format with separators added to enhance human readability. The separator used between date values \(year, month, week, and day\) is the hyphen, while the colon is used as the separator between time values \(hours, minutes, and seconds\).
-* For reduced accuracy, any number of values may be dropped from any of the date and time representations, but in the order from the least to the most significant. For example, "2004-05" is a valid ISO 8601 date, which indicates May \(the fifth month\) 2004. This format will never represent the 5th day of an unspecified month in 2004, nor will it represent a time-span extending from 2004 into 2005.
-* If necessary for a particular application, the standard supports the addition of a decimal fraction to the smallest time value in the representation.
+- Date and time values are ordered from the largest to smallest unit of time: year, month \(or week\), day, hour, minute, second, and fraction of second. The lexicographical order of the representation thus corresponds to chronological order, except for date representations involving negative years. This allows dates to be naturally sorting\|sorted by, for example, file systems.
+- Each date and time value has a fixed number of digits that must be padded with leading zeros.
+- Representations can be done in one of two formats - a basic format with a minimal number of separators or an extended format with separators added to enhance human readability. The separator used between date values \(year, month, week, and day\) is the hyphen, while the colon is used as the separator between time values \(hours, minutes, and seconds\).
+- For reduced accuracy, any number of values may be dropped from any of the date and time representations, but in the order from the least to the most significant. For example, "2004-05" is a valid ISO 8601 date, which indicates May \(the fifth month\) 2004. This format will never represent the 5th day of an unspecified month in 2004, nor will it represent a time-span extending from 2004 into 2005.
+- If necessary for a particular application, the standard supports the addition of a decimal fraction to the smallest time value in the representation.
## Atomic types
Atoms are represented in an SQL database. For this purpose, every atom has a type \(sometimes called the _technical type_\). The representation in SQL is given in the following table.
-| type | purpose | SQL | closed | eq |
-| :--- | :--- | :--- | :--- | :--- |
-| ALPHANUMERIC | to represent strings of short length, i.e. less than 255 characters | VARCHAR\(255\) | yes | yes |
-| BIGALPHANUMERIC | to represent large strings of limited length, i.e. less than 64 kb | TEXT | no | yes |
-| HUGEALPHANUMERIC | to represent strings of arbitrary length | MEDIUMTEXT | no | no |
-| PASSWORD | to represent passwords in a secure way | VARCHAR\(255\) | no | yes |
-| BINARY | to represent uninterpreted binary data of short length | BLOB | no | no |
-| BIGBINARY | to represent large binary data of limited length | MEDIUMBLOB | no | no |
-| HUGEBINARY | to represent large binary data of arbitrary length | LONGBLOB | no | no |
-| DATE | to represent dates compatible with ISO8601 | DATE | yes | yes |
-| DATETIME | to represent timestamps compatible with ISO8601 | DATETIME | yes | yes |
-| BOOLEAN | to represent True and False values | BOOLEAN | yes | yes |
-| INTEGER | to represent positive and negative whole numbers in the range \[-2^63..2^63 -1\] | BIGINT | yes | yes |
-| FLOAT | to represent floating-point numbers compatible with ISO8601 | FLOAT | no | no |
-| Object | to represent a key value for objects; it is not meant to be visible to end-users. | VARCHAR\(255\) | yes | yes |
-| | all other atoms | VARCHAR\(255\) | yes | yes |
+| type | purpose | SQL | closed | eq |
+| :--------------- | :-------------------------------------------------------------------------------- | :------------- | :----- | :-- |
+| ALPHANUMERIC | to represent strings of short length, i.e. less than 255 characters | VARCHAR\(255\) | yes | yes |
+| BIGALPHANUMERIC | to represent large strings of limited length, i.e. less than 64 kb | TEXT | no | yes |
+| HUGEALPHANUMERIC | to represent strings of arbitrary length | MEDIUMTEXT | no | no |
+| PASSWORD | to represent passwords in a secure way | VARCHAR\(255\) | no | yes |
+| BINARY | to represent uninterpreted binary data of short length | BLOB | no | no |
+| BIGBINARY | to represent large binary data of limited length | MEDIUMBLOB | no | no |
+| HUGEBINARY | to represent large binary data of arbitrary length | LONGBLOB | no | no |
+| DATE | to represent dates compatible with ISO8601 | DATE | yes | yes |
+| DATETIME | to represent timestamps compatible with ISO8601 | DATETIME | yes | yes |
+| BOOLEAN | to represent True and False values | BOOLEAN | yes | yes |
+| INTEGER | to represent positive and negative whole numbers in the range \[-2^63..2^63 -1\] | BIGINT | yes | yes |
+| FLOAT | to represent floating-point numbers compatible with ISO8601 | FLOAT | no | no |
+| Object | to represent a key value for objects; it is not meant to be visible to end-users. | VARCHAR\(255\) | yes | yes |
+| | all other atoms | VARCHAR\(255\) | yes | yes |
The last column, eq, tells whether Ampersand implements equality on these types. If equality is not defined, the operators `\/`, `/\`, `-`, `\`, `/`, `;`, and `<>` cannot be used.
The distinction between closed and open types is relevant in the following situations:
-* The complement of a relation, `-r[A*B]`, is defined only if both `A` and `B` are closed.
-* The full relation, `V[A*B]` is defined only if both `A` and `B` are closed.
-* A service `INTERFACE X : e` requires that the target of `e` is closed.
+- The complement of a relation, `-r[A*B]`, is defined only if both `A` and `B` are closed.
+- The full relation, `V[A*B]` is defined only if both `A` and `B` are closed.
+- An interface `INTERFACE X : e` requires that the target of `e` is closed.
Violations are currently signaled at runtime, but future versions of Ampersand will signal these violations at compile time.
## Miscellaneous
-* Every atom whose atomic type is marked "yes" in the column "eq" can be compared for equality. For all other atoms, equality is not defined.
-* The following Ampersand statement declares the atomic type of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement):
+- Every atom whose atomic type is marked "yes" in the column "eq" can be compared for equality. For all other atoms, equality is not defined.
+- The following Ampersand statement declares the atomic type of a [concept](./syntax-of-ampersand#the-concept-statement):
```text
REPRESENT <Concepts> TYPE <Atomic type>
@@ -69,4 +69,3 @@ Violations are currently signaled at runtime, but future versions of Ampersand w
```
If `Person` and `Company` are both `LegalEntity`, then both of them will be implicitly declared as `ALPHANUMERIC` too.
-
diff --git a/docs/configuring-your-application.md b/docs/reference-material/configuring-your-application.md
similarity index 83%
rename from docs/configuring-your-application.md
rename to docs/reference-material/configuring-your-application.md
index 7ea5af0761..5effb2498c 100644
--- a/docs/configuring-your-application.md
+++ b/docs/reference-material/configuring-your-application.md
@@ -16,7 +16,6 @@ The file localSettings.php contains code and switches to be used in the client-s
6. a switch `productionEnv` to switch between development and production mode
7. database credentials for the application to log into the database
8. a switch loginEnabled to allow logging into the system
-9. a variable `allowedRolesForImporter` to specify roles with access to the [Excel importer](the-excel-importer.md).
-10. runtime parameters for the [Exec engine](architecture-of-an-ampersand-application/extensions/the-execengine.md).
-11. runtime parameters for extensions such as OAuth.
-
+9. a variable `allowedRolesForImporter` to specify roles with access to the [Excel importer](../the-excel-importer.md).
+10. runtime parameters for the [Exec engine](architecture-of-an-ampersand-application#the-execengine).
+11. runtime parameters for extensions such as OAuth.
\ No newline at end of file
diff --git a/docs/reference-material/the-language-ampersand/context.md b/docs/reference-material/context.md
similarity index 52%
rename from docs/reference-material/the-language-ampersand/context.md
rename to docs/reference-material/context.md
index b7306c5e0b..38bca67437 100644
--- a/docs/reference-material/the-language-ampersand/context.md
+++ b/docs/reference-material/context.md
@@ -13,15 +13,15 @@ As facts are true statements, we say that facts must exist inside a context.
Examples of contexts:
-* a single lawsuit in which all case data is contained;
-* the financial administration of a repair shop;
-* the life insurance department of a bank.
+- a single lawsuit in which all case data is contained;
+- the financial administration of a repair shop;
+- the life insurance department of a bank.
The world is full of contradictions. Examples:
-* Bob's personal income over March 2013 according to Bob's employer differs from Bob's personal income over March 2013 according to the National Tax Authority. \(To resolve this, we must distinguish between the context of Bob's employer and the context of the National Tax Authority.\)
-* The police can be convinced that Peter X commited the crime, yet his attorney is convinced he is innocent. \(To make sense of the situation, a judge distinguishes the reasoning of the defense from the reasoning of the prosecution as different contexts. In fact, the judge will construct her own context to create the verdict \)
-* A computer system can tell that the person with social security number 721-07-4426 was born on April 27th, 1943, while the same computer system tells in another screen that this person was born on May 3rd, 1952. This is inconsistent, because every person has only one birth date. \(This situation should be reported as a software mistake.\)
+- Bob's personal income over March 2013 according to Bob's employer differs from Bob's personal income over March 2013 according to the National Tax Authority. \(To resolve this, we must distinguish between the context of Bob's employer and the context of the National Tax Authority.\)
+- The police can be convinced that Peter X commited the crime, yet his attorney is convinced he is innocent. \(To make sense of the situation, a judge distinguishes the reasoning of the defense from the reasoning of the prosecution as different contexts. In fact, the judge will construct her own context to create the verdict \)
+- A computer system can tell that the person with social security number 721-07-4426 was born on April 27th, 1943, while the same computer system tells in another screen that this person was born on May 3rd, 1952. This is inconsistent, because every person has only one birth date. \(This situation should be reported as a software mistake.\)
## [Syntax](https://github.com/AmpersandTarski/Ampersand/blob/development/src/Ampersand/Input/ADL1/Parser.hs) and meaning
@@ -53,19 +53,18 @@ Directly following the optional language definition, you can optionally specify
A context may contain different types of statements. The order of statements in a context is irrelevant for the software that Ampersand generates. However, the order is maintained when documentation is generated.
-| | |
-| :--- | :--- |
-| `<meta>` | a statement to provide metadata to a script, such as author, company, etc. |
-| `<pattern>` | a block of code that represents rules on a single and specific topic, at the user's discretion |
-| `<rule>` | a statement that declares a [rule](/ampersand/reference-material/syntax-of-ampersand#the-rule-statement) |
-| `<classify>` | a statement that specifies generalization/specialization of [concepts](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement) |
-| `<relation>` | a declaration of a relation, stating the existence of a [relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) within the context |
-| `<conceptDef>` | a description of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement), to document its meaning |
-| `<representation>` | a statement that defines the atomic type of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement) |
-| `<roleRule>` | a statement that makes a role responsible for satisfying a rule |
-| `<viewDef>` | a statement for presenting facts in a readable sentence |
-| `<service>` | a unit of code that can be run independently and specifies interaction with a user or a computer |
-| `<purpose>` | a statement to describe the [purpose](/ampersand/reference-material/syntax-of-ampersand#the-purpose-statement) of a context or a context element |
-| `<population>` | a statement that sums up the initial [population](/ampersand/reference-material/syntax-of-ampersand#the-population-statement) of a relation |
-| `<include>` | a statement to [include](/ampersand/reference-material/syntax-of-ampersand#the-include-statement) another file in the context |
-
+| | |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------- |
+| `<meta>` | a statement to provide metadata to a script, such as author, company, etc. |
+| `<pattern>` | a block of code that represents rules on a single and specific topic, at the user's discretion |
+| `<rule>` | a statement that declares a [rule](./syntax-of-ampersand#the-rule-statement) |
+| `<classify>` | a statement that specifies generalization/specialization of [concepts](./syntax-of-ampersand#the-concept-statement) |
+| `<relation>` | a declaration of a relation, stating the existence of a [relation](./syntax-of-ampersand#the-relation-statement) within the context |
+| `<conceptDef>` | a description of a [concept](./syntax-of-ampersand#the-concept-statement), to document its meaning |
+| `<representation>` | a statement that defines the atomic type of a [concept](./syntax-of-ampersand#the-concept-statement) |
+| `<roleRule>` | a statement that makes a role responsible for satisfying a rule |
+| `<viewDef>` | a statement for presenting facts in a readable sentence |
+| `<interface>` | a unit of code that can be run independently and specifies interaction with a user or a computer |
+| `<purpose>` | a statement to describe the [purpose](./syntax-of-ampersand#the-purpose-statement) of a context or a context element |
+| `<population>` | a statement that sums up the initial [population](./syntax-of-ampersand#the-population-statement) of a relation |
+| `<include>` | a statement to [include](./syntax-of-ampersand#the-include-statement) another file in the context |
diff --git a/docs/reference-material/the-language-ampersand/design-considerations.md b/docs/reference-material/design-considerations.md
similarity index 93%
rename from docs/reference-material/the-language-ampersand/design-considerations.md
rename to docs/reference-material/design-considerations.md
index bc8aa04481..2a225da6dc 100644
--- a/docs/reference-material/the-language-ampersand/design-considerations.md
+++ b/docs/reference-material/design-considerations.md
@@ -6,7 +6,7 @@ The design considerations of Ampersand are treated as principles, not as laws. I
An Ampersand context presents itself as a universe with constraints. This was chosen to allow for incremental development. Adding a constraint changes nothing to the semantics of other constraints.
-One example of this is found in the CRUD annotations: A service provides all possible CRUD-functions, which are constrained by CRUD annotations.
+One example of this is found in the CRUD annotations: An interface provides all possible CRUD-functions, which are constrained by CRUD annotations.
## No obligations
diff --git a/docs/reference-material/dictionary.md b/docs/reference-material/dictionary.md
new file mode 100644
index 0000000000..a69e163c69
--- /dev/null
+++ b/docs/reference-material/dictionary.md
@@ -0,0 +1,30 @@
+# The language Ampersand
+
+This page is a dictionary. It defines the words we use to talk about Ampersand. You can click on the words to navigate to its defining page.
+
+| Word | Meaning | Example | Purpose |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| [Atom](atoms.md) | an indivisible item. Watch [this clip](https://player.ou.nl/wowzaportlets/#!production/Cq0M1nv) to learn how we use the words atom, concept, and relation. | `"Peter"` | to represent a thing |
+| [Concept](./syntax-of-ampersand#the-concept-statement) | a name to categorize similar items | `Person` | |
+| Pair | two atoms: a source and a target atom | `("Ida",5)` | to state that two atoms are related |
+| [Relation](./syntax-of-ampersand#the-relation-statement) | a set of pairs that is identifyable in a context by its name and type | `r[A*B]` | to build true statements and store pairs persistently in an application |
+| [Rule](./syntax-of-ampersand#the-rule-statement) | a constraint, which is supposed to remain satisfied. | `r;s \|- t` | to provide meaning in a given context |
+| [Invariant](./syntax-of-ampersand#the-rule-statement) | a rule that remains satisfied at all times by forbidding violations or by automatically resolving them. | |
+| [Enforcement rule](./syntax-of-ampersand#the-enforce-statement) | a rule that remains satisfied at all times by automatically resolving its violations as they occur. | |
+| Process rule | a rule that remains satisfied only when the user resolves its violations. | |
+| satisfy | A rule is satisfied (in a context) if the data (in that context) do not cause any violation of that rule. | | to calculate violations at runtime helps users do the right things |
+| [Pattern](./syntax-of-ampersand#the-pattern-statement) | a set of rules | <p><code>PATTERN</code></p><p> <code>...</code></p><p><code>ENDPATTERN</code></p> | to gather rules that belong together for reusing them in different contexts |
+| [Population](./syntax-of-ampersand#the-population-statement) | a set of pairs in a context | `POPULATION r[A*B] CONTAINS [ ("Ida",5), ("Bob",1) ]` | to represent the facts (i.e. true statements) in an information system |
+| [Context](./syntax-of-ampersand#the-context-statement) | a population together with a set of rules that are satisfied by the population. | <p><code>CONTEXT</code></p><p> <code>...</code></p><p><code>ENDCONTEXT</code></p> | to maintain a consistent representation of a real life situation |
+| View | A set of pairs that can be shown to users in a particular formulation. | | to represent facts |
+| [Interface](./syntax-of-ampersand#the-interface-statement) | A structure meant for "the outside world" to communicate with the system and possibly change the population. | `INTERFACE Request FOR Customer` | to let "the outside world" communicate with the system in a given context and possibly change its population |
+| Multiplicity | A predefined property of a relation | `UNI`, `TOT`, `SUR`, `INJ` | to constrain a relation with predefined properties |
+| [Term](terms.md) | A combination of relations and operators that satisfy the Ampersand syntax | `r;s-t` | to express rules |
+| Operator | a symbol used in combining terms into other terms. | `-`, `~`, `\/`, `/\`, `-`, `;`, `\`, `/`, `\|-`, `=` | to express more complex rules. |
+| | | | |
+| [Specialization](./syntax-of-ampersand#the-classify-statement) | A rule that defines specialization between two (or more) concepts. | `CLASSIFY A ISA B` | To specify a building block for a classification hierarchy. |
+| Role | A name for a group of people | `ROLE Customer MAINTAINS paymentObligation` | to talk about users without having any users |
+
+Syntactic definitions are given where the underlying notions (e.g. rule, relation, pattern, etc.) are discussed. The metasyntax is singled out [on a separate page](how-to-read-syntax-statements.md). Because [terms](terms.md) are defined in relation algebra, their semantics are explained in various ways to suit the background of each individual reader. Terms are the only algebraically defined things.
+
+This section is organized by discussing each notion in isolation. Hyperlinks are added in the text to let the reader navigate on her own. The text is suitable for reference purposes, so there is no preferred order in reading.
diff --git a/docs/reference-material/how-to-read-syntax-statements.md b/docs/reference-material/how-to-read-syntax-statements.md
new file mode 100644
index 0000000000..3d8013d0be
--- /dev/null
+++ b/docs/reference-material/how-to-read-syntax-statements.md
@@ -0,0 +1,127 @@
+# Syntactical conventions
+
+This section is a reference for meta syntax, syntactical conventions, reserved words, etc.
+
+To keep this documentation readable, the documentation omits some details that we deem irrelevant for most Ampersand modelers. The definitive syntax definition is [the source code of the parser](https://github.com/AmpersandTarski/Ampersand/blob/master/src/Ampersand/Input/ADL1/Parser.hs), where all EBNF statements are fully detailed in comments.
+
+## How to read syntax statements
+
+Sometimes, in describing the syntax, we use EBNF-like notation with the following meaning:
+
+| Operator | meaning |
+| -------- | ----------------------------------- |
+| `<foo>?` | Zero or one occurrence of `<foo>` |
+| `<foo>+` | One or more occurrences of `<foo>` |
+| `<foo>*` | Zero or more occurrences of `<foo>` |
+
+## Syntactical Conventions
+
+## Symbols
+
+Ampersand has _reserved words_, such as `RELATION`, `CONTEXT`, `CONTAINS`. All reserved words are written in capital letters. They are introduced on the fly. You will find an exhaustive list of reserved words [here](## List of reserved words).
+
+Untyped atoms are written between double quotes, e.g. `"Peter"` or `"KD-686-D"`. If you want to introduce a double quote inside an atom, escape it with a backslash, e.g. `"the symbol \" is called double quote"`.
+Numeric atoms always start with a digit, e.g. `4711` or `75.88E3`. The boolean atoms are `TRUE` and `FALSE`. Dates and timestamps follow the Excel-syntax, e.g. ??? The atom `_SESSION` indicates the current user session, and is an instance of concept `SESSION`. It is used in interfaces.
+
+Brackets must always match. For terms, we use round brackets `(` and `)`. For populations and interfaces we use square brackets `[` and `]`.
+
+Constructs that contain Ampersand statements are contexts and patterns. They always come in pairs: `PATTERN` and `ENDPATTERN`, and `CONTEXT` and `ENDCONTEXT`.
+
+White space characters \(spaces, tabs, CRLF\) are meaningless. You can use them freely to layout your script in a way that helps you to recognize its structure.
+
+A comment on a single line starts with `--`. Everything after a `--` symbol is ignored until the line ends. Multiline comments are wrapped between comment brackets `{-` and `-}`. Multiline comments may be nested.
+
+Identifiers always start with a letter. Concepts start with a capital letter, as in `Person`, `Case`, `A`, and `Order`. Relation names start with a lower case letter, as in `contains`, `attr`, `sessionLogin`, or `r`.
+
+## Terms
+
+Terms specify calculations with relations. They combine relations with operators to produce new relations. There are unary and binary operators. Binary operators may require brackets to avoid ambiguity. To save writing unneccessary brackets, some precedence rules are in place.
+
+| operator category | precedence | operators |
+| :-------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| logic | 1 \(weakest\) | \|- \(subset\), `=` \(equal\) |
+| binary boolean | 2 | `\/` \(union\), `/\` \(intersect\), `-` \(difference\) |
+| binary relational | 3 | `;` \(composition\), `!` \(relational addition\), `\` \(right residual\), `/` \(left residual\), `<>` \(diamond operator\) |
+| unary prefix, unary postfix | 4 \(strongest\) | `-` \(complement\), `~` \(converse\) |
+
+Within an operator category, you must place brackets to disambiguate. E.g. `r/\s\/t` is not allowed. You have to write either `(r/\s)\/t` or `r/\(s\/t)`. Across categories, you may omit brackets because a higher precedence binds stronger. So `r;s\/t` means `(r;s)\/t`. \(Note that `(r;s)\/t` and `r;(s\/t)` have different meanings\). Associative operators \(`\/`, `/\`, `;`\) need not be disambiguated with brackets. So `r\/s\/t` and `(r\/s)\/t` and `r\/(s\/t)` all mean exactly the same.
+
+## List of reserved words
+
+Keywords in Ampersand are always written in CAPITALS.
+
+- Keywords for the main structure of the code
+ - [`CONTEXT`, `ENDCONTEXT`](./syntax-of-ampersand#the-context-statement)
+ - [`IN`, `ENGLISH`, `DUTCH`](./syntax-of-ampersand#language-support)
+ - [`INCLUDE`](./syntax-of-ampersand#the-include-statement)
+ - [`PATTERN`, `ENDPATTERN`](./syntax-of-ampersand#the-pattern-statement)
+ - [`CONCEPT`](./syntax-of-ampersand#the-concept-statement)
+- 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)
+ - [`POPULATION`, `CONTAINS`](./syntax-of-ampersand#the-population-statement)
+- Keywords for [rules](./syntax-of-ampersand#the-rule-statement)
+ - `RULE`
+ - `MESSAGE`
+ - `VIOLATION`
+ - `TXT`
+ - `SRC`
+ - `TGT`
+ - `I`
+ - `V`
+ - `ONE`
+ - `ROLE`
+ - `MAINTAINS`
+- Keywords for documentation
+ - [`PURPOSE`](./syntax-of-ampersand#the-purpose-statement)
+ - [`MEANING`](./syntax-of-ampersand#the-meaning-sub-statement)
+ - `META`
+ - `REF`
+ - `REST`
+ - `HTML`
+ - `LATEX`
+ - `MARKDOWN`
+- Keywords for [interfaces](./interfaces.md)
+ - `INTERFACE`
+ - `FOR`
+ - `LINKTO`
+ - `BOX`
+- Keywords for identities
+ - [`IDENT`](./syntax-of-ampersand#the-ident-statement)
+- Keywords for views
+ - `VIEW`
+ - `ENDVIEW`
+ - `DEFAULT`
+ - `TEMPLATE`
+ - `HTML`
+- Keywords for generalisations:
+ - [`CLASSIFY`](./syntax-of-ampersand#the-classify-statement)
+ - `ISA`
+ - `IS`
+- Keywords for TType:
+ - `REPRESENT`
+ - `TYPE`
+ - `ALPHANUMERIC`
+ - `BIGALPHANUMERIC`
+ - `HUGEALPHANUMERIC`
+ - `PASSWORD`
+ - `BINARY`
+ - `BIGBINARY`
+ - `HUGEBINARY`
+ - `DATE`
+ - `DATETIME`
+ - `BOOLEAN`
+ - `INTEGER`
+ - `FLOAT`
+ - `AUTOINCREMENT`
+- Reserved words for values of atoms:
+ - `TRUE`
+ - `FALSE` --for booleans
+ - `_SESSION`
+- Reserved words for concepts
+ - `ONE`
+ - `SESSION`
+- Experimental keywords:
+ - `SERVICE`
+ - `API`
diff --git a/docs/reference-material/interfaces.md b/docs/reference-material/interfaces.md
new file mode 100644
index 0000000000..c7c40ca4b3
--- /dev/null
+++ b/docs/reference-material/interfaces.md
@@ -0,0 +1,280 @@
+# Interfaces
+
+<!-- Purpose -->
+
+An interface is a component of an information system that exposes functionality and data from a [context](./syntax-of-ampersand#the-context-statement), to let users or information systems interact by creating, reading, updating, and deleting data.
+
+## Description
+
+An interface is a component of an information system. Its life starts when it is deployed and ends when it is pulled back. A typical instance is a user interface based on HTML-CSS that runs in a browser. But an application program interface \(API\) that serves other computers with web interfaces is a perfectly valid instance as well.
+
+The definition of an interface specifies which data is presented to which users. For every different use of the system a different interface can be defined. This may lead to a substantial amount of interfaces for large and complex systems. However, one device will show one interface only at any given moment in time.
+
+[This page] gives syntactic details of interfaces. Please find tutorial explanations [here](../tutorial/interfaces.md).
+
+## Example
+
+```text
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] cRud
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] cRuD
+ BOX <TABLE>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRUd
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
+```
+
+This example specifies three tabs. One shows students, one shows courses and one shows modules. This is what it looks like when run in a browser:
+
+
+
+## Syntax and Meaning {#syntax-of-interface-statements}
+
+This chapter gives the formal syntax of interfaces for the purpose of reference.
+
+An interface specification has the following structure. It is identical for user interfaces (`INTERFACE`) and application programming interfaces (`API`).
+
+```
+INTERFACE <name> <forRoles>? : <term> <crud>? <view>? <subinterface>?
+API <name> <forRoles>? : <term> <crud>? <view>? <subinterface>?
+```
+
+The name of an interface must be unique within the context. The term defines the atoms to which the interface can be applied. The (optional) crud annotation constrains the possible interactions a user can do. The (optional) views determine what the interface will look like. If no view is specified, the interface will look like the screenshot above. Finally the sub-interface contains all the contents, i.e. the fields, field names and the constraints on them.
+
+The hierarchy of boxes in an interface comes from the following (recursive) syntax of `<subinterface>`.
+
+A sub-interface may be defined on the spot (by `<boxKey> <box>`) or it may link to another interface to reuse its structure:
+
+```
+<subinterface> ::= <boxKey> <box>
+ | LINKTO ( INTERFACE | API ) <name>
+```
+
+The boxKey is meant to tell the front-end application what the interface looks like. The compiler uses templates to adapt an interface to specific needs regarding its HTML structure. Please read the [documentation of templates](./syntax-of-ampersand#layout-of-interfaces) for details.
+
+```
+<boxKey> ::= BOX '<' <htmlname> '>'
+ | BOX
+```
+
+If no htmlname is specified, Ampersand uses `BOX <FORM>` by default.
+
+A box is simply a list of interface items (`ifcItem`) separated by commas. Each interface item specifies a field in the interface or a sub-interface.
+
+```
+<box> ::= '[' <ifcItem> ( ',' <ifcItem> )* ']'
+```
+
+Each interface item has a label that must be unique within the box. After the colon there is either a term or a text. The term specifies which data is related to the field it specifies if it has no sub-interface. If it does, it specifies the atoms on which the box is applied.
+
+```
+<ifcItem> ::= <label> ':' <term> <crud>? <view>? <subinterface>?
+ | <label> ':' <text>
+```
+
+## Layout of user interfaces
+
+Ampersand is meant for back-end design. It offers no features for front-end design. For that purpose we advise you use contemporary front-end tools for web-based applications. Your Ampersand application is [designed to be adaptable](./architecture-of-an-ampersand-application), especially for this purpose.
+
+However, Ampersand offers a few layout features that let you place items. It has three built-in layout options, [colums](#table-layout), [rows](#forms-layout) and [tabs](#tabs-layout), which you can mix freely.
+
+<a name="table-layout"></a>
+
+### Table layout
+
+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.
+
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] cRud
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] cRuD
+ BOX <TABLE>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRUd
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
+```
+
+This interface shows three columns in the user interface, **Students**, **Course** and **Modules**. The first column is not readable, because the [CRUD annotation](#CRUD) blocks this column for reading. It would have shown students in each row, because the target of `V[SESSION*Student]`is `Student`. The second column shows courses in two columns, **Course** and **Modules**. The third column shows modules in three columns. This is what the user will see on the screen.
+
+
+
+<a name="forms-layout"></a>
+
+### ROW layout
+
+The row layout uses `BOX <FORM>` to instruct the front-end application to layout the user interface row by row. Here is an example of an interface, which uses the row layout on the top level.
+
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX <FORM>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <FORM>
+ [ "Student" : I[Student] CRUD
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] CRUD
+ BOX <FORM>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ ]
+```
+
+This interface shows three rows in the user interface, **Students**, **Course** and **Modules**. The first column shows students in each of its rows. Each student is shown in the column layout. The second row shows courses in two columns, **Course** and **Modules**. Please read about [templates](./syntax-of-ampersand#layout-of-interfaces) if you are curious which other ways of displaying information there are besides `BOX <FORM>`. Please read the [explanation of CRUD annotations](#CRUD) if you are curious about the CRUD annotations. This is what the user will see on the screen.
+
+
+
+<a name="tabs-layout"></a>
+
+### Tabs layout
+
+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.
+
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] CRUD
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] CRUD
+ BOX <TABLE>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRud
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
+```
+
+This interface shows three tabs in the user interface, **Students**, **Course** and **Modules**. Only one tab is shown at a time, to avoid cluttered data. This is what the user will see on the screen.
+
+
+
+We have discussed the `FORM`, `TABLE`, and `TABS` layout options. Please note that these options do not change the semantics; whatever your options, Ampersand displays the same data in the same fields.
+
+<a name="layout-and-widgets"></a>
+
+### Your own layout and your own widgets \(HTML and CSS\)
+
+You don't have to put up with the [Ampersand built-in layout options](./syntax-of-ampersand#layout-of-interfaces) if they don't suit your purpose. You can change most anything by including your own code snippets. \(to be done...\).
+
+## CRUD {#CRUD}
+
+CRUD annotations are used in interfaces to constrain the functionality of fields and boxes in an `INTERFACE`-statement. This allows you to minimize the functionality for your users, to design for easy learning.
+
+Each CRUD annotation comes right after a [term](./terms.md), so we can always refer to "the term" to which a CRUD annotation belongs. A CRUD annotation constrains the things your user can do with the target atoms and the pairs of its term.
+
+The CRUD-annotation specifies Create, Read, Update, and Delete rights for the term it follows. Capital = allowed, Non-capital = not allowed. CRUD is the default, so if you specify nothing, everything is allowed. The following interface definition illustrates this.
+
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] cRud
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] cRuD -- used for a box
+ BOX <TABLE>
+ [ "Course" : I cRud -- used for a field
+ , "Modules" : isPartOf~ -- CRUD is default
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRUd
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
+```
+
+The user interface defined by this interface is shown as a screenshot below. Notice that the lowercase r in the annotation of the Students box prevents showing the underlying box. The full CRUD functionality in Course yields 'create' functionality (the green plus-button), 'remove pair' functionality (red minus button), and 'delete atom' functionality (the red trash can button). The lowercase c, u, and d in the Modules box prevents displaying that functionality in the user interface.
+
+
+
+The next sections give some more detailed information on the run time semantics for CRUD annotations as implemented in Ampersand.
+
+### Create
+
+| CRUD | for a box | for a field. |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| C |  A + (plus) button is displayed that lets you create a new atom, but only if the box-expression is editable. |  Enter a new atom and a `+` button appears. Click the + to add that atom to the listed set of atoms. If you enter an atom that exists (Peter), you can select it. |
+| c | Atoms cannot be created | Atoms cannot be created |
+
+### Read
+
+| Read | CRUD for boxes | | CRUD for fields |
+| ---- | ------------------- | --- | ------------------- |
+| R | Read is allowed | | Read is allowed |
+| r | Read is not allowed | | Read is not allowed |
+
+### Update
+
+| Update | CRUD for boxes | CRUD for fields |
+| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| U |  Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. |  Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. |
+| u | Update is not allowed | Update is not allowed |
+
+### Delete
+
+| Delete | CRUD for boxes | CRUD for fields |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| D |  Deleting a pair is done with the - (minus) button. Deleting an atom is done with the trash bin. |  Delete atom (tgt) and all pairs in which it is used. |
+| d | delete not allowed | delete not allowed |
+
+A top-level Update or Create are common in my own scripts, e.g. to create an overview of People and be able to create a new Person: `INTERFACE "People" : V[SESSION*Person] CRud COLS []`. And update is also possible.
+
+### Things to remember
+
+1. The red minus is enabled by `U`. It unlinks an atom (by deleting a pair from a relation) and leaves the atom alone.
+2. The red trash bin is enabled by `D`. It removes an atom and all pairs in which that atom is used.
+
+### Background
+
+Motivations for CRUD-functionality are found in the [GitHub discussions on CRUD](https://github.com/AmpersandTarski/Ampersand/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Acrud+) functionality.
+
+## Using an interface
+
+On the user screen each atom is displayed in some form as data. If an interface exists for that atom, that is shown to the user as a hyperlink to which you can navigate.
+
+When running an application in your browser, you are watching one user interface at any given moment in time. Each hyperlink on your screen represents an atom to which some interface applies. To navigate to that user interface, you click on the hyperlink. You will see the interface being applied solely to the atom you just clicked. To determine the atom\(s\) to which an interface applies, each interface has an _interface term_.
+
+The next sections contain two examples:
+
+- a [client interface](../Examples.md#interfaces-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
+- a [login interface](../Examples.md#interfaces-example-login) to demonstrate how to get different interface structures under varying conditions.
diff --git a/docs/reference-material/syntactical-conventions/README.md b/docs/reference-material/syntactical-conventions/README.md
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/reference-material/syntactical-conventions/language-support.md b/docs/reference-material/syntactical-conventions/language-support.md
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/reference-material/syntax-of-ampersand.md b/docs/reference-material/syntax-of-ampersand.md
index aa7b5ec8a0..549191feed 100644
--- a/docs/reference-material/syntax-of-ampersand.md
+++ b/docs/reference-material/syntax-of-ampersand.md
@@ -1,119 +1,250 @@
---
title: Syntax of Ampersand
-id: syntax-of-ampersand
---
-# Syntax of ampersand
-This page is about the syntax of ampersand scripts.
+# Syntax and Semantics of Ampersand
+
+This page defines the syntax and semantics of the statements in the Ampersand language.
+[Terms](./terms.md) and [interfaces](./interfaces.md) are defined in separate pages.
+Please use it as a reference document rather than an introductory course.
+
+## Structuring your Ampersand specification
+
+Structuring an Ampersand specification effectively is crucial for readability, maintainability, and ease of development. There are several ways that can help:
+
+1. `Include` statements enable you to use multiple files. This can help to separate your statements by concerns.
+2. `Pattern`s can help to devide your rules etc. by theme. The generated documentation takes this into account.
+
+Not all statements can be used inside a Pattern. This table shows what elements are available inside a Pattern and inside a Context:
+
+| element | description | Context | Pattern |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------- | ------- |
+| [<include\>](#the-include-statement) | a statement to include another file in the context | ✅ | ❌ |
+| <meta\> | a statement to provide metadata to a script, such as author, company, etc. | ✅ | ❌ |
+| [<pattern\>](#the-pattern-statement) | a block of code that represents rules on a single and specific topic, at the user's discretion | ✅ | ❌ |
+| [<conceptDef\>](#the-concept-statement) | a description of a concept, to document its meaning | ✅ | ✅ |
+| [<representation\>](#the-concept-statement | a statement that defines the atomic type of a concept | ✅ | ✅ |
+| [<classify\>](#the-classify-statement) | a statement that specifies generalization/specialization of concepts | ✅ | ✅ |
+| [<relation\>](#the-relation-statement) | a declaration of a relation, stating the existence of a relation within the context | ✅ | ✅ |
+| [<rule\>](#the-rule-statement) | a statement that declares a rule | ✅ | ✅ |
+| <roleRule\> | a statement that makes a role responsible for satisfying a rule | ✅ | ✅ |
+| [<enforce\>](#the-enforce-statement) | a statement to declare an automatic enforcement rule | ✅ | ✅ |
+| [<ident\>](#the-ident-statement) | a declaration of an identity rule on a concept | ✅ | ✅ |
+| <viewDef\> | a statement for presenting facts in a readable sentence | ✅ | ✅ |
+| [<purpose\>](#the-purpose-statement) | a statement to describe the purpose of a pattern or a pattern element | ✅ | ✅ |
+| [<population\>](#the-population-statement) | a statement that sums up the initial population of a relation | ✅ | ✅ |
+| [<interface\>](#the-interface-statement) | a unit of code that can be run independently and specifies interaction with a user or a computer | ✅ | ❌ |
+| [<purpose\>](#the-purpose-statement) | a statement to describe the purpose of a context or a context element | ✅ | ✅ |
+| [<population\>](#the-population-statement) | a statement that sums up the initial population of a relation | ✅ | ✅ |
-## The CONCEPT statement
+## The CONTEXT statement
-### Purpose:
+#### Purpose
-A concept statement defines a concept in natural language. A concept is a name for similar things. For example: `Peter`, `John`, and `Barack` are things you might want to call `Person`, whereas `45-NP-88` and `KD-686-D` could be instances of the concept `LicensePlate`.
+The data contained in a business system represents a view of \(a very small part of\) the real world. Ideally, this view must be consistent, meaning that there may be no contradictions within that view. Since different business systems have different ways of viewing the real world, and/or look at different parts of the real world, we need to be able to distinguish between such views. We use the word 'Context' to refer to an individual view. Thus, a Context is defined in terms of concepts, relations and rules, and it consists of atoms and links to populate them.
+
+#### Semantics
+
+Any Ampersand model has one context.
+The model is true within its context and there is no knowledge in a model about other contexts.
+
+#### Syntax
-### Syntax:
+The model is specified between the keywords CONTEXT and ENDCONTEXT. A context has a name. You can optionally specify the language and markup \(see below\).
```text
-CONCEPT <Uppercase identifier> <String> <String>?
+CONTEXT MyModel
+INCLUDE*
+
+<all kind of elements in the model>
+
+ENDCONTEXT
```
-This statement may occur anywhere within a context, either inside or outside a pattern.
+Other models included with the INCLUDE statement become part of the context they are included in.
-### Semantics
+###### Optional parts
-This statement means that there exists a concept called `<Uppercase identifier>` in the current context.
+######### Language definition
-* `<Uppercase identifier>` specifies the name of the concept.
-* `String` contains a definition of the concept. This definition is used by the documentation generator, which expects it to be a grammatically correct and complete sentence.
-* `String?` is an \(optional\) reference to the source of the definition. It is meant for traceability.
+To tell Ampersand what language your context is in, you can append a language directive to your context. Currently English and Dutch are supported. To do so, directly following the name of your context, you can specify
-### Examples
+```text
+IN <language>
+```
+
+Where `<language>` can be `ENGLISH` or `DUTCH`.
+
+######### Markup format
+
+Directly following the optional language definition, you can optionally specify the format of your texts \(see PURPOSE statement\). Ampersand understands some different markup styles. The default style is REST \(Restructured Text\)
```text
-CONCEPT Person "A person is a human creature." "Ventroli1997"
+<markupStyle>
```
+where can be one of
+
+`REST`,
+
+`HTML`,
+
+`LATEX`,
+
+`MARKDOWN`.
+
+\(For details on these formats, see [pandoc.org](http://pandoc.org/)\).
+
+## The INCLUDE statement
+
+#### Purpose
+
+To facilitate reusing code, Ampersand allows its user to divide code over different files.
+
+#### Description
+
+The `INCLUDE`-statement includes the code of another Ampersand-script or the data of a .xlsx-file into the context.
+
+#### Examples
+
```text
-CONCEPT Organization "An organization is a collection of persons that work together to achieve specific objectives."
+INCLUDE "foo.adl"
+INCLUDE "subdirectory/foo.adl"
+INCLUDE "bar.xlsx"
```
+#### Syntax and meaning
+
```text
-CONCEPT Criterion "A criterion is a standard on which a judgment or decision may be based." "Merriam-Webster"
+INCLUDE <filename>
```
-### Miscellaneous
+This statement specifies files that need to be included before compiling. The filename is given in double quotes, including a path that is relative to the position of the main adl-file. The main adl-file is the file that is called with the command Ampersand.
-* The name of a concept starts with an uppercase.
-* A concept should be used for immutable concepts. E.g. use a concept `Person` to express that a person will always be a person and will not change in, let us say, a table. However, don't use `Employee`, because termination of an employee's contract causes a person to be an employee no longer. So employees are not immutable. To be an employee is a dynamic property, so model it as a relation.
-* The description will be printed in the functional specification, so please check that your definition is a complete sentence.
-* Concepts need not be defined. If you use a concept without a definition, Ampersand defines it for you \(regardless of whether you defined it or not\).
+Possible files to include are:
-## The CONTEXT statement
+- other adl-files
+- xlsx-files to include population
-### Purpose
+All code in the included adl-files will become part of the context of the main adl-file.
-The data contained in a business system represents a view of \(a very small part of\) the real world. Ideally, this view must be consistent, meaning that there may be no contradictions within that view. Since different business systems have different ways of viewing the real world, and/or look at different parts of the real world, we need to be able to distinguish between such views. We use the term 'Context' to refer to an individual view. Thus, a Context is defined in terms of concepts, relations and rules, and it consists of atoms and links to populate them.
+Make sure to include the adl-files before including xlsx-files.
-### Semantics
+Included files may contain `INCLUDE`statements themselves. The files mentioned there are treated as though they were included in the main file. So their code is also part of the same context. Nested adl-files can have their own xlsx-files included.
-Any Ampersand model has one context.
-The model is true within its context and there is no knowledge in a model about other contexts.
+For formatting your excel-file see the text on [the Excel Importer](../the-excel-importer.md).
-### Syntax
+## The PATTERN statement
-The model is specified between the keywords CONTEXT and ENDCONTEXT. A context has a name.
+#### Purpose
-```text
-CONTEXT MyModel
-INCLUDE*
+Patterns are meant to isolate discussions and make solutions reusable, as known from [design patterns](http://en.wikipedia.org/wiki/Design_pattern).
-<all kind of elements in the model>
+#### Description
+
+A pattern is a set of rules that describes a theme or a general reusable solution to a commonly occurring problem.
+
+For instance, if specific concerns about security arise, you might want to discuss this with stakeholders in security. With them you can discuss which rules in particular constitute your solution. Divide your problem in smaller pieces and discuss each piece with just the right stakeholders. This allows you to go deeper by talking to the right people. It saves time as well by freeing others from having to participate. An even larger benefit arises if you reuse patterns that have been discussed and scrutinized before. The best thing comes once your stakeholders agree. By that time, your pattern represents their agreement formally in Ampersand, so you can use it in the larger context of the information system.
+
+#### Example
-ENDCONTEXT
```
+PATTERN Security
-Other models included with the INCLUDE statement become part of the context they are included in.
+RELATION required[Subject*Destination]
+MEANING "A subject that you must have passed to qualify for the school trip to a destination"
-#### Optional parts
+RELATION pass[Subject*Student]
+MEANING "The subjects that have been passed by specific students"
-##### Language definition
+RELATION attends[Student*Destination]
-To tell Ampersand what language your context is in, you can append a language directive to your context. Currently English and Dutch are supported. To do so, directly following the name of your context, you can specify
+PURPOSE RULE guardPrerequisites
+{+ This rule prevents students from registering for a trip
+without having passed the required courses. +}
+RULE guardPrerequisites : attends;required |- pass
-```text
-IN <language>
+ENDPATTERN
```
-Where `<language>` can be `ENGLISH` or `DUTCH`.
+#### Syntax
-##### Markup format
+Every pattern has the following form:
-Directly following the optional language definition, you can optionally specify the format of your texts \(see PURPOSE statement\). Ampersand understands some different markup styles. The default style is REST \(Restructured Text\)
+```
+PATTERN <pattern name>
+ <pattern element>*
+ENDPATTERN
+```
+
+#### Good practice
+
+A model can have as many patterns as you want.
+It has no effect on how the code is processed.
+
+The interface definition must be outside a pattern
+
+A pattern contains rules in an arbitrary order.
+The context in which these rules are valid must contain the definition for each of the relations that are used in those rules.
+It is good practice to declare all relations in the pattern itself.
+That practice makes the pattern self-contained and therefore more suitable for reuse.
+
+Ampersand advocates **one theme in one pattern**. Stakeholders confine their discussion to one theme, and deliver the result in one pattern.
+
+#### Restrictions
+
+In the current implementation of Ampersand, patterns are defined within a context. (This will change in a future version.) If you want to reuse patterns, you have to cut-and-paste them from one context to another. In the future, there will be a better mechanism for reusing patterns in different contexts.
+
+## The CONCEPT statement
+
+#### Purpose:
+
+A concept statement defines a concept in natural language. A concept is a name for similar things. For example: `Peter`, `John`, and `Barack` are things you might want to call `Person`, whereas `45-NP-88` and `KD-686-D` could be instances of the concept `LicensePlate`.
+
+#### Syntax:
```text
-<markupStyle>
+CONCEPT <Uppercase identifier> <String> <String>?
```
-where can be one of
+This statement may occur anywhere within a context, either inside or outside a pattern.
-`REST`,
+#### Semantics
-`HTML`,
+This statement means that there exists a concept called `<Uppercase identifier>` in the current context.
-`LATEX`,
+- `<Uppercase identifier>` specifies the name of the concept.
+- `String` contains a definition of the concept. This definition is used by the documentation generator, which expects it to be a grammatically correct and complete sentence.
+- `String?` is an \(optional\) reference to the source of the definition. It is meant for traceability.
-`MARKDOWN`.
+#### Examples
-\(For details on these formats, see [pandoc.org](http://pandoc.org/)\).
+```text
+CONCEPT Person "A person is a human creature." "Ventroli1997"
+```
+
+```text
+CONCEPT Organization "An organization is a collection of persons that work together to achieve specific objectives."
+```
+
+```text
+CONCEPT Criterion "A criterion is a standard on which a judgment or decision may be based." "Merriam-Webster"
+```
+
+#### Miscellaneous
+
+- The name of a concept starts with an uppercase.
+- A concept should be used for immutable concepts. E.g. use a concept `Person` to express that a person will always be a person and will not change in, let us say, a table. However, don't use `Employee`, because termination of an employee's contract causes a person to be an employee no longer. So employees are not immutable. To be an employee is a dynamic property, so model it as a relation.
+- The description will be printed in the functional specification, so please check that your definition is a complete sentence.
+- Concepts need not be defined. If you use a concept without a definition, Ampersand defines it for you \(regardless of whether you defined it or not\).
## The CLASSIFY statement
-### Purpose
+#### Purpose
A _**classify statement**_ is also called a _**specialization**_. It specifies that atoms of one concept are atoms of another concept as well. You can use it to buils classifications like [Linnaeus](https://www.britannica.com/science/taxonomy/The-Linnaean-system) did.
-### Syntax and meaning
+#### Syntax and meaning
```
CLASSIFY <upper case identifier> ISA <upper case identifier>
@@ -121,9 +252,9 @@ CLASSIFY <upper case identifier> ISA <upper case identifier>
In a specialization, e.g. `CLASSIFY Sedan ISA Car`, we call the first concept (`Sedan`) the specific concept and the second (`Car`) the generic concept. The meaning of a specialization is that every atom from the specific concept is an atom from the generic concept as well. So every (atom that is a) Sedan is a Car as well.
-So in general: `CLASSIFY` $$A$$ `ISA` $$B$$ means: $$\forall a: a\in A\Rightarrow a\in B$$.
+So in general: `CLASSIFY` $$A$$ `ISA` $$B$$ means: $$\forall a: a\in A\Rightarrow a\in B$$.
-### Examples
+#### Examples
```
CLASSIFY Monkey ISA Mammal
@@ -133,8 +264,6 @@ CLASSIFY Monkey ISA Mammal
CLASSIFY Sedan ISA Car
```
-
-
To save some writing, you may specify
```
@@ -149,25 +278,267 @@ CLASSIFY Cow ISA Mammal
CLASSIFY Human ISA Mammal
```
-### Best practice
+#### Best practice
A specialization is a static relationship. If you want to say that a student is a person, please consider whether you want this to be static. If a person can enroll to become a student, or graduate or drop out to become non-student again, the dynamics of that cannot be captured in a specialization. Use a relationship instead to model the state of being a student. \
E.g. `RELATION student[Person*Enrollment]`
By adding and removing pairs to that relation, it continuously reflects which persons are a student.
-## The ENFORCE statement
+## The RELATION statement
+
+#### Purpose
+
+A _**relation statement**_ says that a relation exists. It introduces (defines, declares) the relation in the context that uses the relation statement.
+
+A _**population statement**_ specifies which pairs (of atoms) are in a relation.
+
+#### Description
+
+A relation is a set that contains pairs of atoms. Over time, pairs can be inserted into or deleted from a relation, for example by a user typing data into an Ampersand application. So the content of a relation is changing over time.
+
+When discussing relations, an arbitrary relation is referred to as $$r$$, $$s$$, or $$t$$. To say that a pair $$(a,b)$$ belongs to a relation $$r$$, we write $$a\ r\ b$$ or alternatively $$(a,b)\in r$$.
+
+#### Examples
+
+```
+RELATION soldBy[Order*Person]
+```
+
+```
+RELATION contract[Order*ContractID] [UNI,TOT]
+PRAGMA "Order " " has contract " " as its legal basis."
+MEANING
+{+ Every Order has a unique ContractID which specifies the legal basis
+ for that particular order.
++}
+```
+
+In this example:
+
+- `contract` is the _**name**_ of the relation,
+- `Order` is the _**source concept**_ of the relation,
+- `ContractID` is the _**target concept**_ of this relation, and
+- `UNI` and `TOT` are _**constraints**_ of this relation.
+
+#### Syntax and meaning
+
+Each relation used in Ampersand has to be declared. This means that the developer tells the system that this particular relation exists. A relation declaration can have one of the following formats:
+
+```
+RELATION <lower case identifier>
+ '[' <upper case identifier> '*' <upper case identifier> ']'
+ <properties>? <pragma>? <meaning>?
+```
+
+In the _**declaration**_ `RELATION owner[Person*Building]`, `owner` is the _**name**_ and `[Person*Building]` is the _**type**_ of the relation. Relation names start with a lower case character, to avoid confusion with concept names. The _**signature**_ of this relation is `owner[Person*Building]`. The signature identifies the relation within its context. The left hand concept, `Person`, is called the _**source**_ of the relation and the right concept, `Building`, is called the _**target**_.
+
+All three formats define a relation by its name, its source concept and its target concept. By convention, the name of a relation is a single word that starts with a lower case letter. The source and target concepts start with an upper case letter. This convention avoids confusion between concepts and relations.
+
+A relation statement means that there exists a relation in the current context with the specified name, source concept and target concept.
+
+A relation statement may occur anywhere inside a context, both inside and outside a pattern.
+
+The optional `<properties>` and `<pragma>`-parts are discussed in the sequel. The `<meaning>`-part is discussed [here](#the-meaning-substatement\).
+
+The name, source concept and target concept together identify a relation uniquely within its context. As a consequence, the name of a relation does not have to be unique. E.g. `name[Book*Name]` can be specified in the same context as `name[Person*Name]`. Because they have different source concepts, these are different relations.
+
+#### Properties
+
+The `<properties>`-part is meant for writing multiplicity constraints in a comma separated list between square brackets '\[' and ']'. E.g. `[UNI,TOT]` . The following properties can be specified on any relation `r[A*B]`
+
+| & | property | semantics |
+| --- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| UNI | univalent | For any `a` in `A` there can be not more than one `b` in `B` in the population of `r`. This implies that every `a` occurs not more than once (is unique) in the source of `r`. |
+| 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`. |
+
+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]`.
+
+| & | property | semantics |
+| ---- | ------------- | ------------------------------------------------------------------------- |
+| SYM | symmetric | For each (`a`,`b`) in `r`, (`b`,`a`) is in `r`. |
+| ASY | antisymmetric | If (`a`,`b`) and (`b`,`a`) are both in `r`, then `a` = `b` |
+| 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. |
+
+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.
+
+In relation algebra, we say that the relation is univalent, which means that every atom in the source concept can only be paired with a single atom in the target concept. This is modeled as
+
+```
+RELATION lives[Person*City][UNI]
+MEANING "A person can live in one city only."
+```
+
+#### PRAGMA
+
+A pragma is optional and is characterized by the reserved word `PRAGMA`. The `PRAGMA` is followed by two or three strings. It is used to construct sentences in natural language, using pairs from the actual population of a relation. A pragma specifies how we speak (in natural language) about any pair in the relation. Ampersand also uses pragmas to generate examples in the functional specification. Example of a pragma with three strings:
+
+```
+PRAGMA "Student " " flies the flag of " " in top."
+```
+
+To use this pragma on the pair `(John,Amsterdam)` results in the sentence `"Student John flies the flag of Amsterdam in top."`. The two atoms are fitted in between the three strings. A pragma with two strings is identical to a pragma in which the third string is empty.
+
+(The `PRAGMA` keyword will become obsolete in a future version of Ampersand. It will be replaced by the `VIEW`-statement which offers more flexibility in composing sentences.)
+
+Example:
+
+```
+RELATION accepted[Provider * Order] [INJ] PRAGMA "Provider " " has accepted order "
+```
+
+The `PRAGMA` tells us that it makes sense to utter the phrase `"Provider Mario's Pizza's has accepted order 12345."`
+
+#### MEANING
+
+For a full discussion of meaning, we refer to [`this page`](#the-meaning-substatement\).
+
+#### Miscellaneous
+
+-
+
+## The RULE statement
+
+#### Purpose
+
+The purpose of a rule is to constrain data. Refer to the chapter about rules in the tutorial for examples and a practice oriented explanation.
+
+A rule statement defines something that should be true. It does not define the enforcement.
+
+#### Syntax of rules
+
+A `<rule>` has the following syntax:
+
+```text
+RULE <label>? <term> <meaning>* <message>* <violation>?
+```
+
+#### Syntax of labels
-### Purpose
+A `<label>` is optional. It can be a single word or a string \(enclosed by double brackets\) followed by a colon \(`:`\).
+
+###### Term
+
+A term can be any of:
+
+- Term BinaryOperator Term
+- UnaryOpPre Term
+- Term UnaryOpPost
+- a \(reference to a\) relation \(including an optional signature, when required to disambiguate\):
+ - A relation by name
+ - `I` \(the Identity relation\)
+ - `V` \(carthesian product\) Note that this can also be used to denote the empty relation, by using the unary negation operator: '-v'
+ - A singleton term \(the value of an atom\)
+- a term enclosed in brackets.
+
+The [semantics of terms](./terms) is documented in a separate page.
+
+######### Operators
+
+The following operators are available to build expressions:
+
+- Binary operators
+ - equivalence: `=`
+ - composition: `;`
+ - inclusion: `|-`
+ - intersection: `/\`
+ - union: `\/`
+ - difference: `-`
+ - left residual: `/`
+ - right residual: `\`
+ - diamond: `<>`
+ - relative addition: `!`
+ - cartesian product: `#`
+- Unary operator \(pre-operator\)
+ - complement: `-`
+- Unary operators \(post-operator\)
+ - conversion \(flip\): `~`
+ - Reflexive, transitive closure: `*` \(Kleene star\) --currently not implemented
+ - transitive closure: `+` \(Kleene plus\) --currently not implemented
+
+###### MEANING\*
+
+The meaning of a rule can be written in natural language in the Meaning part of the RULE statement.
+It is a good habit to specify the meaning! The meaning will be printed in the functional specification.
+The meaning is optional.
+
+######### Syntax
+
+```text
+MEANING Language? Markup? <text>
+```
+
+The `<text>` part is where the the meaning is written down. We support both:
+
+- a simple string, enclosed by double quotes
+- any text, starting with `{+` and ending with `-}`
+
+The optional language is specified as
+
+- `IN ENGLISH` or
+- `IN DUTCH`.
+
+The optional Markup is one of :
+
+- `REST` \(Restructured text\)
+- `HTML`
+- `LATEX`
+- `MARKDOWN`
+
+If you need specific markup, there are several options to do so. The default markup is used, but you can override that here. We rely on [Pandoc](http://pandoc.org/) to read the markup.
+
+###### MESSAGE\*
+
+Messages may be defined to give feedback whenever the rule is violated. The message is a predefined string. Every message for a rule should be for another Language.
+
+```text
+MESSAGE Markup
+```
+
+###### VIOLATION?
+
+A violation message can be constructed so that it gives specific information about the violating atoms:
+
+```text
+VIOLATION (Segment1,Segment2,... )
+```
+
+Every segment must be of one of the following forms:
+
+- `TXT` String
+- `SRC` Term
+- `TGT` Term
+
+A rule is violated by a pair of atoms \(source, target\). The source atom is the root of the violation message. In the message the target atoms are printed. With the Identity relation the root atom itself can be printed. You can use a [term](./terms) to print other atoms.
+The two examples below define a violation of the rule that each project must have a project leader.
+The first prints the project's ID, the second the project's name using the relation projectName:
+
+`VIOLATION ( TXT "Project ", SRC I, TXT " does not have a projectleader")`
+
+`VIOLATION ( TXT "Project ", SRC projectName, TXT " does not have a projectleader")`
+
+#### ROLE MAINTAINS
+
+By default rules are invariant rules.
+By preceding the rule statement with a role specification for this rule, the rule becomes a process rule.
+
+## The ENFORCE statement {#the-enforce-statement}
+
+#### Purpose
The purpose of this statement is to automatically modify the population of a relation based on rules.
-### Syntax
+#### Syntax
Since ampersand 4.4.0 the syntax of this statement is:
```
-ENFORCE <RelationRef> <type>?
+ENFORCE <RelationRef> <type>?
<operator>
<Term>
```
@@ -176,11 +547,11 @@ The `<operator>` can be one of **`:=`,** `:<` or `>:` .
This statement may occur anywhere within a context, either inside or outside a pattern.
-### Semantics
+#### Semantics
-This statement means the population of the relation will automatically be kept respectively equal ( **`:=`**), a subset (`:<`) or a superset (`>:`) of the population of the given term.
+This statement means the population of the relation will automatically be kept respectively equal ( **`:=`**), a subset (`:<`) or a superset (`>:`) of the population of the given [term](./terms).
-### Examples
+#### Examples
```
ENFORCE r := s;t
@@ -198,20 +569,19 @@ ENFORCE canDrive :< hasCar /\ hasDriverLicence
It will do so by deleting pairs from the contents of canDrive
without affecting the contents of hasCar /\ hasDriverLicence .
So, whenever a person can drive, that person needs to have a car and a driver licence.
- However, if that person has both these assets, it is still possible that he/she
- cannot drive.
+ However, if that person has both these assets, it is still possible that he/she
+ cannot drive.
-}
```
-### Miscellaneous
+#### Miscellaneous
-* Both the sources and the targets of the relation and the term must match. An error message is given otherwise.
-* The relation must be specified in order to use it here, as is the case with any relation used in a term.
+- Both the sources and the targets of the relation and the term must match. An error message is given otherwise.
+- The relation must be specified in order to use it here, as is the case with any relation used in a term.
## The IDENT statement
-
-### Purpose:
+#### Purpose:
This statement is a rule, which defines an identity on a concept. It is syntactic sugar for specifying a set of relations that identify atoms in a specific concept. For example, if relations `pi` and `rho` determine an atom of concept `T` uniquely, you can write:
@@ -221,7 +591,7 @@ IDENT "T uniqueness" : T (pi, rho)
As the IDENT statement defines a rule, it can be in the same places as any other RULE.
-### Syntax
+#### Syntax
```text
`IDENT` (<label> `:`)? <Concept> `(` <term>* `)`
@@ -229,11 +599,11 @@ As the IDENT statement defines a rule, it can be in the same places as any other
where:
-* `<label>` is the name of the rule. It can be a single word or a string \(enclosed by double brackets\). It is followed by a colon \(`:`\) to distinguish the label from the concept that follows.
-* `<Concept>` is the name of the Concept for atoms of which the rule specifies an identity
-* Between brackets are terms whose source concept must be `<Concept>`. This is enforced by the type system.
+- `<label>` is the name of the rule. It can be a single word or a string \(enclosed by double brackets\). It is followed by a colon \(`:`\) to distinguish the label from the concept that follows.
+- `<Concept>` is the name of the Concept for atoms of which the rule specifies an identity
+- Between brackets are [terms](./terms) whose source concept must be `<Concept>`. This is enforced by the type system.
-### Informal Semantics
+#### Informal Semantics
```text
IDENT "Rule Name" : C (e1, e2, ...)
@@ -247,235 +617,710 @@ translates into the following rule:
Note that
-* in case every`e`is both univalent and total, `e<>e~` equals `e;e~`, and the rule is equivalent to:
+- Since for every `e` that is univalent and total `e<>e~` equals `e;e~`, so if `e1`, `e2`, ... are all univalent and total, the rule is equivalent to:
+
+ ```text
+ RULE "Rule Name": {e1};{e1}~ /\ {e2};{e2}~ /\ ... |- I[C]
+ ```
+
+- in case every `e` is univalent but not total, you should use the `IDENT` statement \(or the rule that it implements\), because that also works when an `e` is not populated.
+
+## The POPULATION statement
+
+#### Purpose
+
+To store data in a database corresponds to populating the relations in a context. Atoms are the data and pairs of atoms are inserted and deleted during the lifetime of a relation.
+
+#### Description
+
+All pairs in a relation are called the population of that relation. All atoms in a concept constitute the population of that concept. The population of all relations and concepts in a context make the population of that context.
+
+There are two ways to populate a concept with atoms:
+
+- A `POPULATION` statement defines the initial population of a concept or a relation.
+- An `INCLUDE` statement defines the initial population from an xlsx-file \(i.e. an Excel speadsheet\)
+
+[Using spreadsheets](#population-in-spreadsheets) to define an initial population allows you to work with larger populations. Often you can use an existing spreadsheet and adapt it to become acceptable as Ampersand input.
+
+#### Syntax
+
+You can define atoms separately and you can define the pairs in a relation. Both methods result in added population for each concept.
```text
- RULE "Rule Name": {e1};{e1}~ /\ {e2};{e2}~ /\ ... |- I[C]
+POPULATION Tree CONTAINS
+ [ "Oak"
+ , "Birch"
+ , "Willow"
+ ]
```
-* in case every `e` is univalent but not total, you should use the `IDENT` statement \(or the rule that it implements\), because that also works when an `e` is not populated.
+```text
+POPULATION personBank[Person*Bank] CONTAINS
+ [ ("John", "ING")
+ , ("Jane", "TRIODOS")
+ ]
+```
+The list of pairs is a comma-separated list between square brackets. Pairs are comma-separated pairs between round brackets. Each atom is enclosed in double quotes.
-## The INCLUDE statement
+#### Population in spreadsheets
+
+In this section we will make an Ampersand script that is based on an existing spreadsheet. This technique is useful for quickly adding population to an information system. Ampersand has a facility that allows you to import existing .xlsx files with minimal changes.
-### Purpose
+###### Theory: tables vs. binary relations
-To facilitate reusing code, Ampersand allows its user to divide code over different files.
+We can consider Ampersand as a finite system of relations. Every relation is a set of \(ordered\) pairs and each pair contains two atoms. However, in the real world we also store information in wider tables, as we do in spreadsheets and relational databases. Here is the trick. If we have two pairs that share the same left atom, e.g. \(1, Abraham\) and \(1, Lincoln\), we can put them in the same row. Using the same trick, we can interpret a row in a spreadsheet as a number of pairs.
-### Description
+######### Example
-The `INCLUDE`-statement includes the code of another Ampersand-script or the data of a .xlsx-file into the context.
+Let us look at an example:
-## Examples
+| | firstname | lastname | birth |
+| :-- | :-------- | :--------- | :---------------- |
+| 1 | Abraham | Lincoln | February 12, 1809 |
+| 2 | Barack | Obama | August 4, 1961 |
+| 3 | Calvin | Coolidge | July 4, 1872 |
+| 4 | Dwight | Eisenhower | October 14, 1890 |
+
+Since Ampersand works with relations, it must represent this table as relations. Three relations can do the job in the following manner:
```text
-INCLUDE "foo.adl"
-INCLUDE "subdirectory/foo.adl"
-INCLUDE "bar.xlsx"
+POPULATION firstname[President*Name] CONTAINS
+ [ ("1", "Abraham")
+ , ("2", "Barack")
+ , ("3", "Calvin")
+ , ("4", "Dwight")
+ ]
+
+POPULATION lastname[President*Surname] CONTAINS
+ [ ("1", "Lincoln")
+ , ("2", "Obama")
+ , ("3", "Coolidge")
+ , ("4", "Eisenhower")
+ ]
+
+POPULATION birth[President*Date] CONTAINS
+ [ ("1", "February 12, 1809")
+ , ("2", "August 4, 1961")
+ , ("3", "July 4, 1872")
+ , ("4", "October 14, 1890")
+ ]
```
-### Syntax and meaning
+Notice that the column names in the table correspond with the relation names in Ampersand. In the table we call them "attributes". So it makes sense to say that a relation in Ampersand can correspond with an attribute in a table.
+
+###### Practice: how to prepare a spreadsheet
+
+In theory, the population of the Hawaii-script might just as well be given in a spreadsheet. This works in practice too. It looks like this:
+
+| \[Subject\] | pass | required |
+| :-------------- | :-------- | :---------- |
+| Subject | Student | Destination |
+| Surfing | Brown | Hawaii |
+| Surfing | Conway | |
+| Latin | Brown | Rome |
+| World Religions | Applegate | |
+| World Religions | Brown | Rome |
+
+Please copy this in a spreadsheet of your own. The element in the first column with square brackets tells Ampersand that a new table starts. The first row contains relation names. The second row contains concept names. The rows that follow contain pairs. Ampersand reconstructs those pairs as in the example above.
+
+###### Reusing existing data
+
+In practical applications, you might want to reuse data from existing spreadsheets. People tend to have lots of "informal administration" in spreadsheets, which gives you access to authentic population. Surely you need that data organized in rows, but fortunately that is reasonably common. In such cases, you just add two lines above each table to inform Ampersand about the relations that are populated. In other cases, you have some work organizing the spreadsheet for importing it.
+
+###### Uploading your spreadsheet
+
+You will find the Excel import function in the menu bar on the top right of your screen:
+
+
+
+This is what your upload screen looks like:
+
+
+
+You can upload one or more .xlsx-files by dropping them in the drop zone or by selecting them. You have to upload the population with the green
+
+_Upload_
+
+button. At that time, all population from the .xlsx-file is added to the context and checked for inconsistencies. As a result, you may get errors when uploading. Only error-free spreadsheets will be uploaded successfully. As long as an error remains, the population in your context will not change.
+
+###### Assignment
+
+Make a population of your own for the Hawaii-script and put it in a .xlsx spreadsheet. As described above. Make sure to delete the population statements from your Hawaii source code, to make sure that you get to see the population from your .xlsx-file. Generate a prototype from your Hawaii-application, upload your population in Excel and play around with the results.
+
+###### What have you learned?
+
+After finishing your assignment, you have learned:
+
+- to upload population to your Ampersand application in the form of a spreadsheet in .xlsx-format;
+- to understand how a `POPULATION`-statement relates to the contents of a spreadsheet;
+- that the contents of the spreadsheet is added to the population of your context, provided this does not lead to any conflict.
+
+#### Purpose
+
+Patterns are meant to isolate discussions and make solutions reusable, as known from [design patterns](http://en.wikipedia.org/wiki/Design_pattern).
+
+#### Description
+
+A pattern is a set of [rules](#the-rule-statement) that describes a theme or a general reusable solution to a commonly occurring problem.
+
+For instance, if specific concerns about security arise, you might want to discuss this with stakeholders in security. With them you can discuss which rules in particular constitute your solution. Divide your problem in smaller pieces and discuss each piece with just the right stakeholders. This allows you to go deeper by talking to the right people. It saves time as well by freeing others from having to participate. An even larger benefit arises if you reuse patterns that have been discussed and scrutinized before. The best thing comes once your stakeholders agree. By that time, your pattern represents their agreement formally in Ampersand, so you can use it in the larger context of the information system.
+
+#### Example
```text
-INCLUDE <filename>
+PATTERN Security
+
+RELATION required[Subject*Destination]
+MEANING "A subject that you must have passed to qualify for the school trip to a destination"
+
+RELATION pass[Subject*Student]
+MEANING "The subjects that have been passed by specific students"
+
+RELATION attends[Student*Destination]
+
+PURPOSE RULE guardPrerequisites
+{+ This rule prevents students from registering for a trip
+without having passed the required courses. +}
+RULE guardPrerequisites : attends;required |- pass
+
+ENDPATTERN
```
-This statement specifies files that need to be included before compiling. The filename is given in double quotes, including a path that is relative to the position of the main adl-file. The main adl-file is the file that is called with the command Ampersand.
+## The INTERFACE statement
-Possible files to include are:
+#### Purpose
-* other adl-files
-* xlsx-files to include population
+Interfaces are meant to expose functionality and data from a [context](#the-context-statement), to let users or information systems interact with the system by creating, reading, updating, and deleting data.
-All code in the included adl-files will become part of the context of the main adl-file.
+#### Description
-Make sure to include the adl-files before including xlsx-files.
+An interface is a component of an information system that exposes functionality and data from a [context](#the-context-statement), to let users or information systems interact by creating, reading, updating, and deleting data. The first [example](../Examples.md#example-interface-structure) introduces a simple interface informally. Another [example](../Examples.md#interface-introductory-example) introduces the main features of an interface with nested interfaces.
-Included files may contain `INCLUDE`statements themselves. The files mentioned there are treated as though they were included in the main file. So their code is also part of the same context. Nested adl-files can have their own xlsx-files included.
+A _interface_ is a component of an information system. During the time that this interface can actually be used, we say it is _deployed_. We also call this the _lifetime_ of a interface. A typical instance of a interface is a user interface based on HTML-CSS that runs in a browser. But an application program interface \(API\) that serves other computers with web services is a perfectly valid instance as well.
-For formatting your excel-file see the text on [the Excel Importer](../the-excel-importer.md).
+#### Syntax and Meaning {#syntax-of-interface-statement}
+Note: The interface definition must be outside a pattern
-## The MEANING sub-statement
+An interface specification has the following structure. It is identical for user interfaces (`INTERFACE`) and application programming interfaces (`API`).
+
+```
+INTERFACE <name> <forRoles>? : <term> <crud>? <view>? <subinterface>?
+API <name> <forRoles>? : <term> <crud>? <view>? <subinterface>?
+```
+
+The name of an interface must be unique within the context. The [term](./terms) defines the atoms to which the interface can be applied. The (optional) crud annotation constrains the possible interactions a user can do. The (optional) views determine what the interface will look like. If no view is specified, the interface will look like the screenshot above. Finally the sub-interface contains all the contents, i.e. the fields, field names and the constraints on them.
+
+The hierarchy of boxes in an interface comes from the following (recursive) syntax of `<subinterface>`.
+
+A sub-interface may be defined on the spot (by `<boxKey> <box>`) or it may link to another interface to reuse its structure:
+
+```
+<subinterface> ::= <boxKey> <box>
+ | LINKTO ( INTERFACE | API ) <name>
+```
+
+The boxKey is meant to tell the front-end application what the interface looks like. The compiler uses templates to adapt an interface to specific needs regarding its HTML structure.
+
+```
+<boxKey> ::= BOX '<' <htmlname> '>'
+ | BOX
+```
+
+If no htmlname is specified, Ampersand uses `BOX <FORM>` by default.
+
+A box is simply a list of interface items (`ifcItem`) separated by commas. Each interface item specifies a field in the interface or a sub-interface.
+
+```
+<box> ::= '[' <ifcItem> ( ',' <ifcItem> )* ']'
+```
+
+Each interface item has a label that must be unique within the box. After the colon there is either a term or a text. The term specifies which data is related to the field it specifies if it has no sub-interface. If it does, it specifies the atoms on which the box is applied.
+
+```
+<ifcItem> ::= <label> ':' <term> <crud>? <view>? <subinterface>?
+ | <label> ':' <text>
+```
+
+You can specify that an interface is available only to actors (i.e. computers or persons) in a specific role.
-A meaning is optional and is characterized by the reserved word `MEANING`. It specifies the meaning of a concept, a relation, or a rule in natural language. The meaning is used to generate documentation and is printed in the functional specification. A `<meaning>` can be any text, starting with `{+` and ending with `+}` e.g.
-MEANING can be used with [CONCEPT](#the-concept-statement), [RELATION](#the-relation-statement), and [RULE](#the-rule-statement)-statements, to define the meaning of your concepts, relations, and rules.
-```text
-MEANING
-{+ This is an example that is
- spread over multiple lines.
-+}
```
+<forRoles> ::= FOR <roles>
+<roles> ::= <rolename> ',' <roles>
+ | <rolename>
+```
+
+#### Using an interface
+
+On the user screen each atom is displayed in some form as data. If an interface exists for that atom, that is shown to the user as a hyperlink to which you can navigate.
+
+When running an application in your browser, you are watching one user interface at any given moment in time. Each hyperlink on your screen represents an atom to which some interface applies. To navigate to that user interface, you click on the hyperlink. You will see the interface being applied solely to the atom you just clicked. To determine the atom\(s\) to which an interface applies, each interface has an _interface term_.
+
+Further examples:
+
+- a [client interface](../Examples.md#interfaces-example-client) to allow clients of a web shop to change their name and address and show them status information of their orders;
+- a [login interface](../Examples.md#interfaces-example-login) to demonstrate how to get different interface structures under varying conditions.
+
+### CRUD annotations
+
+CRUD annotations are used in interfaces to constrain the functionality of fields and boxes in an `INTERFACE`-statement. This allows you to minimize the functionality for your users, to design for easy learning.
+
+Each CRUD annotation comes right after a [term](./terms.md), so we can always refer to "the term" to which a CRUD annotation belongs. A CRUD annotation constrains the things your user can do with the target atoms and the pairs of its term.
+
+The CRUD-annotation specifies Create, Read, Update, and Delete rights for the term it follows. Capital = allowed, Non-capital = not allowed. CRUD is the default, so if you specify nothing, everything is allowed. The following interface definition illustrates this.
+
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] cRud
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] cRuD -- used for a box
+ BOX <TABLE>
+ [ "Course" : I cRud -- used for a field
+ , "Modules" : isPartOf~ -- CRUD is default
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRUd
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
+```
+
+The user interface defined by this interface is shown as a screenshot below. Notice that the lowercase r in the annotation of the Students box prevents showing the underlying box. The full CRUD functionality in Course yields 'create' functionality (the green plus-button), 'remove pair' functionality (red minus button), and 'delete atom' functionality (the red trash can button). The lowercase c, u, and d in the Modules box prevents displaying that functionality in the user interface.
+
+
+
+The next sections give some more detailed information on the runtime semantics for CRUD annotations as implemented in Ampersand.
+
+###### Create
+
+| CRUD | for a box | for a field. |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| C |  A + (plus) button is displayed that lets you create a new atom, but only if the box-term is editable. |  Enter a new atom and a `+` button appears. Click the + to add that atom to the listed set of atoms. If you enter an atom that exists (Peter), you can select it. |
+| c | Atoms cannot be created | Atoms cannot be created |
+
+###### Read
+
+| Read | CRUD for boxes | | CRUD for fields |
+| ---- | ------------------- | --- | ------------------- |
+| R | Read is allowed | | Read is allowed |
+| r | Read is not allowed | | Read is not allowed |
+
+###### Update
+
+| Update | CRUD for boxes | CRUD for fields |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| U |  Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. |  Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. |
+| u | Update is not allowed | Update is not allowed |
+
+###### Delete
+
+| Delete | CRUD for boxes | CRUD for fields |
+| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| D |  Deleting a pair is done with the - (minus) button. Deleting an atom is done with the trash bin. |  Delete atom (tgt) and all pairs in which it is used. |
+| d | delete not allowed | delete not allowed |
+
+A top-level Update or Create are common in my own scripts, e.g. to create an overview of People and be able to create a new Person: `INTERFACE "People" : V[SESSION*Person] CRud COLS []`. And update is also possible.
+
+###### Things to remember
+
+1. The red minus is enabled by `U`. It unlinks an atom (by deleting a pair from a relation) and leaves the atom alone.
+2. The red trash bin is enabled by `D`. It removes an atom and all pairs in which that atom is used.
+
+Motivations for CRUD-functionality are found in the [GitHub discussions on CRUD](https://github.com/AmpersandTarski/Ampersand/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Acrud+) functionality.
+
+#### Layout of user interfaces
+Ampersand lets you define the structure of your interface.
+It lets you place items and offers three built-in layout options, [colums](./#column-layout), [rows](./#row-layout) and [tabs](./#tabular-layout), which you can mix freely.
+Ampersand is meant for back-end design. It offers no features for front-end design. For that purpose we advise you use contemporary front-end tools for web-based applications. Your Ampersand application is [designed to be adaptable](./architecture-of-an-ampersand-application), especially for this purpose.
+
+## Interface templates
+Templates are used to generate prototype user interfaces based on Ampersand INTERFACE definitions.
+There are 3 types of templates:
+1. Box template ->
+2. Atomic templates -> used for interface leaves nodes (without a user defined VIEW specified)
+3. View templates -> used for user defined views
+
+#### Example
+```adl
+INTERFACE "Project" : I[Project] cRud BOX <-- the default FORM box template is used
+ [ "Name" : projectName <-- the default atomic template for a alphanumeric type is used
+ , "Description" : projectDescription
+ , "(Planned) start date": projectStartDate
+ , "Active" : projectActive
+ , "Current PL" : pl <PersonEmail> <-- a user defined PersonEmail view template is used
+ , "Project members" : member BOX <TABLE> <-- the built-in TABLE box template is used
+ [ "Name" : personFirstName
+ , "Email" : personEmail
+ ]
+ ]
+```
+
+
+### FORM
+The FORM template is the default BOX template.
+It structures the interface like a form, with each item on a separate line, i.e. a vertical layout style.
+It displays one form for each target atom. The sub interfaces are used as form fields.
+This template replaces former templates: `ROWS`, `HROWS`, `HROWSNL` and `ROWSNL`
+
+Usage `BOX <FORM attributes*>`
+
+For root interface boxes automatically a title is added which equals the interface name. To hide this title use `noRootTitle` attribute.
-The optional `<language>` is specified as
+Examples:
+- `BOX <FORM>`
+- `BOX <FORM hideLabels>`
+- `BOX <FORM hideOnNoRecords>`
+- `BOX <FORM title="Title of your form">`
+- `BOX <FORM hideLabels hideOnNoRecords noRootTitle>`
-* `IN ENGLISH` or
-* `IN DUTCH`.
+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 |
-Example :
+#### 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.
-```text
-MEANING IN DUTCH {+ Dit is een voorbeeld in een (1) regel.+}
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX<FORM>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <FORM>
+ [ "Student" : I[Student] CRUD
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] CRUD
+ BOX <FORM>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ ]
```
-This is a way to override the default language \(which is English\).
+This interface shows three rows in the user interface, **Students**, **Course** and **Modules**. The first column shows students in each of its rows. Each student is shown in the column layout. The second row shows courses in two columns, **Course** and **Modules**. Please read about [templates](#layout-of-interfaces) if you are curious which other ways of displaying information there are besides `BOX <FORM>`. Please read the [explanation of CRUD annotations](./interfaces.md#CRUD) if you are curious about the CRUD annotations. This is what the user will see on the screen.
-Sometimes you need formatting in the meaning, such as dotted lists, italics, or mathematical symbols. For this purpose you have a choice in which syntax you specify the meaning. The optional `<markup>` is one of :
+
-* `REST` \(Restructured text. This is the default\)
-* `HTML`
-* `LATEX`
-* `MARKDOWN`
+### TABLE
+The TABLE template structures an interface like a table.
+Every target atoms of the interface is displayed as a row as in a table.
+The sub interfaces are used as columns.
+This templates replaces former templates: `COLS`, `SCOLS`, `HCOLS`, `SHCOLS` and `COLSNL`
-Example :
+Usage: `BOX <TABLE attributes*>`
-```text
-MEANING LATEX {+This is a {\em mathematical} formula $\frac{3}{x+7}$.+}
-```
+For root interface boxes automatically a title is added which equals the interface name. To hide this title use `noRootTitle` attribute.
-Ampersand uses Pandoc to offer a choice for your markup. See [pandoc.org](http://pandoc.org/) for details.
+Examples:
+- `BOX <TABLE>` -- was: COLS
+- `BOX <TABLE noHeader>`
+- `BOX <TABLE hideOnNoRecords>` -- was: HCOLS
+- `BOX <TABLE title="Title of your table">`
+- `BOX <TABLE noHeader hideOnNoRecords title="Table with title">`
+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) |
+| 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 |
+| 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 |
+#### 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.
-## The POPULATION statement
+```
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] cRud
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] cRuD
+ BOX <TABLE>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRUd
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
+```
-### Purpose
+This interface shows three columns in the user interface, **Students**, **Course** and **Modules**. The first column is not readable, because the [CRUD annotation](#CRUD) blocks this column for reading. It would have shown students in each row, because the target of `V[SESSION*Student]`is `Student`. The second column shows courses in two columns, **Course** and **Modules**. The third column shows modules in three columns. This is what the user will see on the screen.
-To store data in a database corresponds to populating the relations in a context. Atoms are the data and pairs of atoms are inserted and deleted during the lifetime of a relation.
+
-### Description
+### TABS
+Interface template for a form structure with different tabs. For each sub interface a tab is added.
+This template is used best in combination with univalent interface expressions (e.g. `INTERFACE "Test" : univalentExpression BOX <TABS>`), because for each target atom of the expression a complete form (with all tabs) is shown.
-All pairs in a relation are called the population of that relation. All atoms in a concept constitute the population of that concept. The population of all relations and concepts in a context make the population of that context.
+Usage `BOX <TABS attributes*>`
-There are two ways to populate a concept with atoms:
+For root interface boxes automatically a title is added which equals the interface name. To hide this title use `noRootTitle` attribute.
-* A `POPULATION` statement defines the initial population of a concept or a relation.
-* An `INCLUDE` statement defines the initial population from an xlsx-file \(i.e. an Excel speadsheet\)
+Example:
+- `BOX <TABS>`
+- `BOX <TABS title="Tabs with title">`
+- `BOX <TABS noRootTitle>`
-[Using spreadsheets](#population-in-spreadsheets) to define an initial population allows you to work with larger populations. Often you can use an existing spreadsheet and adapt it to become acceptable as Ampersand input.
+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 |
-### Syntax
-You can define atoms separately and you can define the pairs in a relation. Both methods result in added population for each concept.
+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.
-```text
-POPULATION Tree CONTAINS
- [ "Oak"
- , "Birch"
- , "Willow"
- ]
+#### Example
```
-
-```text
-POPULATION personBank[Person*Bank] CONTAINS
- [ ("John", "ING")
- , ("Jane", "TRIODOS")
- ]
+INTERFACE Overview : "_SESSION" cRud
+BOX <TABS>
+ [ Students : V[SESSION*Student] cRuD
+ BOX <TABLE>
+ [ "Student" : I[Student] CRUD
+ , "Enrolled for" : isEnrolledFor cRUD
+ , "Course" : takes CRUD
+ ]
+ , Course : V[SESSION*Course] CRUD
+ BOX <TABLE>
+ [ "Course" : I cRud
+ , "Modules" : isPartOf~ CRUD
+ ]
+ , Modules : V[SESSION*Module] cRud
+ BOX <TABLE>
+ [ "Modules" : I cRuD
+ , "Course" : isPartOf cRud
+ , "Students" : isEnrolledFor~ CRUD
+ ]
+ ]
```
-The list of pairs is a comma-separated list between square brackets. Pairs are comma-separated pairs between round brackets. Each atom is enclosed in double quotes.
-
-### Population in spreadsheets
+This interface shows three tabs in the user interface, **Students**, **Course** and **Modules**. Only one tab is shown at a time, to avoid cluttered data. This is what the user will see on the screen.
-In this section we will make an Ampersand script that is based on an existing spreadsheet. This technique is useful for quickly adding population to an information system. Ampersand has a facility that allows you to import existing .xlsx files with minimal changes.
+
-#### Theory: tables vs. binary relations
+We have discussed the `FORM`, `TABLE`, and `TABS` layout options. Please note that these options do not change the semantics; whatever your options, Ampersand displays the same data in the same fields.
-We can consider Ampersand as a finite system of relations. Every relation is a set of \(ordered\) pairs and each pair contains two atoms. However, in the real world we also store information in wider tables, as we do in spreadsheets and relational databases. Here is the trick. If we have two pairs that share the same left atom, e.g. \(1, Abraham\) and \(1, Lincoln\), we can put them in the same row. Using the same trick, we can interpret a row in a spreadsheet as a number of pairs.
+### RAW
+Interface template without any additional styling and without (editing) functionality. Just plain html `<div>` elements
+This template replaces former templates: `DIV`, `CDIV` and `RDIV`
-##### Example
+Usage: `BOX <RAW attributes*>`
-Let us look at an example:
+Examples:
+- `BOX <RAW>`
+- `BOX <RAW form>`
+- `BOX <RAW table>`
-| | firstname | lastname | birth |
-| :--- | :--- | :--- | :--- |
-| 1 | Abraham | Lincoln | February 12, 1809 |
-| 2 | Barack | Obama | August 4, 1961 |
-| 3 | Calvin | Coolidge | July 4, 1872 |
-| 4 | Dwight | Eisenhower | October 14, 1890 |
+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
-Since Ampersand works with relations, it must represent this table as relations. Three relations can do the job in the following manner:
+### 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]).
-```text
-POPULATION firstname[President*Name] CONTAINS
- [ ("1", "Abraham")
- , ("2", "Barack")
- , ("3", "Calvin")
- , ("4", "Dwight")
- ]
+The interface provides means to:
-POPULATION lastname[President*Surname] CONTAINS
- [ ("1", "Lincoln")
- , ("2", "Obama")
- , ("3", "Coolidge")
- , ("4", "Eisenhower")
- ]
+- construct the label (i.e. the text that shows on the button) from fixed texts (i.e. `TXT "some text here"`) as well as valiues of expression. This allows you to create detailed/customized texts on a button.
+- flip, set, and clear (up to 3) property-relations. This allows you to easily create complex state machines, where clicking a single button can flip, set and clear several property-relations simultaneously.
+- specify the color of the button, and a different color for when it is disabled.
+- hide and/or disable the button by specifying an expression (that must be a [PROP]-type).
+- provide a popover text for the button, both when it is enabled and when it is disabled.
-POPULATION birth[President*Date] CONTAINS
- [ ("1", "February 12, 1809")
- , ("2", "August 4, 1961")
- , ("3", "July 4, 1872")
- , ("4", "October 14, 1890")
+Usage (note that all attributes are optional, and you can rearrange their order as you see fit) :
+```
+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
+ , "label2": expr or txt -- text on button = label+label1+label2
+ , "label3": expr or txt -- text on button = label+label1+label2+label3
+ , "property": propRel cRUd -- value of propRel is flipped when the button is clicked (backward compatible)
+ , "fliprop1": propRel cRUd -- value of propRel is flipped when the button is clicked
+ , "fliprop2": propRel cRUd -- value of propRel is flipped when the button is clicked
+ , "fliprop3": propRel cRUd -- value of propRel is flipped when the button is clicked
+ , "setprop1": propRel cRUd -- value of propRel is set (made true) when the button is clicked
+ , "setprop2": propRel cRUd -- value of propRel is set (made true) when the button is clicked
+ , "setprop3": propRel cRUd -- value of propRel is set (made true) when the button is clicked
+ , "clrprop1": propRel cRUd -- value of propRel is cleared (made false) when the button is clicked
+ , "clrprop2": propRel cRUd -- value of propRel is cleared (made false) when the button is clicked
+ , "clrprop3": propRel cRUd -- value of propRel is cleared (made false) when the button is clicked
+ , "color": color -- see below for details.
+ , "hide": expr cRud -- button is hidden (not shown) when expression evaluates to true
+ , "disabled": expr -- button is disabled (not clickable) when expression evaluates to true
+ , "disabledcolor": color -- optional; see below for details.
+ , "disabledpopovertext": expr or txt -- text is shown instead of popovertext when button is disabled.
+ , "popovertext": expr or txt -- text that is displayed when hovering the button
]
```
+where:
+- `propRel` is an & `[PROP]`-type relation, whose value will be toggled when the user clicks the button.
+- `expr` refers to an &-expression that should be univalent (and should be followed by `cRud` except when explicitly mentioned otherwise);
+- `txt` refers to the syntax `TXT "some text here"`;
+- `color` refers to `TXT "colorword"` can be primary (blue), secondary (grey), success (green), warning (yellow), danger (red), info (lightblue), light (grey), dark (black). So, if you want a red button, you write `"color": TXT "danger" -- button is red`.
+It should be possible to precede color names 'outline-' (e.g. 'outline-primary') to make outline buttons (i.e. buttons with only the outline coloured), but that does not yet seem to work properly.
-Notice that the column names in the table correspond with the relation names in Ampersand. In the table we call them "attributes". So it makes sense to say that a relation in Ampersand can correspond with an attribute in a table.
-#### Practice: how to prepare a spreadsheet
+Possible attributes are:
+| attribute | value | description |
+| --------- | ----- | ----------- |
+| *currently there are no attributes for this template*
-In theory, the population of the Hawaii-script might just as well be given in a spreadsheet. This works in practice too. It looks like this:
-| \[Subject\] | pass | required |
-| :--- | :--- | :--- |
-| Subject | Student | Destination |
-| Surfing | Brown | Hawaii |
-| Surfing | Conway | |
-| Latin | Brown | Rome |
-| World Religions | Applegate | |
-| World Religions | Brown | Rome |
+If these options are not enough, you can [enhance your application with your own layouts](../tutorial/interfaces.md#layout-and-widgets).
-Please copy this in a spreadsheet of your own. The element in the first column with square brackets tells Ampersand that a new table starts. The first row contains relation names. The second row contains concept names. The rows that follow contain pairs. Ampersand reconstructs those pairs as in the example above.
+### Your own templates and widgets \(HTML and CSS\)
-#### Reusing existing data
+You don't have to put up with the [Ampersand built-in layout options](#layout-of-interfaces) if they don't suit your purpose. You can change most anything by including your own code snippets. \(to be documented...\).
-In practical applications, you might want to reuse data from existing spreadsheets. People tend to have lots of "informal administration" in spreadsheets, which gives you access to authentic population. Surely you need that data organized in rows, but fortunately that is reasonably common. In such cases, you just add two lines above each table to inform Ampersand about the relations that are populated. In other cases, you have some work organizing the spreadsheet for importing it.
+### Atomic templates (i.e. interface leaves)
-#### Uploading your spreadsheet
+#### OBJECT
-You will find the Excel import function in the menu bar on the top right of your screen:
+#### ALPHANUMERIC, BIGALPHANUMERIC, HUGEALPHANUMERIC
-
+#### BOOLEAN
-This is what your upload screen looks like:
+#### DATE, DATETIME
-
+#### INTEGER, FLOAT
- You can upload one or more .xlsx-files by dropping them in the drop zone or by selecting them. You have to upload the population with the green
+#### PASSWORD
-_Upload_
+#### TYPEOFONE
+Special interface for singleton 'ONE' atom. This probably is never used in an prototype user interface.
- button. At that time, all population from the .xlsx-file is added to the context and checked for inconsistencies. As a result, you may get errors when uploading. Only error-free spreadsheets will be uploaded successfully. As long as an error remains, the population in your context will not change.
+#### OBJECTDROPDOWN
+Interface template that can be used to populate a relation (whose target concept MUST BE an object) using a dropdown list.
+Objects are concepts for which there is no `REPRESENT` statement; non-objects (or values) are concepts for which there is (e.g. `REPRESENT SomeConcept TYPE ALPHANUMERIC`). This template can be used for objects. Use `BOX <VALUEDROPDOWN>` for non-objects.
-#### Assignment
+Usage:
+```
+expr cRud BOX <OBJECTDROPDOWN>
+[ "selectfrom": selExpr cRud <ObjectView> -- population from which the user can make a selection.
+, "setrelation": setRel cRUd -- If the relation is [UNI], a newly selected object will replace the existing population.
+, "instruction": expr or txt -- Text that shows when nothing is selected yet.
+, "selectflag": selectEventFlag cRUd -- [PROP]-type relation that toggles when OBJECT is selected.
+, "deselectflag": deselectEventFlag cRUd -- [PROP]-type relation that toggles when NO OBJECT is selected.
+]
+```
-Make a population of your own for the Hawaii-script and put it in a .xlsx spreadsheet. As described above. Make sure to delete the population statements from your Hawaii source code, to make sure that you get to see the population from your .xlsx-file. Generate a prototype from your Hawaii-application, upload your population in Excel and play around with the results.
+where:
+- `expr` is an expression that, if and only if 'TRUE' causes the dropdown box to be shown.
+- `selExpr cRud` specifies the objects that the user may select from.
+- `<ObjectView>` the VIEW to be used to show the selectable objects in the dropdown box.
+- `setRel cRUd` is the relation whose population is modified as a result of the users actions.
+ - If the relation is `[UNI]` the user may overwrite its value (tgt atom) by selecting an object.
+ - If the relation is not `[UNI]`, the user can add values (tgt atoms) by selecting one or more objects.
+ - When the user selects the NO OBJECT, the (list of) tgt atom(s) is cleared.
+- `expr or txt` in the 'instruction' field specifies the text that the user sees when no object has been selected.
+- `selectEventFlag cRUd` specifies a [PROP]-type relation that will be toggled when an object is selected.
+- `deselectEventFlag cRUd` specifies a [PROP]-type relation that toggles when NO OBJECT is selected.
+
+NOTE that the `cRud` and `cRUd` usage must be strictly followed here!
+
+#### VALUEDROPDOWN
+Interface template that can be used to populate a relation (whose target concept is NOT an object) using a dropdown list. Objects are concepts for which there is no `REPRESENT` statement; non-objects (or values) are concepts for which there is (e.g. `REPRESENT SomeConcept TYPE ALPHANUMERIC`). This template can be used for values (non-objects). Use `BOX <OBJECTDROPDOWN>` for concepts that are objects.
+
+Usage:
+```
+expr cRud BOX <VALUEDROPDOWN>
+[ "selectfrom": selExpr cRud <ValueView> -- population from which the user can make a selection.
+, "setrelation": setRel cRUd -- If the relation is [UNI], a newly selected value will replace the existing population.
+, "instruction": expr or txt -- Text that shows when nothing is selected yet.
+, "selectflag": selectEventFlag cRUd -- [PROP]-type relation that toggles when VALUE is selected.
+, "deselectflag": deselectEventFlag cRUd -- [PROP]-type relation that toggles when NO VALUE is selected.
+]
+```
+
+where:
+- `expr` is an expression that, if and only if 'TRUE' causes the dropdown box to be shown.
+- `selExpr cRud` specifies the values that the user may select from.
+- `<ValueView>` the VIEW to be used to show the selectable values in the dropdown box.
+- `setRel cRUd` is the relation whose population is modified as a result of the users actions.
+ - If the relation is `[UNI]` the user may overwrite its value (tgt atom) by selecting an value.
+ - If the relation is not `[UNI]`, the user can add values (tgt atoms) by selecting one or more values.
+ - When the user selects the NO VALUE, the (list of) tgt atom(s) is cleared.
+- `expr or txt` in the 'instruction' field specifies the text that the user sees when no value has been selected.
+- `selectEventFlag cRUd` specifies a [PROP]-type relation that will be toggled when an value is selected.
+- `deselectEventFlag cRUd` specifies a [PROP]-type relation that toggles when NO VALUE is selected.
-#### What have you learned?
+NOTE that the `cRud` and `cRUd` usage must be strictly followed here!
-After finishing your assignment, you have learned:
+### Built-in VIEW templates
+
+#### FILEOBJECT
+The purpose of this template, and the associated code, is to allow users to download and upload files.
+
+To use: add the following statements to your script:
+
+```
+ IDENT FileObjectName: FileObject (filePath)
+ RELATION filePath[FileObject*FilePath] [UNI,TOT]
+ RELATION originalFileName[FileObject*FileName] [UNI,TOT]
-* to upload population to your Ampersand application in the form of a spreadsheet in .xlsx-format;
-* to understand how a `POPULATION`-statement relates to the contents of a spreadsheet;
-* that the contents of the spreadsheet is added to the population of your context, provided this does not lead to any conflict.
+ REPRESENT FilePath,FileName TYPE ALPHANUMERIC
+ VIEW FileObject: FileObject DEFAULT
+ { apiPath : TXT "api/v1/file"
+ , filePath : filePath
+ , fileName : originalFileName
+ } HTML TEMPLATE "View-FILEOBJECT.html" ENDVIEW
+```
+
+#### LINKTO
+This template can be used to specify the interface to which the user must navigate.
+
+Usage:
+```
+ "label": expr LINKTO INTERFACE "InterfaceName"
+```
+
+where:
+- `expr` is an ampersand expression, as usual
+- `InterfaceName` is the name of an existing interface whose (SRC) concept matches the TGT concept of `expr`.
+
+#### PROPERTY
+
+#### STRONG
+
+#### URL
## The PURPOSE statement
-### Semantics
+#### Semantics
Most things in your model are in it for a reason. To document these, you should use the PURPOSE statement.
-### Syntax
+#### Syntax
`PURPOSE` `<type of thing>` `<name>` `<language>?` `<markup>?`
@@ -485,7 +1330,7 @@ Where `<type of thing>` and `<name>` are the type and name of the thing that is
The optional and can be used to override the settings for language and markup. If omitted, these are inherited from the pattern of context where the PURPOSE statement is specified in.
-### Examples
+#### Examples
```text
PURPOSE CONCEPT Person {+The concept Person keeps all personal data together.+}
@@ -507,7 +1352,7 @@ PURPOSE RELATION accountOwner[Account*Owner]
+}
```
-### Markup
+#### Markup
For the purpose of documentation, you may state the language in which you write a purpose. You may also state in which markup language you use. Examples:
@@ -534,247 +1379,378 @@ IN ENGLISH MARKDOWN
+}
```
+## The MEANING sub-statement
-## The RELATION statement
+A meaning is optional and is characterized by the reserved word `MEANING`. It specifies the meaning of a concept, a relation, or a rule in natural language. The meaning is used to generate documentation and is printed in the functional specification. A `<meaning>` can be any text, starting with `{+` and ending with `+}` e.g.
+MEANING can be used with [CONCEPT](#the-concept-statement), [RELATION](#the-relation-statement), and [RULE](#the-rule-statement)-statements, to define the meaning of your concepts, relations, and rules.
+
+```text
+MEANING
+{+ This is an example that is
+ spread over multiple lines.
++}
+```
-### Purpose
+The optional `<language>` is specified as
-A _**relation statement**_ says that a relation exists. It introduces (defines, declares) the relation in the context that uses the relation statement.
+- `IN ENGLISH` or
+- `IN DUTCH`.
-A _**population statement**_ specifies which pairs (of atoms) are in a relation.
+Example :
-### Description
+```text
+MEANING IN DUTCH {+ Dit is een voorbeeld in een (1) regel.+}
+```
-A relation is a set that contains pairs of atoms. Over time, pairs can be inserted into or deleted from a relation, for example by a user typing data into an Ampersand application. So the content of a relation is changing over time.
+This is a way to override the default language \(which is English\).
-When discussing relations, an arbitrary relation is referred to as $$r$$, $$s$$, or $$t$$. To say that a pair $$(a,b)$$ belongs to a relation $$r$$, we write $$a\ r\ b$$ or alternatively $$(a,b)\in r$$.
+Sometimes you need formatting in the meaning, such as dotted lists, italics, or mathematical symbols. For this purpose you have a choice in which syntax you specify the meaning. The optional `<markup>` is one of :
-### Examples
+- `REST` \(Restructured text. This is the default\)
+- `HTML`
+- `LATEX`
+- `MARKDOWN`
-```
-RELATION soldBy[Order*Person]
-```
+Example :
+```text
+MEANING LATEX {+This is a {\em mathematical} formula $\frac{3}{x+7}$.+}
```
-RELATION contract[Order*ContractID] [UNI,TOT]
-PRAGMA "Order " " has contract " " as its legal basis."
-MEANING
-{+ Every Order has a unique ContractID which specifies the legal basis
- for that particular order.
-+}
+
+Ampersand uses Pandoc to offer a choice for your markup. See [pandoc.org](http://pandoc.org/) for details.
+
+## Miscellaneous
+###Language support
+
+#### Purpose
+
+To generate documentation, Ampersand is language aware.
+
+#### Description
+
+Ampersand assigns a language to every text written as documentation, whether it is a `MEANING`, `PURPOSE` or other text except comment.
+
+Ampersand does not recognize any language, so you must tell which language is meant. To tell Ampersand what language you use, you can append a language directive to a context, a meaning, and to a purpose statement. Currently English and Dutch are supported.
+
+#### Syntax
+
+A language directive has the following syntax
+
+```text
+IN <language>
```
-In this example:
+Where `<language>` can be `ENGLISH` or `DUTCH`.
-* `contract` is the _**name**_ of the relation,
-* `Order` is the _**source concept**_ of the relation,
-* `ContractID` is the _**target concept**_ of this relation, and
-* `UNI` and `TOT` are _**constraints**_ of this relation.
+#### Semantics by example
-### Syntax and meaning
+The first example is a context declaration in which the language `ENGLISH` is specified.
-Each relation used in Ampersand has to be declared. This means that the developer tells the system that this particular relation exists. A relation declaration can have one of the following formats:
+```text
+CONTEXT Foo IN ENGLISH
+...
+ENDCONTEXT
+```
+
+This means that all natural language elements within this context are written in `ENGLISH`, unless specified otherwise.
+
+The second example is a `MEANING`, which can be used in a `RULE` statement and in a `RELATION` statement. This example uses a `MEANING` in `ENGLISH`:
+```text
+RELATION ptpic[Pattern*Image] [UNI]
+MEANING IN ENGLISH "Relation ptpic relates a pattern to the image of its conceptual diagram."
```
-RELATION <lower case identifier>
- '[' <upper case identifier> '*' <upper case identifier> ']'
- <properties>? <pragma>? <meaning>?
+
+The language directive `IN ENGLISH` means that the meaning of the relation `ptpic[Pattern*Image]` is written in `ENGLISH`.
+
+The third example is a `PURPOSE` statement in which the language `DUTCH` is specified.
+
+```text
+PURPOSE CONCEPT Person IN DUTCH
+{+ Een persoon is een natuurlijke persoon of een rechtspersoon +}
```
-In the _**declaration**_ `RELATION owner[Person*Building]`, `owner` is the _**name**_ and `[Person*Building]` is the _**type**_ of the relation. Relation names start with a lower case character, to avoid confusion with concept names. The _**signature**_ of this relation is `owner[Person*Building]`. The signature identifies the relation within its context. The left hand concept, `Person`, is called the _**source**_ of the relation and the right concept, `Building`, is called the _**target**_.
+This means that the contents of this purpose statement is written in `DUTCH`.
-All three formats define a relation by its name, its source concept and its target concept. By convention, the name of a relation is a single word that starts with a lower case letter. The source and target concepts start with an upper case letter. This convention avoids confusion between concepts and relations.
+#### Additional information
-A relation statement means that there exists a relation in the current context with the specified name, source concept and target concept.
+Ampersand assumes that whatever is written is written in the language denoted in the language directive. It doesn't check whether that language is actually used, because it cannot recognize languages.
-A relation statement may occur anywhere inside a context, both inside and outside a pattern.
+If a `CONTEXT` has no language directive, `IN ENGLISH` is used by default. If a `CONTEXT` has a language directive, that language will be the default language of all natural language items within that context.
-The optional `<properties>` and `<pragma>`-parts are discussed in the sequel. The `<meaning>`-part is discussed [here](#the-meaning-substatement\).
+If a `PURPOSE` statement or a `MEANING` has no language directive, Ampersand assumes this to be the language of its context. So, the user needs to specify a language only if it is an exception to the default.
-The name, source concept and target concept together identify a relation uniquely within its context. As a consequence, the name of a relation does not have to be unique. E.g. `name[Book*Name]` can be specified in the same context as `name[Person*Name]`. Because they have different source concepts, these are different relations.
+Documentation generated by the Ampersand-compiler is written in a single language, which is specified when the compiler is called.
-### Properties
+Documentation generated by RAP4 is written in `DUTCH`. Natural language items written in any other language are ignored. This is [not a mistake](https://github.com/AmpersandTarski/Ampersand/issues/702), but a feature. RAP4 only "speaks Dutch" and ignores anything else.
-The `<properties>`-part is meant for writing multiplicity constraints in a comma separated list between square brackets '\[' and ']'. E.g. `[UNI,TOT]` . The following properties can be specified on any relation `r[A*B]`
+### Automated rules
+#### Purpose
-| & | property | semantics |
-| --- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| UNI | univalent | For any `a` in `A` there can be not more than one `b` in `B` in the population of `r`. This implies that every `a` occurs not more than once (is unique) in the source of `r`. |
-| 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`. |
+The purpose of automated rules is to resolve violations automatically when enforcement rules are insufficient for the job at hand.
-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]`.
+#### Syntax
-| & | property | semantics |
-| ---- | ------------- | ------------------------------------------------------------------------- |
-| SYM | symmetric | For each (`a`,`b`) in `r`, (`b`,`a`) is in `r`. |
-| ASY | antisymmetric | If (`a`,`b`) and (`b`,`a`) are both in `r`, then `a` = `b` |
-| 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. |
+```text
+ROLE ExecEngine MAINTAINS <label>
+RULE <label> <term> <meaning>* <message>* <violation>?
+```
+The [RULE syntax](#the-rule-statement) is the same as for ordinary rules.
+However, the violations are specified differently.
+We will define the specifics by examples.
+Most of the examples are taken from the demo script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/Examples/ProjectAdministration). You can compile and run this script, and reproduce several of the examples that follow.
-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.
+#### Example \(`InsPair` and `DelPair`\)
-In relation algebra, we say that the relation is univalent, which means that every atom in the source concept can only be paired with a single atom in the target concept. This is modeled as
+Consider the following example:
+```text
+RELATION pl[Project*Person] MEANING "A project can have project leaders."
+RELATION member[Project*Person] MEANING "A person can do actual work within a project."
+RELATION coworker[Person*Person] MEANING "Two people are co-workers in a project."
```
-RELATION lives[Person*City][UNI]
-MEANING "A person can live in one city only."
+
+The following rule defines coworkers. Two different persons are coworker if they work in the same project. As a person can be either a project leader or a member, we get this rule:
+
+```text
+RULE coworker = (pl\/member)~;(pl\/member)-I
```
-### PRAGMA
+This rule basically says that `coworker` is shorthand for the much more complicated [term](./terms) `(pl\/member)~;(pl\/member)-I`. Quite useful indeed. Now suppose this rule is satisfied in the system. Then some manager assigns a new person, Harry, to the project Zeus-III. To administer that fact in the system, he adds a pair `("Zeus-III", "Harry")` to the relation `member`. Now there is a problem. The prototype will not accept this input, because our rule is violated. For all present workers in the project now have Harry as a new coworker. That should be administered in the relation `coworker` in order to satisfy the rule.
-A pragma is optional and is characterized by the reserved word `PRAGMA`. The `PRAGMA` is followed by two or three strings. It is used to construct sentences in natural language, using pairs from the actual population of a relation. A pragma specifies how we speak (in natural language) about any pair in the relation. Ampersand also uses pragmas to generate examples in the functional specification. Example of a pragma with three strings:
+One way to do that is to allow the manager to edit the relation coworker. This is not very convenient for that manager. He will be irritated, as he is forced to enter a number of pairs into the relation `coworker` that is equal to the number of persons in the project plus the number of projectleaders of that project. This rule is typically a candidate for automation.
+
+We have to consider that whenever a person is added to the project, that person must be added to `coworker` as well. But when a person is discharged from the project, that person must be removed from `coworker`. We can split the rule in two, knowing that `r=s` is always equivalent to both `r|-s` and `s|-r`.
+
+```text
+ROLE "ExecEngine" MAINTAINS r1
+RULE r1: (pl\/member)~;(pl\/member)-I |- coworker
+VIOLATION (TXT "InsPair;coworker;Person;", SRC I, TXT ";Person;", TGT I)
+ROLE "ExecEngine" MAINTAINS r2
+RULE r2: coworker |- (pl\/member)~;(pl\/member)-I
+VIOLATION (TXT "DelPair;coworker;Person;", SRC I, TXT ";Person;", TGT I)
```
-PRAGMA "Student " " flies the flag of " " in top."
+
+Let us discuss both rules, starting with the first one. The `ROLE` statement assigns rule `r1` to the ExecEngine. The instruction for the ExecEngine is given in the `VIOLATION` string. It will be executed for each violation of rule `r1`.
+
+Elaborating on this example, just which violations will the ExecEngine resolve? Suppose the project has Alfred and Bob on the team before Harry is assigned. This means that the relation `coworker` contains `("Alfred", "Bob")` and `("Bob", "Alfred")` for starters. When the pair `("Zeus-III", "Harry")` is added to the relation `member`, we get the following violations: `("Alfred", "Harry")`, `("Harry", "Alfred")`, `("Bob", "Harry")`, and `("Harry", "Bob")`. So, the following instructions will be given to the ExecEngine:
+
+```text
+"InsPair;coworker;Person;Alfred;Person;Harry"
+"InsPair;coworker;Person;Harry;Person;Alfred"
+"InsPair;coworker;Person;Bob;Person;Harry"
+"InsPair;coworker;Person;Harry;Person;Bob"
```
-To use this pragma on the pair `(John,Amsterdam)` results in the sentence `"Student John flies the flag of Amsterdam in top."`. The two atoms are fitted in between the three strings. A pragma with two strings is identical to a pragma in which the third string is empty.
+Note that the violations of rule `r1` are precisely the pairs the ExecEngine must add to `coworker` to satisfy rule `r1`. The function `InsPair` is a predefined ExecEngine function, that adds to the population of a relation. The corresponding function `DelPair` removes pairs from the population of a relation. In the example, it is used to remove people from `coworker` that no longer share a project.
-(The `PRAGMA` keyword will become obsolete in a future version of Ampersand. It will be replaced by the `VIEW`-statement which offers more flexibility in composing sentences.)
+**Notes**:
-Example:
+* The examples use `SRC I` or `TGT I` to produce atoms that are to be inserted or deleted. However, `I` may be any [term](./terms) whose source concept is the same as that of the preceeding `SRC` or `TGT`.
+* The `SRC <term>` and `TGT <term>` is a set of pairs \(a,b\), where a is the source atom or target atom of the violation and b is a set of atoms that is the result of `<term>`. In the examples given, this set of atoms has cardinality 1 \(which is most often the case\). However, if it is empty, that is considered regular behaviour, and this will hence not result in an error. Also, if it has a cardinality > 1, then `InsPair` will insert them all whereas `DelPair` will produce an error.
-```
-RELATION accepted[Provider * Order] [INJ] PRAGMA "Provider " " has accepted order "
+#### Example \(`InsAtom`\) and \(`{EX}`\)
+
+Consider the following example:
+
+```text
+RELATION pl[Project*Person] MEANING "A project can have project leaders."
+RELATION project[Assignment*Project] [UNI,TOT] MEANING "Every Assignment must apply to one project"
+RELATION assignee[Assignment*Person] [UNI,TOT] MEANING "Every Assignment must apply to one person"
```
-The `PRAGMA` tells us that it makes sense to utter the phrase `"Provider Mario's Pizza's has accepted order 12345."`
+The following rule states that for every project leader, an assignment must exist that applies to one person and one project, basically assigning that person to be a project leader for the Project.
-### MEANING
+```text
+RULE "Require Assignment" : pl |- project~;assignee
+```
-For a full discussion of meaning, we refer to [`this page`](#the-meaning-substatement\).
+This calls for two different things: first, the automated creation of an atom in the concept `Assignment`, and second the consecutive population of relations `project` and `assignee` using this newly created atom.
-### Miscellaneous
+This is specified as follows:
-*
+```text
+ROLE "ExecEngine" MAINTAINS "Create Assignment"
+RULE "Create Assignment" : pl |- project~;assignee
+VIOLATION (TXT "{EX} InsAtom;Assignment"
+ ,TXT "{EX} InsPair;project;Assignment;_NEW;Project;", SRC I
+ ,TXT "{EX} InsPair;assignee;Assignment;_NEW;Person;", TGT I
+ )
+```
-## The RULE statement
+First, note that we have three consecutive statements: an `InsAtom` command followed by two `InsPair`s. Using the phrase `{EX}` in front of each statement allows the interpreter of the violation texts to recognize each individual command and its arguments. In order to ensure that you do not forget about this, you may want to consider habituating yourself to _always_ use {EX} before any function.
-### Purpose
+The first statement assigns the rule `Create Assignment` to the ExecEngine. The prototype will send all violations of this rule to the ExecEngine. The rule says that for every project with a project leader, there must be an assignment. Without that assignment, the rule is violated. The `VIOLATION` statement specifies that a new `Assignment` must be made for each violation. For that purpose, we use the predefined function `InsAtom`. This function takes a single argument, being the concept within which an atom has to be generated \(`Assignment` in the example\).
-The purpose of a rule is to constrain data. Refer to the chapter about rules in the tutorial for examples and a practice oriented explanation.
+The second statement calls the `InsPair` function in order to populate the relation `project`, in the manner we described above. Note that at the position where we want to specify the newly created Assignment atom, we use the phrase `_NEW`. The third statement calls the `InsPair` function in a similar fashion, and thus populates the relation `assignee`.
-A rule statement defines something that should be true. It does not define the enforcement.
+Note that
-### Syntax of rules
+* in an `InsPair` \(or `DelPair`\), the source-atom or the target-atom \(or both\) can be the keyword `_NEW`.
+* the keyword `_NEW` refers to the last atom that was created by the \(last\) `InsAtom` statement that was executed in the violation.
+* when using `_NEW`, the corresponding concept \(obviously\) MUST be the same as the concept as specified in the `InsAtom` statement.
-A `<rule>` has the following syntax:
+Here is how it works. Suppose the pair `("Zeus-III", "Rhea")` is added to the relation `pl`, meaning that `Rhea` is being made a project leader of project `Zeus-III`. This produces a violation `("Zeus-III", "Rhea")` of the rule `Create Assignment`. The associated VIOLATION statement produces the text
```text
-RULE <label>? <term> <meaning>* <message>* <violation>?
+ {EX} InsAtom;Assignment{EX} InsPair;project;Assignment;_New;Project;Zeus-III{EX} InsPair;assignee;Assignment;_NEW;Person;Rhea
```
-### Syntax of labels
+which is passed to the ExecEngine, which splits the text in three statements
-A `<label>` is optional. It can be a single word or a string \(enclosed by double brackets\) followed by a colon \(`:`\).
+```text
+ InsAtom;Assignment
+ InsPair;project;Assignment;_New;Project;Zeus-III
+ InsPair;assignee;Assignment;_NEW;Person;Rhea
+```
-#### Term
+and subsequently executes them. Executing the `InsAtom` statement creates a new atom in concept `Assignment` \(let's say it is `Assignment_3495812395`. The keywords `_NEW` in the InsPair statements are then replaced by `Assignment_3495812395`, so that `("Assignment_3495812395", "Zeus-III")` is inserted into relation `project[Assignment*Project]`, and `("Assignment_3495812395", "Rhea")` is inserted into relation `assignee[Assignment*Person]`.
-A term can be any of:
+#### Example \(`DelAtom`\)
-* Term BinaryOperator Term
-* UnaryOpPre Term
-* Term UnaryOpPost
-* a \(reference to a\) relation \(including an optional signature, when required to disambiguate\):
- * A relation by name
- * `I` \(the Identity relation\)
- * `V` \(carthesian product\) Note that this can also be used to denote the empty relation, by using the unary negation operator: '-v'
- * A singleton term \(the value of an atom\)
-* a term enclosed in brackets.
+In our example, whenever a project participant is discharged from his task, the corresponding Assignment needs to be deleted. We can do this by means of an automated rule:
-##### Operators
+```text
+ROLE "ExecEngine" MAINTAINS "Delete Assignment"
+RULE "Delete Assignment" : project~;assignee |- pl\/member
+VIOLATION ( TXT "DelAtom;Assignment;", SRC I)
+```
-The following operators are available to build expressions:
+The function 'DelAtom' is predefined, and takes two arguments: 1. the concept from which an atom is to be deleted; 2. the actual atom to be deleted.
-* Binary operators
- * equivalence: `=`
- * composition: `;`
- * inclusion: `|-`
- * intersection: `/\`
- * union: `\/`
- * difference: `-`
- * left residual: `/`
- * right residual: `\`
- * diamond: `<>`
- * relative addition: `!`
- * cartesian product: `#`
-* Unary operator \(pre-operator\)
- * complement: `-`
-* Unary operators \(post-operator\)
- * conversion \(flip\): `~`
- * Reflexive, transitive closure: `*` \(Kleene star\) --currently not implemented
- * transitive closure: `+` \(Kleene plus\) --currently not implemented
-
-#### MEANING\*
+Note that when an atom is deleted, also every pair \(in any relation\) is deleted if either its source atom or target atom is the deleted atom.
-The meaning of a rule can be written in natural language in the Meaning part of the RULE statement.
-It is a good habit to specify the meaning! The meaning will be printed in the functional specification.
-The meaning is optional.
+#### Example \(`_;`\)
-##### Syntax
+When you try to create or delete pairs with atoms that contain texts, you may find that some texts contain the semi-colon. When such a text is used in a violation statement, this will be interpreted as an argument separator, causing all sorts of unexpected results. This can be prevented by using `_;` rather than `;` as an argument separator. However, the ExecEngine must be made aware that this alternative argument separator is used. This is done by mentioning it immediately at the beginning of a function call, as in the below example:
```text
-MEANING Language? Markup? <text>
+VIOLATION (TXT "{EX}_;InsPair_;r1_;A_;", SRC I, TXT "_;B_;", TGT I)
```
-The `<text>` part is where the the meaning is written down. We support both:
+Of course, if the SRC or TGT atom is a text that contains the characters `_;`, the problem still remains...
-* a simple string, enclosed by double quotes
-* any text, starting with `{+` and ending with `-}`
+#### Example \(`TransitiveClosure`\)
-The optional language is specified as
+Consider the `r :: A * A [IRF,ASY]`. In relation algebra, terms such as `r+` or `r*` are allowed, designating the transitive closure of `r`. The `+` and `*` operators are currently not supported in Ampersand.
-* `IN ENGLISH` or
-* `IN DUTCH`.
+This section describes a workaround that allows you to use transitive closures.To do so, we simply define a relation `rPlus :: A * A` and/or `rStar :: A * A`, and define the following automated rules to populate these relations:
-The optional Markup is one of :
+```text
+ ROLE ExecEngine MAINTAINS "Grow rPlus"
+ RULE "Grow rPlus": r;rPlus \/ rPlus;r |- rPlus
+ VIOLATION (TXT "{EX} InsPair;rPlus;A;", SRC I, TXT ";A;", TGT I)
-* `REST` \(Restructured text\)
-* `HTML`
-* `LATEX`
-* `MARKDOWN`
+ ROLE ExecEngine MAINTAINS "Shrink rPlus"
+ RULE "Shrink rPlus": rPlus |- r;rPlus \/ rPlus;r
+ VIOLATION (TXT "{EX} DelPair;rPlus;A;", SRC I, TXT ";A;", TGT I)
-If you need specific markup, there are several options to do so. The default markup is used, but you can override that here. We rely on [Pandoc](http://pandoc.org/) to read the markup.
+ ROLE ExecEngine MAINTAINS "Grow rStar"
+ RULE "Grow rStar": r \/ r;rStar \/ rStar;r |- rStar
+ VIOLATION (TXT "{EX} InsPair;rStar;A;", SRC I, TXT ";A;", TGT I)
-#### MESSAGE\*
+ ROLE ExecEngine MAINTAINS "Shrink rStar"
+ RULE "Shrink rStar": rStar |- r \/ r;rStar \/ rStar;r
+ VIOLATION (TXT "{EX} DelPair;rStar;A;", SRC I, TXT ";A;", TGT I)
+```
-Messages may be defined to give feedback whenever the rule is violated. The message is a predefined string. Every message for a rule should be for another Language.
+While this works \(certainly in theory\), a practical issue is that it quickly becomes very timeconsuming as the population of `r` grows, up to an unacceptable level. Also, Ampersand prototypes have a time limit \(30 or 60 seconds\) for an ExecEngine run. In order to make transitive closures a bit more practicable \(but certainly not workable for 'real' software\), we can use the predefined ExecEngine function `TransitiveClosure`, as follows:
```text
-MESSAGE Markup
+ rCopy :: A * A
+ MEANING "a copy of the relation `r`, needed to detect deletions in `r`"
+
+ rPlus :: A * A
+ ROLE ExecEngine MAINTAINS "Warshall on r"
+ RULE "Warshall on r": rCopy = r
+ VIOLATION (TXT "{EX} TransitiveClosure;r;A;rCopy;rPlus")
```
-#### VIOLATION?
+What this does is the following. Any time that `r` is being \(de\)populated, the rule `Warshall on r` is violated. This calls the \(predefined\) function `TransitiveClosure` with its four arguments, the result of which is that 1. the relation `rPlus` is computed as the \(smallest\) transitive closure of `r` \(using the Warshall algorithm\); 2. the relation `rCopy` is made to have the same population as `r`, thereby resolving all violations of the rule.
-A violation message can be constructed so that it gives specific information about the violating atoms:
+Note that if you want to use \(the equivalent of\) `r*` somewhere in an term, the most practical way is to use the term `(I \/ rPlus)` at that spot.
+
+#### HELP! I got errors!
+
+As an Ampersand user, you are used to getting error messages from the compiler. Yet, errors in rules for the Exec-engine are not signalled by the compiler. Instead, you get runtime error message that some inexperienced users find hard to work with, as it requires some knowledge of the backgrounds.
+
+Here are some tips.
+1. Most \(all?\) predefined functions check for a valid number of arguments. If the error message relates to the number of arguments,
+ 1. you have missed out on a `;`. The function `NewStruct` is well-known to produce this error, because of the wealth of arguments allowed. Learning and maintaining a strict discipline regarding how you write such \(e.g. `NewStruct`\) statements is a big help in preventing this error from occurring.
+ 2. you may have too many `;`s. Of course, you may just mistakenly having written too many `;`s. Another, less known cause is where a violation occurs on an atom that happens to be a text containing one or more `;` characters. This will cause the ExecEngine to interpret the text as multiple arguments, which \(usually\) results in an illegal number of arguments error. The cure is to use the `_;` separator rather than the `;` separator \(see the appropriate section above\).
+2. Most \(all?\) predefined functions that have arguments to specify a relation definition, will check \(at runtime\) whether or not this relation is actually defined \(at define-time\). Misspellings in relation or concept names \(e.g. capitalizations\) often cause this error.
+3. You should specify a relation just with its name, e.g. `project` \(not: `project[Assignment*Project]`\). The reason for this is that it \(currently\) is the ExecEngine itself that parses the violation string \(rather than the Ampersand compiler\). This very simple parser does not handle `[Assignment*Project]`-like constructs.
+4. For the same reason \(simple ExecEngine parser\), there is no type checking for the ExecEngine functions. This means that you must check yourself whether or not the type of atom\(s\) you want to insert or delete match with the source or target atom of the relation you try to \(de\)populate.
+5. Look at the log window to get more information on what is actually happening when the ExecEngine executes. You can turn it on by clicking on the left-most icon of the icon-list that is at the right hand side in the menu bar. There, you turn on the 'Show log window'. In the log window, you can select what you do and do not see. Options you may want to select include 'ExecEngine', 'RuleEngine' and 'Database'.
+6. If everything else fails, read the error messages and log lines slowly and carefully, as they \(sometimes unexpectedly\) do provide information that may actually help you to resolve the issue at hand.
+
+For the time that researchers are working on this problem, you will have to live with all this. It makes programming of automated rules initially error-prone and time consuming, but when you get the hang of it, it gets better. Still, the best piece of advice we can currently give here is:
+
+* Keep automated rules simple.
+* Test thoroughly.
+
+#### Ways to run the ExecEngine \(one or more times\)
+
+The ExecEngine currently is a simple one. Whenever it executes, it evaluates the automated rules one after another. Whenever an automated rule produces violations, the associated violation text is executed for every such violation.
+
+While rules are most often evaluated in the order in which they are defined, you really should not make any assumptions about the evaluation order \(nor about the order in which violations of a rule are processed\). Hence, it may happen that the violations are processed 'out of order', resulting in violations of automated rules that could 'easily' have been fixed.
+
+To overcome this issue, the ExecEngine \(by default\) simply runs itself again, until all automated rules have no violations any more, or until the maximum amount of such reruns has been reached - this limit is set to guarantee that execution terminates. The default number of maximum reruns is 10 \(decimal\). You can modify this setting in `LocalSettings.php`, , by \(including and/or\) modifying the following texts:
```text
-VIOLATION (Segment1,Segment2,... )
+ Config::set('maxRunCount', 'execEngine', 10);
```
-Every segment must be of one of the following forms:
+For research or debugging purposes, it may sometimes be neccesary to have further control over the manner in which the ExecEngine does. There are three possibilities for running the ExecEngine:
-* `TXT` String
-* `SRC` Term
-* `TGT` Term
+1. Automatically. This is the default behaviour. Turning the autoRerun feature off means that the ExecEngine will always run only once when called. You can specify this in the file `LocalSettings.php`, by replacing the text `true` by `false` in the line that contains the text:
-A rule is violated by a pair of atoms \(source, target\). The source atom is the root of the violation message. In the message the target atoms are printed. With the Identity relation the root atom itself can be printed. You can use a term to print other atoms. Below two examples reporting a violation of the rule that each project must have a project leader. The first prints the project's ID, the second the project's name using the relation projectName:
+ `Config::set('autoRerun', 'execEngine', true);`
-`VIOLATION ( TXT "Project ", SRC I, TXT " does not have a projectleader")`
+2. Manually. This is when you, as a user, clik on the `refresh/reset options` icon in a prototype, and the select `Run execution engine`. Note that if you also use logins, you must have been assigned a role that allows you to do this, or you won't see this option.
+3. By using the ExecEngine function `RerunExecEngine`, which takes one argument \(an explanatory text, that is used for logging - see the example below\). Whenever the ExecEngine calls this function, a flag is set requesting a rerun. When, at the end of an ExecEngine run, this flag is set, the ExecEngine will run itself again.
-`VIOLATION ( TXT "Project ", SRC projectName, TXT " does not have a projectleader")`
+Here is an example of how `RerunExecEngine` can be used to create a transitive closure:
+
+```text
+ r :: A * A [ASY]
+ rStar :: A * A -- This will contain a transitive closure
+
+ ROLE ExecEngine MAINTAINS "InsPair on rStar"
+ RULE "InsPair on rStar": r \/ r;rStar \/ rStar;r |- rStar
+ VIOLATION (TXT "{EX} InsPair;rStar;A;", SRC I, TXT ";A;", TGT I
+ ,TXT "{EX} RerunExecEngine;InsPair on rStar"
+ )
+ ROLE ExecEngine MAINTAINS "DelPair on rStar"
+ RULE "DelPair on rStar": rStar |- r \/ r;rStar \/ rStar;r
+ VIOLATION (TXT "{EX} DelPair;rStar;A;", SRC I, TXT ";A;", TGT I
+ ,TXT "{EX} RerunExecEngine;DelPair on rStar"
+ )
+```
-### ROLE MAINTAINS
+### Current date
+The runtime system of Ampersand contains a function that produces the current date. Here is an example how to use it:
-By default rules are invariant rules.
-By preceding the rule statement with a role specification for this rule, the rule becomes a process rule.
+```
+CONTEXT CurrentDate
+
+ RELATION sessionToday[SESSION*Date] -- or whatever the DateTime concept is called
+ REPRESENT Date TYPE DATE
+ ROLE ExecEngine MAINTAINS "Initialize today's date"
+ RULE "Initialize today's date": I[SESSION] |- sessionToday;sessionToday~
+ VIOLATION (TXT "{EX} SetToday;sessionToday;SESSION;", SRC I, TXT ";Date")
+INTERFACE Overview : "_SESSION" cRud
+BOX [ date : sessionToday cRuD ]
+ENDCONTEXT
+```
+If you run this program, this is what you'll see
+<!--  -->
+#### Explanation
+The rule "Initialize today's date" tells us that there must be a date for every session. When your session starts, there is a session atom: `_SESSION`. The relation `sessionToday` does not relate that session atom to a date, so the rule is violated. As a consequence, the ExecEngine triggers the violation and calls the function `SetToday`. That PHP-function creates the desired link in the relation `sessionToday`. That is then displayed in the user screen.
diff --git a/docs/reference-material/the-language-ampersand/terms/semantics.md b/docs/reference-material/terms.md
similarity index 58%
rename from docs/reference-material/the-language-ampersand/terms/semantics.md
rename to docs/reference-material/terms.md
index e1617c5faa..26e3856af9 100644
--- a/docs/reference-material/the-language-ampersand/terms/semantics.md
+++ b/docs/reference-material/terms.md
@@ -1,36 +1,116 @@
---
description: >-
- Semantics tell us about meaning. About how to interpret terms and their
- operators.
+ This page describes the notion of term. Its subpages provide several
+ interpretations of terms, all of which are valid so you can use each
+ interpretation at your own discretion.
---
-# Semantics
+# Terms
+
+## Purpose
+
+The purpose of a term is to compute pairs that constitute a relation. We use operators to assemble terms from smaller terms, to express in formal language precisely what is meant in the natural language of the business. The smallest term is a single relation.
+
+We noticed that our readers have different backgrounds. They have different preferences about the way we explain the operators in Ampersand. Some prefer an explanation in logic, others in algebra, and still others in set theory. So we decided to [explain the operators](#semantics) in many different ways simultaneously, hoping that one of them suits your preference.
+
+## Description
+
+A term is a combination of operators and relations. Its meaning is a set of pairs, which is in fact a newly created relation. The word "expression" may be used as a synonym for "term" in the context of Ampersand.
+
+## Examples
+
+`owner`
+
+`r;s~`
+
+`I /\ goalkeeper;goalkeeper~`
+
+`destination;"Algarve" |- spoken;"Portugese"`
+
+## Syntax
+
+Every term is built out of relations, which are combined by operators. An term has one of the following 8 syntactic structures
+
+```
+<Term> <BinaryOperator> <Term>
+<UnaryOpPre> <Term>
+<Term> <UnaryOpPost>
+<RelationRef> <type>?
+I <type>?
+V <type>?
+<atom>
+( <Term> )
+```
+
+## `Operators`
+
+The operators come in families. We advise novices to study only the rule operators, boolean operators and relational operators. There is a wealth of things you can express with just these operators. The residual operators seem harder to learn and the Kleene operators are not fully implemented yet. You can click the hyperlink to navigate to the semantics of each family.
+
+| 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 |
+| [relational](#relational-operators-in-logic) | $$;$$, $$\times$$, and $$\dagger$$ | 4 | $$\smallsmile$$ | postfix |
+| [residual](#residual-operators-in-logic) | $$\backslash$$, $$/$$, and $$♢$$ | 3 | | |
+| Kleene | | | $$∗$$ and $$+$$ | postfix |
+
+## Brackets
+
+Operators with different binding power may be used in the same term without brackets, because the binding power tells how it is interpreted. For example, $$r\cap s;t$$ means $$r\cap(s;t)$$ because $$;$$ has a higher binding power than $$\cap$$.
+
+Operators with the same binding power must be used unambiguously. For example: $$r\cap(s-t)$$ means something different than $$(r\cap s)-t$$. In such cases Ampersand insists on the use of brackets, so readers without knowledge of the binding powers of the operators can read a term unambiguously.
+
+Repeated uses of an associative operator does not require brackets. So $$r\cap s \cap t$$ is allowed because $$\cap$$ is associative.
+
+## Notation on the keyboard
+
+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 |
+
+## Semantics
We present the semantics of terms in 5 different (but equivalent) ways: one explanation in terms of logic, one in set theory, one in terms of axioms (algebraically), one in natural language, and one visual explanation. These ways are equivalent, so you can interpret a term in any of the presented ways. Any way will do; take your pick!
-| Category | Logic | Sets | Axioms | Natural Language | Visual |
-| --------------- | --------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| primitive terms | [logic](#primitive-terms-in-logic) | [set theory](#primitive-terms-in-set-theory) | axioms | [natural language](#primitive-terms-in-natural-language) | visual |
-| boolean | [logic](#boolean-operators-in-logic) | [set theory](#boolean-operators-in-set-theory) | [axioms](#boolean-operators-in-algebra) | [natural language](#boolean-operators-in-natural-language) | [visual](#boolean-operators-visualized) |
+| Category | Logic | Sets | Axioms | Natural Language | Visual |
+| --------------- | --------------------------------------- | ------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | ------------------------------------------ |
+| primitive terms | [logic](#primitive-terms-in-logic) | [set theory](#primitive-terms-in-set-theory) | axioms | [natural language](#primitive-terms-in-natural-language) | visual |
+| boolean | [logic](#boolean-operators-in-logic) | [set theory](#boolean-operators-in-set-theory) | [axioms](#boolean-operators-in-algebra) | [natural language](#boolean-operators-in-natural-language) | [visual](#boolean-operators-visualized) |
| relational | [logic](#relational-operators-in-logic) | [set theory](#relational-operators-in-set-theory) | [axioms](#relational-operators-in-algebra) | [natural language](#relational-operators-in-natural-language) | [visual](#relational-operators-visualized) |
-| residual | [logic](#residual-operators-in-logic) | set theory | | [natural language](#residual-operators-in-natural-language) | [visual](#semantics-visualized) |
-| products | logic | set theory | axioms | natural language | visual |
+| residual | [logic](#residual-operators-in-logic) | set theory | | [natural language](#residual-operators-in-natural-language) | [visual](#semantics-visualized) |
+| products | logic | set theory | axioms | natural language | visual |
(the pages without hyperlinks are yet to be made).
-## Semantics in logic
+### Semantics in logic
-### Primitive terms in logic
+#### Primitive terms in logic
-#### Relations
+##### Relations
-When a [relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) is used in a term, it stands for all pairs it contains at the moment it is evaluated. Those pairs (also referred to as the _**contents**_ or _**population**_ of the relation) can change over time as users add or delete pairs from it.
+When a [relation](./syntax-of-ampersand#the-relation-statement) is used in a term, it stands for all pairs it contains at the moment it is evaluated. Those pairs (also referred to as the _**contents**_ or _**population**_ of the relation) can change over time as users add or delete pairs from it.
-When a relation is used in a term, we can just use its name if that is unambiguous. For instance the name `owner` refers to `RELATION owner[Person*Building]` if that is the only relation the ampersand-compiler can link it to. In some cases, however the name alone is ambiguous. For example if there are two relations with the same name and different signatures. In such cases Ampersand will try to infer the type from the context. That however does not always succeed. In such cases, Ampersand generates an error message that asks you to remove the ambiguity by adding the correct type.
+When a relation is used in a term, we can just use its name if that is unambiguous. For instance the name `owner` refers to `RELATION owner[Person*Building]` if that is the only relation the ampersand-compiler can link it to. In some cases, however the name alone is ambiguous. For example if there are two relations with the same name and different signatures. In such cases Ampersand will try to infer the type from the context. That however does not always succeed. In such cases, Ampersand generates an error message that asks you to remove the ambiguity by adding the correct type.
If a pair $$(a,b)$$ is an element of a relation $$r$$, we write $$a\ r\ b$$. Alternatively we may write $$(a,b)\in r$$ , since we know that $$r$$ is a set.
-#### Identity
+##### Identity
For every concept $$C$$, the term $$I_{[C]}$$ exists. It refers to the _**identity relation**_. It means that for every $$a\in C$$ and $$b\in C$$ we have:
@@ -40,7 +120,7 @@ $$
The type of $$I_{[C]}$$ is $$[C*C]$$. In Ampersand code you write `I[C]`.
-#### Complete relation
+##### Complete relation
For every pair of concepts $$A$$ and $$B$$ the term $$V_{[A*B]}$$ refers to the _**complete relation**_. For every $$a\in A$$ and $$b\in B$$ we have:
@@ -50,32 +130,31 @@ $$
The type of $$V_{[A*B]}$$ is $$[A*B]$$. In Ampersand code you write `V[A*B]`.
-
-### Boolean operators in logic
+#### Boolean operators in logic
The notation $$a\ r\ b$$ means that the pair (a,b) is in relation $$r$$. This page defines when pair (a,b) is in relation $$r ∩ s$$ (the intersection of $$r$$ and $$s$$), $$r ∪ s$$ (the union of $$r$$ and $$s$$), $$r-s$$ (the difference of $$r$$ and $$s$$).
-* intersection : $$a\ (r ∩ s)\ b\ \Leftrightarrow\ a\ r\ b\ ∧\ a\ s\ b$$ . In other words: if the pair $$(a,b)$$ is both in relation $$r$$ and $$s$$, then it is in the intersection of $$r$$ and $$s$$.
-* union : $$a\ (r ∪ s)\ b\ \Leftrightarrow\ a\ r\ b\ \vee\ a\ s\ b$$ . In words: if the pair $$(a,b)$$ is in the relation $$r$$ or in $$s$$, then it is in the union of $$r$$ and $$s$$.
-* difference : $$a\ (r-s)\ b\ \Leftrightarrow\ a\ r\ b\ ∧\ \neg(a\ s\ b)$$. In other words, the term $$r-s$$ contains all pairs from $$r$$ that are not in $$s$$.
+- intersection : $$a\ (r ∩ s)\ b\ \Leftrightarrow\ a\ r\ b\ ∧\ a\ s\ b$$ . In other words: if the pair $$(a,b)$$ is both in relation $$r$$ and $$s$$, then it is in the intersection of $$r$$ and $$s$$.
+- union : $$a\ (r ∪ s)\ b\ \Leftrightarrow\ a\ r\ b\ \vee\ a\ s\ b$$ . In words: if the pair $$(a,b)$$ is in the relation $$r$$ or in $$s$$, then it is in the union of $$r$$ and $$s$$.
+- difference : $$a\ (r-s)\ b\ \Leftrightarrow\ a\ r\ b\ ∧\ \neg(a\ s\ b)$$. In other words, the term $$r-s$$ contains all pairs from $$r$$ that are not in $$s$$.
The complement (or negation) of a relation $$r_{[A x B]}$$ is defined by means of the difference operator:
-* complement : If $$r$$ is defined as $$r_{A\times B}$$, then $$\overline{r}$$ is the set of all tuples in $$A\times B$$ (the Cartesian product) that are not contained in $$r$$. So $$\overline{r} = V_{[A\times B]} - r$$
+- complement : If $$r$$ is defined as $$r_{A\times B}$$, then $$\overline{r}$$ is the set of all tuples in $$A\times B$$ (the Cartesian product) that are not contained in $$r$$. So $$\overline{r} = V_{[A\times B]} - r$$
Note that the complement is defined in terms of $$A$$ and $$B$$. So, two relations with an identical population yet a different type may have different complements.
-#### How to type boolean operators in your script
+##### How to type boolean operators in your script
-[This page](../#notation-on-the-keyboard) shows how you can type boolean (and other) operators in your Ampersand script.
+[This page](#notation-on-the-keyboard) shows how you can type boolean (and other) operators in your Ampersand script.
-### Relational operators in logic
+#### Relational operators in logic
-#### Purpose of relational operators
+##### Purpose of relational operators
To say things such as "the name of the owner", we want to string together multiple relations \(viz. `name` and `owner`\). Relational operators allow us to make such statements.
-#### Converse
+##### 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:
@@ -85,7 +164,7 @@ $$
If $$r$$ has type$$[A\times B]$$, then $$r\smallsmile\$$ has type $$[B\times A]$$.
-#### Composition
+##### Composition
The composition operator is denoted by a semicolon $$;$$ between two terms. It is pronounced as 'composed with'. Let us take a look at $$r$$ composed with $$s$$. Let $$r_{[A\times B]}$$ and $$s_{[B\times C]}$$ be two relations, with the target of r being the same as the source of s. Then the composition of $$r$$ and $$s$$ is defined by:
@@ -95,48 +174,48 @@ $$
If $$r$$ has type$$[A\times B]$$and $$s$$has type$$[B\times C]$$, then $$r;s$$ has type $$[A\times C]$$.
-#### How to type boolean operators in your script
+##### How to type boolean operators in your script
-[This page](../#notation-on-the-keyboard) shows how you can type boolean \(and other\) operators in your Ampersand script.
+[This page](#notation-on-the-keyboard) shows how you can type boolean \(and other\) operators in your Ampersand script.
-### Residual operators in logic
+#### Residual operators in logic
[Residual operators](https://en.wikipedia.org/wiki/Residuated_Boolean_algebra) are used when "[material implication](https://en.wikipedia.org/wiki/Material_implication_%28rule_of_inference%29)" is involved.
-* right residual : $$a\ (r\backslash s)\ b\ \Leftrightarrow\ \forall x: x\ r\ a\rightarrow x\ s\ b$$ . In other words: $$(a,b)$$ is in the right residual of $$r$$ and $$s$$ means that for every $$x$$, pair $$(x,a)$$ is in relation $$r$$ implies that pair $$(x,b)$$ is in $$s$$.
-* left residual : $$a\ (s/r)\ b\ \Leftrightarrow\ \forall x: b\ r\ x\rightarrow a\ s\ x$$ . In words: $$(a,b)$$ is in the left residual of $$s$$ and $$r$$
+- right residual : $$a\ (r\backslash s)\ b\ \Leftrightarrow\ \forall x: x\ r\ a\rightarrow x\ s\ b$$ . In other words: $$(a,b)$$ is in the right residual of $$r$$ and $$s$$ means that for every $$x$$, pair $$(x,a)$$ is in relation $$r$$ implies that pair $$(x,b)$$ is in $$s$$.
+- left residual : $$a\ (s/r)\ b\ \Leftrightarrow\ \forall x: b\ r\ x\rightarrow a\ s\ x$$ . In words: $$(a,b)$$ is in the left residual of $$s$$ and $$r$$
means that for every $$x$$ pair$$(b,x)$$ is in relation $$r$$ implies that pair $$(a,x)$$ is in $$s$$.
-* diamond: $$a (r♢s) b\ \Leftrightarrow\ \forall x: a\ r\ x\ =\ x\ s\ b$$. In words: For every $$x$$, both $$a\ r\ x$$ and $$x\ s\ b$$ are true or both are false.
+- diamond: $$a (r♢s) b\ \Leftrightarrow\ \forall x: a\ r\ x\ =\ x\ s\ b$$. In words: For every $$x$$, both $$a\ r\ x$$ and $$x\ s\ b$$ are true or both are false.
-#### How to type boolean operators in your script
+##### How to type boolean operators in your script
-[This page](../#notation-on-the-keyboard) shows how you can type boolean \(and other\) operators in your Ampersand script.
+[This page](#notation-on-the-keyboard) shows how you can type boolean \(and other\) operators in your Ampersand script.
-## Semantics in natural language
+### Semantics in natural language
-### Primitive terms in natural language
+#### Primitive terms in natural language
-#### Relations
+##### Relations
-When a [relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) is used in a term, it stands for a set of facts that are assumed true on the current time in the current context. Those facts \(also referred to as the contents or the population of the relation\) can change over time as users add or delete facts from it.
+When a [relation](./syntax-of-ampersand#the-relation-statement) is used in a term, it stands for a set of facts that are assumed true on the current time in the current context. Those facts \(also referred to as the contents or the population of the relation\) can change over time as users add or delete facts from it.
-When a relation is used in a term, we can simply use its name if that is unambiguous. For instance the name `owner` refers to `RELATION owner[Person*Building]` if that is the only relation the ampersand-compiler can link it to. In some cases, however the name alone is ambiguous. For example if there are two relations with the same name and different signatures. In such cases Ampersand will try to infer the type from the context. That however does not always succeed. In such cases, Ampersand generates an error message that asks you to remove the ambiguity by adding the correct type.
+When a relation is used in a term, we can simply use its name if that is unambiguous. For instance the name `owner` refers to `RELATION owner[Person*Building]` if that is the only relation the ampersand-compiler can link it to. In some cases, however the name alone is ambiguous. For example if there are two relations with the same name and different signatures. In such cases Ampersand will try to infer the type from the context. That however does not always succeed. In such cases, Ampersand generates an error message that asks you to remove the ambiguity by adding the correct type.
If a pair $$(a,b)$$ is an element of a relation $$r$$, we write $$a\ r\ b$$ to denote the fact. It means that we consider $$a\ r\ b$$ to be true \(within the current context\).
-#### Identity
+##### Identity
Every atom in a concept $$C$$ identifies itself. If for example concept "Person" contains atoms {"Ann", "Bob", "Cecil"}, "Ann" identifies "Ann", "Bob" identifies "Bob", and "Cecil" identifies "Cecil". This makes "Ann" and "Bob" different atoms \(unequal\).
-### Boolean operators in natural language
+#### Boolean operators in natural language
-#### Purpose of boolean operators
+##### Purpose of boolean operators
-To say things such as pair `("peter","macbook")` is either in relation `ownsa` or `wantsa`, requires us to use boolean operators $$\cup$$, $$\cap$$, and $$-$$ .
+To say things such as pair `("peter","macbook")` is either in relation `ownsa` or `wantsa`, requires us to use boolean operators $$\cup$$, $$\cap$$, and $$-$$ .
-#### Meaning
+##### Meaning
Let us explain the meaning of relational operators $$\cup$$, $$\cap$$, and $$-$$ by means of examples.
@@ -144,38 +223,38 @@ Assume we have a relation, `ownsa[Person*LaptopType]`, which contains the person
Also assume another relation `wantsa[Person*LaptopType]`, which contains the persons who want a particular type of laptop. A fact `"peter" wantsa "macbook"` means that Peter wants a MacBook.
-#### Union
+##### Union
The sentence: "Peter owns a MacBook or Peter wants a MacBook." is represented as\
`"peter"` (`ownsa` $$\cup$$ `wantsa`) `"macbook"`.
-#### Intersection
+##### Intersection
The sentence: "Peter owns a MacBook and Peter wants a MacBook." is represented as\
`"peter"` (`label` $$\cap$$ `colour`) `"macbook"`.
-#### Difference
+##### Difference
The sentence: "Peter owns a MacBook and Peter does not want a MacBook." is represented as\
`"peter"` (`label` $$-$$ `colour`) `"macbook"`.
-#### Natural language templates
+##### Natural language templates
-There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](https://ampersandtarski.gitbook.io/documentation/\~/drafts/-LKR7o8ALsxT8aQfWugs/primary/ampersands-own-language/semantics-visualized/semantics-visualized). The systematic translation is given in the following table:
+There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](https://ampersandtarski.gitbook.io/documentation/~/drafts/-LKR7o8ALsxT8aQfWugs/primary/ampersands-own-language/semantics-visualized/semantics-visualized). The systematic translation is given in the following table:
-| Formally | Natural language template |
-| --------------------- | ------------------------- |
-| $$a\ (r\cup s)\ b$$ | `a r b `or `a s b`. |
-| $$a\ (r\cap s)\ b$$ | `a r b `and `a s b`. |
-| $$a\ (r-s)\ b$$ | `a r b `and not`a s b`. |
+| Formally | Natural language template |
+| ------------------- | ------------------------- |
+| $$a\ (r\cup s)\ b$$ | `a r b `or `a s b`. |
+| $$a\ (r\cap s)\ b$$ | `a r b `and `a s b`. |
+| $$a\ (r-s)\ b$$ | `a r b `and not`a s b`. |
-### Relational operators in natural language
+#### Relational operators in natural language
-#### Purpose of relational operators
+##### Purpose of relational operators
To say things such as "the name of the owner", we want to string together multiple relations (viz. `name` and `owner`). Relational operators allow us to make such statements.
-#### Meaning
+##### Meaning
The meaning of relational operators $$\smallsmile$$ and $$;$$ is best explained by means of examples.
@@ -183,19 +262,19 @@ Assume we have a relation, `label[Contract*Colour]`, which contains the colour o
Also assume another relation `stored[Contract*Location]`, which gives the location where a contract is stored. Fact `"1834" store "cabinet 42"` means that contract 1834 is stored in cabinet 42.
-#### Converse
+##### 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)$$. In natural language, however, the meaning does not change. So if`"1834" label "blue"` means that contract 1834 has a blue label, `"blue" label~ "1834"` also means that contract 1834 has a blue label.
+A relation can be altered by swapping the elements of every pair in the relation. Mathematically, $$(a, b)$$ is a different from $$(b,a)$$. In natural language, however, the meaning does not change. So if`"1834" label "blue"` means that contract 1834 has a blue label, `"blue" label~ "1834"` also means that contract 1834 has a blue label.
-* The sentence: "All contracts with a blue label are stored in cabinet 42." is represented as `"blue" (label\stored) "cabinet 42"`. Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42.
+- The sentence: "All contracts with a blue label are stored in cabinet 42." is represented as `"blue" (label\stored) "cabinet 42"`. Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42.
-#### Composition
+##### Composition
-The sentence "A _contract with a blue label is stored in cabinet 42_." can be represented as `"blue" (label~;stored) "cabinet 42"`. Literally it says: There is a contract that has a blue label and is stored in cabinet 42.
+The sentence "A _contract with a blue label is stored in cabinet 42_." can be represented as `"blue" (label~;stored) "cabinet 42"`. Literally it says: There is a contract that has a blue label and is stored in cabinet 42.
-#### Natural language templates
+##### Natural language templates
-There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](https://ampersandtarski.gitbook.io/documentation/\~/drafts/-LKR7o8ALsxT8aQfWugs/primary/ampersands-own-language/semantics-visualized/semantics-visualized). The systematic translation is given in the following table:
+There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](https://ampersandtarski.gitbook.io/documentation/~/drafts/-LKR7o8ALsxT8aQfWugs/primary/ampersands-own-language/semantics-visualized/semantics-visualized). The systematic translation is given in the following table:
| Formally | Natural language template |
| ----------- | ------------------------------------------- |
@@ -204,7 +283,7 @@ There is a pattern to this. A computer can generate a literal translation from t
The natural language translation for `b r~ a`is the same as language translation for `a r b`.
-### Residual operators in natural language
+#### Residual operators in natural language
The meaning of residual operators $$/$$, $$\backslash$$, and $$\diamond$$ is best explained by means of examples.
@@ -212,33 +291,33 @@ Assume we have a relation, `label[Contract*Colour]`, which contains the colour o
Also assume another relation `stored[Contract*Location]`, which gives the location where a contract is stored. Fact `"1834" store "cabinet 42"` means that contract 1834 is stored in cabinet 42.
-* The sentence: "All contracts with a blue label are stored in cabinet 42." is represented as `"blue" (label\stored) "cabinet 42"`. Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42.
-* The sentence: "All contracts that are stored in cabinet 42 have a blue label." is represented as `"blue" (label~/stored~) "cabinet 42"`. Literally it says: For every contract, if it is stored in cabinet 42, then it has a blue label.
-* The sentence: "All blue labeled contracts and no others are stored in cabinet 42." is represented as `"blue" (label~<>stored) "cabinet 42"`. Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42 and if it is stored in cabinet 42, then it has a blue label.
+- The sentence: "All contracts with a blue label are stored in cabinet 42." is represented as `"blue" (label\stored) "cabinet 42"`. Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42.
+- The sentence: "All contracts that are stored in cabinet 42 have a blue label." is represented as `"blue" (label~/stored~) "cabinet 42"`. Literally it says: For every contract, if it is stored in cabinet 42, then it has a blue label.
+- The sentence: "All blue labeled contracts and no others are stored in cabinet 42." is represented as `"blue" (label~<>stored) "cabinet 42"`. Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42 and if it is stored in cabinet 42, then it has a blue label.
-#### Natural language templates
+##### Natural language templates
There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](#semantics-visualized). The systematic translation is given in the following table:
-| Formally | Natural language template |
-| :--- | :--- |
-| `a (r\s) b` | For every `x`: if `x r a`then `x s b`. |
-| `a (r/s) b` | For every `x`: if `b s x` then `a r x`. |
+| Formally | Natural language template |
+| :----------- | :------------------------------------------------------------------ |
+| `a (r\s) b` | For every `x`: if `x r a`then `x s b`. |
+| `a (r/s) b` | For every `x`: if `b s x` then `a r x`. |
| `a (r<>s) b` | For every `x`: if `a r x` then `x s b` and if `x s b` then `a r x`. |
-## Semantics in set theory
+### Semantics in set theory
-### Primitive terms in set theory
+#### Primitive terms in set theory
-#### Relations
+##### Relations
-When a [relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) is used in a term, it stands for the set of pairs it contains at the moment it is evaluated. That set \(also referred to as the contents of the relation\) can change over time as users add or delete pairs from it.
+When a [relation](./syntax-of-ampersand#the-relation-statement) is used in a term, it stands for the set of pairs it contains at the moment it is evaluated. That set \(also referred to as the contents of the relation\) can change over time as users add or delete pairs from it.
-When a relation is used in a term, we can simply use its name if that is unambiguous. For instance the name `owner` refers to `RELATION owner[Person*Building]` if that is the only relation the ampersand-compiler can link it to. In some cases, however the name alone is ambiguous. For example if there are two relations with the same name and different signatures. In such cases Ampersand will try to infer the type from the context. That however does not always succeed. In such cases, Ampersand generates an error message that asks you to remove the ambiguity by adding the correct type.
+When a relation is used in a term, we can simply use its name if that is unambiguous. For instance the name `owner` refers to `RELATION owner[Person*Building]` if that is the only relation the ampersand-compiler can link it to. In some cases, however the name alone is ambiguous. For example if there are two relations with the same name and different signatures. In such cases Ampersand will try to infer the type from the context. That however does not always succeed. In such cases, Ampersand generates an error message that asks you to remove the ambiguity by adding the correct type.
If a pair $$(a,b)$$ is an element of a relation $$r$$, we write $$(a,b)\in r$$. Alternatively we may write $$a\ r\ b$$.
-#### Identity
+##### Identity
For every concept $$C$$, the term $$I_{[C]}$$ represents the _**identity relation**_. It is defined by:
@@ -248,7 +327,7 @@ $$
The type of $$I_{[C]}$$ is $$[C*C]$$. In Ampersand code you write `I[C]`.
-#### Complete relation
+##### Complete relation
For every pair of concepts $$A$$ and $$B$$ the term $$V_{[A*B]}$$ represents the _**complete relation**_. It is defined by:
@@ -258,31 +337,31 @@ $$
The type of $$V_{[A*B]}$$ is $$[A*B]$$. In Ampersand code you write `V[A*B]`.
-### Boolean operators in set theory
+#### Boolean operators in set theory
A relation is by definition a subset of the Cartesian Product of the source and target sets. So, if two different relations r and s are defined on the same source A and target B, then the ordinary set operators can be applied to produce a new relation.
-* intersection : $$r ∩ s$$ is the set that contains the elements that are contained in relation $$r$$ as well as in $$s$$, or $$r ∩ s\ =\ \{ (x,y)\ |\ (x,y) ∈ r ∧ (x,y) ∈ s \}$$
-* union : $$r ∪ s$$ is the set that contains all elements that are contained either in relation $$r$$ or in $$s$$, or $$r ∪ s\ =\ \{ (x,y)\ |\ (x,y) ∈ r ∨ (x,y) ∈ s \}$$
-* difference : $$r - s$$ is the set that contains the elements of relation $$r$$ that are not contained in $$s$$, or $$r - s\ =\ \{ (x,y)\ |\ (x,y) ∈ r ∧ (x,y) ∉ s \}$$
+- intersection : $$r ∩ s$$ is the set that contains the elements that are contained in relation $$r$$ as well as in $$s$$, or $$r ∩ s\ =\ \{ (x,y)\ |\ (x,y) ∈ r ∧ (x,y) ∈ s \}$$
+- union : $$r ∪ s$$ is the set that contains all elements that are contained either in relation $$r$$ or in $$s$$, or $$r ∪ s\ =\ \{ (x,y)\ |\ (x,y) ∈ r ∨ (x,y) ∈ s \}$$
+- difference : $$r - s$$ is the set that contains the elements of relation $$r$$ that are not contained in $$s$$, or $$r - s\ =\ \{ (x,y)\ |\ (x,y) ∈ r ∧ (x,y) ∉ s \}$$
The complement \(or negation\) of a relation $$r_{[A x B]}$$ is defined by means of the difference operator:
-* complement : If $$r$$ is defined as $$r_{A\times B}$$, then $$\overline{r}$$ is the set of all tuples in $$A\times B$$ \(the Cartesian product\) that are not contained in $$r$$. So $$\overline{r} = V_{[A\times B]} - r$$
+- complement : If $$r$$ is defined as $$r_{A\times B}$$, then $$\overline{r}$$ is the set of all tuples in $$A\times B$$ \(the Cartesian product\) that are not contained in $$r$$. So $$\overline{r} = V_{[A\times B]} - r$$
Note that the complement is defined in terms of $$A$$ and $$B$$. So, two relations with the identical population yet a different type may have different complements.
-#### How to type boolean operators in your script
+##### How to type boolean operators in your script
-[This page](../#notation-on-the-keyboard) shows how you can write these things in your Ampersand script.
+[This page](#notation-on-the-keyboard) shows how you can write these things in your Ampersand script.
-### Relational operators in set theory
+#### Relational operators in set theory
-#### Purpose of relational operators
+##### Purpose of relational operators
To say things such as "the name of the owner", we want to string together multiple relations \(viz. `name` and `owner`\). Relational operators allow us to make such statements.
-#### Converse
+##### 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:
@@ -292,59 +371,55 @@ $$
If $$r$$ has type $$[A\times B]$$, then $$r\smallsmile\$$ has type $$[B\times A]$$.
-#### Composition
+##### Composition
The composition operator is denoted by a semicolon ; between two terms. It is pronounced as 'composed with', in this case: $$r$$ composed with $$s$$.
The composition operation is defined as follows: Let $$r_{[A\times B]}$$ and $$s_{[B\times C]}$$ be two relations, with the target of r being the same as the source of s. Then the composition of $$r$$ and $$s$$, is a relation with signature $$(r;s)_{[A\times C]}\ =\ \{ (a, c) | ∃ b∈B\ .\ a\ r\ b ∧ b\ s\ c \}$$
+## Semantics in relational algebra
-
-# Semantics in relational algebra
-
-## Semantics of primitive terms in relational algebra
+### Semantics of primitive terms in relational algebra
This chapter discusses the [boolean operators](#boolean-operators-in-algebra) and the [relational operators](#relational-operators-in-algebra) in the following sections.
-
-### Boolean operators in algebra
+#### Boolean operators in algebra
The boolean operators of Ampersand behave as one would expect in any boolean algebra. Union ($$\cup$$) and intersection ($$\cap$$) are both idempotent, commutative, and associative operators. In Ampersand we use a binary difference operator over with the usual semantics: $$(r-s)\cup(r\cap s) = r$$. The (more customary) complement operator is a partial function, because Ampersand supports heterogeneous relation algebra.
-#### Union
+##### Union
The operator $$\cup$$ (union) satisfies the following axioms:
-1. (commutativity of $$\cup$$) $$r\cup s\ =\ s\cup r$$
-2. (associativity of $$\cup$$) $$r\cup (s\cup t)\ =\ (r\cup s)\cup t$$
-3. (idempotence of $$\cup$$) $$r\cup r\ =\ r$$
+1. (commutativity of $$\cup$$) $$r\cup s\ =\ s\cup r$$
+2. (associativity of $$\cup$$) $$r\cup (s\cup t)\ =\ (r\cup s)\cup t$$
+3. (idempotence of $$\cup$$) $$r\cup r\ =\ r$$
-#### Difference
+##### Difference
The difference $$r-s$$ is the smallest relation $$t$$ that satisfies $$r\ \subseteq\ s\cup t$$. Smallest means: If there is a $$t'$$ for which $$s\cup t'=r$$, this implies that $$t\cup t'=t'$$.
-#### Intersection
+##### Intersection
The intersection $$\cap$$ is defined as: $$r \cap s = r-(r-s)$$
-#### Complement
+##### Complement
The complement operator is defined as $$\overline{t} = V_{[A\times B]} - t$$. The type $$[A\times B]$$ comes from the term(s) in which $$t$$ is embedded. If that type does not exist or if it is ambiguous, Ampersand will refuse to compile with an appropriate error message.
-#### How to type boolean operators in your script
+##### How to type boolean operators in your script
-[This page](../#notation-on-the-keyboard) shows how you can write these things in your Ampersand script.
+[This page](#notation-on-the-keyboard) shows how you can write these things in your Ampersand script.
+#### Relational operators in algebra
-### Relational operators in algebra
-
-#### Purpose of relational operators
+##### Purpose of relational operators
To say things such as "the name of the owner", we want to string together multiple relations \(viz. `name` and `owner`\). Relational operators allow us to make such statements.
There are two relational operators: the converse \($$\smallsmile$$\) and the composition \(semicolon $$;$$ \). This page discusses the most important laws about these operators.
-#### Converse
+##### Converse
There are two things you should know about the converse operator. The first is that the converse of the converse gives you the relation itself, whatever that relation may be:
@@ -358,7 +433,7 @@ $$
r\smallsmile ; s\smallsmile\ =\ (s;r)\smallsmile
$$
-#### Composition
+##### Composition
The composition operator is denoted by a semicolon \(;\) between two terms. It is pronounced as 'composed with', in this case: $$r$$ composed with $$s$$.
@@ -376,19 +451,19 @@ $$
I_A;r\ =\ r\ \ \ \text{and}\ \ \ r;I_B\ =\ r
$$
-#### How to type relational operators in your script
+##### How to type relational operators in your script
-[This page](../#notation-on-the-keyboard) shows how you can write these things in your Ampersand script.
+[This page](#notation-on-the-keyboard) shows how you can write these things in your Ampersand script.
-## Semantics visualized
+### Semantics visualized
-For a visual presentation of the semantics of terms, we use [Venn-diagrams](https://en.wikipedia.org/wiki/Venn\_diagram).
+For a visual presentation of the semantics of terms, we use [Venn-diagrams](https://en.wikipedia.org/wiki/Venn_diagram).
-### Boolean operators visualized
+#### Boolean operators visualized
Consider two relations: `authorized[Account*Person]` and `beneficiary[Account*Person]`. The first relation tells which persons are authorized to which accounts. The diagram shows this as red dashed lines. The second relation tells which persons stand to benefit from which accounts.. It is depicted by dotted blue lines in the diagram.
-.png>)
+
This diagram gives an example population of the relations `authorized[Account*Person]` and `beneficiary[Account*Person]`. Bob is authorized for account DE9382991 and Ann is authorized for account RS746620. Carl stands to benefit from account NL19RABO03992844 and Ann stands to benefit from account RS746620. Formally, we say:
@@ -401,27 +476,25 @@ This diagram gives an example population of the relations `authorized[Account*Pe
By combining the relations `authorized` and `beneficiary`, we can derive the following true statements.
-| statement | natural language |
+| statement | natural language |
| ----------------------------------------------------- | -------------------------------------------------------------------------- |
| `"RS746620" (authorized/\beneficiary) "Ann"` | Ann is authorized for and stands to benefit from for account RS746620. |
| `"NL19RABO03992844" (authorized\/beneficiary) "Carl"` | Carl is authorized for or stands to benefit from account NL19RABO03992844. |
| `"RS746620" (authorized\/beneficiary) "Ann"` | Ann is authorized for or stands to benefit from account RS746620. |
| `"DE9382991" (authorized\/beneficiary) "Bob"` | Bob is authorized for or stands to benefit from account DE9382991. |
-
-
A different way to state the same is:
-| |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `authorized/\beneficiary = {("RS746620", "Ann")}` |
-| <p><code>authorized\/beneficiary =</code> </p><p> <code>{ ("NL19RABO03992844", "Carl")</code></p><p> <code>, ("RS746620", "Ann")</code></p><p> <code>, ("DE9382991", "Bob") }</code></p> |
+| |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `authorized/\beneficiary = {("RS746620", "Ann")}` |
+| <p><code>authorized\/beneficiary =</code> </p><p> <code>{ ("NL19RABO03992844", "Carl")</code></p><p> <code>, ("RS746620", "Ann")</code></p><p> <code>, ("DE9382991", "Bob") }</code></p> |
-### Relational operators visualized
+#### Relational operators visualized
Consider two relations: `traveler[Trip*Person]` and `dest[Trip*Destination]`. The first relation tells which persons have traveled on which trip. The diagram shows this as red dashed lines. The second relation links trips to destinations. It is depicted by dotted blue lines in the diagram.
-
+
Each pair (fact) in the diagram can be written as a fact in two ways, using the converse operator:
@@ -440,11 +513,11 @@ From the diagram, we assume that each pair represents a true statement (i.e. a f
| `"Peter" (traveler~;dest) "Rome"` | There is a trip that Peter has made, which has Rome as destination. | Peter has made a trip to Rome. |
| `"Peter" (traveler~;dest) "Paris"` | There is a trip that Peter has made, which has Paris as destination. | Peter has made a trip to Paris |
-### Residual operators visualized
+#### Residual operators visualized
Consider two relations: `traveler[Trip*Person]` and `dest[Trip*Destination]`. The first relation tells which persons have traveled on which trip. The diagram shows this as red dashed lines. The second relation links trips to destinations. It is depicted by dotted blue lines in the diagram.
-
+
From this diagram, we can tell which statements are true (i.e. facts). The statements are given both formally and in natural language. The elaborate version is a literate translation of the [semantics in logic](#residual-operators-in-logic). The ordinary version tells the same in a more human sounding manner.
@@ -452,11 +525,10 @@ From this diagram, we can tell which statements are true (i.e. facts). The state
| ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------ |
| `"Peter" (traveler~/dest~) "Rome"` | For each trip, if it has destination Rome, then it has been made by Peter. | Every trip to Rome has been made by Peter. |
-The following statements do _**NOT**_ follow from the population shown in the diagram:
+The following statements do _**NOT**_ follow from the population shown in the diagram:
| Formal statement | Elaborate natural language | Ordinary natural language |
| ----------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `"Peter" (traveler\dest) "Rome"` | For each trip, if Peter has made the trip then its destination is Rome. | Every trip that Peter made has Rome as destination. |
| `"Peter" (traveler\dest) "Paris"` | For each trip, if Peter has made the trip then its destination is Paris. | <p>Every trip that Peter made has</p><p>Paris as destination.</p> |
| `"Peter" (traveler~/dest~) "Paris"` | For each trip, if Paris is the destination then Peter has made that trip. | Every trip to Paris has been made by Peter. |
-
diff --git a/docs/reference-material/the-language-ampersand/README.md b/docs/reference-material/the-language-ampersand/README.md
deleted file mode 100644
index 483cc0da60..0000000000
--- a/docs/reference-material/the-language-ampersand/README.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-description: >-
- This chapter describes the full language Ampersand. Please use it as a
- reference rather than an introductory course.
----
-
-# The language Ampersand
-
-Watch [this clip](https://player.ou.nl/wowzaportlets/#!production/Cq0M1nv) to learn how we use the words atom, concept, and relation. Below is a list of other words with a specific meaning in Ampersand.
-
-| Word | Meaning | Example | Purpose |
-| ---- | ------- | ------- | ------- |
-| [Atom](atoms.md) | an indivisible item | `"Peter"` | to represent a thing |
-| [Concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement) | a name to categorize similar items | `Person` | |
-| Pair | two atoms: a source and a target atom | `("Ida",5)` | to state that two atoms are related |
-| [Relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) | a set of pairs that is identifyable in a context by its name and type | `r[A*B]` | to build true statements and store pairs persistently in an application |
-| [Rule](/ampersand/reference-material/syntax-of-ampersand#the-rule-statement) | a constraint, which is supposed to remain satisfied. | `r;s \|- t` | to provide meaning in a given context |
-| satisfy | A rule is satisfied (in a context) if the data (in that context) do not cause any violation of that rule. | | to calculate violations at runtime helps users do the right things |
-| [Pattern](syntactical-conventions/patterns.md) | a set of rules | <p><code>PATTERN</code></p><p> <code>...</code></p><p><code>ENDPATTERN</code></p> | to gather rules that belong together for reusing them in different contexts |
-| [Population](/ampersand/reference-material/syntax-of-ampersand#the-population-statement) | a set of pairs in a context | `POPULATION r[A*B] CONTAINS [ ("Ida",5), ("Bob",1) ]` | to represent the facts (i.e. true statements) in an information system |
-| [Context](context.md) | a population together with a set of rules that are satisfied by the population. | <p><code>CONTEXT</code></p><p> <code>...</code></p><p><code>ENDCONTEXT</code></p> | to maintain a consistent representation of a real life situation |
-| View | A set of pairs that can be shown to users in a particular formulation. | | to represent facts |
-| [Service](../The-language-Ampersand.md#services) | A structure meant for "the outside world" to communicate with the system and possibly change the population. | `INTERFACE Request FOR Customer` | to let "the outside world" communicate with the system in a given context and possibly change its population |
-| Multiplicity | A predefined property of a relation | `UNI`, `TOT`, `SUR`, `INJ` | to constrain a relation with predefined properties |
-| [Term](terms/README.md) | A combination of relations and operators that satisfy the Ampersand syntax | `r;s-t` | to express rules |
-| Operator | a symbol used in combining terms into other terms. | `-`, `~`, `\/`, `/\`, `-`, `;`, `\`, `/`, `\|-`, `=` | to express more complex rules. |
-| | | | |
-| [Specialization](/ampersand/reference-material/syntax-of-ampersand#the-classify-statement) | A rule that defines specialization between two (or more) concepts. | `CLASSIFY A ISA B` | To specify a building block for a classification hierarchy. |
-| Role | A name for a group of people | `ROLE Customer MAINTAINS paymentObligation` | to talk about users without having any users |
-
-Syntactic definitions are given where the underlying notions (e.g. rule, relation, pattern, etc.) are discussed. The metasyntax is singled out [on a separate page](how-to-read-syntax-statements.md). Because [terms](terms/README.md) are defined in relation algebra, their semantics are explained in various ways to suit the background of each individual reader. Terms are the only algebraically defined things.
-
-This section is organized by discussing each notion in isolation. Hyperlinks are added in the text to let the reader navigate on her own. The text is suitable for reference purposes, so there is no preferred order in reading.
diff --git a/docs/reference-material/the-language-ampersand/current-date.md b/docs/reference-material/the-language-ampersand/current-date.md
deleted file mode 100644
index 6c1daad512..0000000000
--- a/docs/reference-material/the-language-ampersand/current-date.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-description: How do you get the moment your script has started to run?
----
-
-# Current date
-
-The runtime system of Ampersand contains a function that produces the current date. Here is an example how to use it:
-
-```
-CONTEXT CurrentDate
-
- RELATION sessionToday[SESSION*Date] -- or whatever the DateTime concept is called
- REPRESENT Date TYPE DATE
- ROLE ExecEngine MAINTAINS "Initialize today's date"
- RULE "Initialize today's date": I[SESSION] |- sessionToday;sessionToday~
- VIOLATION (TXT "{EX} SetToday;sessionToday;SESSION;", SRC I, TXT ";Date")
-
-INTERFACE Overview : "_SESSION" cRud
-BOX [ date : sessionToday cRuD ]
-
-ENDCONTEXT
-```
-
-If you run this program, this is what you'll see
-
-
-
-### Explanation
-
-The rule "Initialize today's date" tells us that there must be a date for every session. When your session starts, there is a session atom: `_SESSION`. The relation `sessionToday` does not relate that session atom to a date, so the rule is violated. As a consequence, the ExecEngine triggers the violation and calls the function `SetToday`. That PHP-function creates the desired link in the relation `sessionToday`. That is then displayed in the user screen.
diff --git a/docs/reference-material/the-language-ampersand/how-to-read-syntax-statements.md b/docs/reference-material/the-language-ampersand/how-to-read-syntax-statements.md
deleted file mode 100644
index 393bf3ef07..0000000000
--- a/docs/reference-material/the-language-ampersand/how-to-read-syntax-statements.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# How to read syntax statements
-
-Sometimes, in describing the syntax, EBNF-like notation is used, with the following meaning:
-
-| Operator | meaning |
-| -------- | ----------------------------------- |
-| `<foo>?` | Zero or one occurrence of `<foo>` |
-| `<foo>+` | One or more occurrences of `<foo>` |
-| `<foo>*` | Zero or more occurrences of `<foo>` |
-
-To keep this chapter as readable as possible, we have chosen to omit some details that are irrelevant for practically all Ampersand modelers. In the very rare case that these technicalities are of interest, the reader could have a look in [the sourcecode of the parser](https://github.com/AmpersandTarski/Ampersand/blob/master/src/Ampersand/Input/ADL1/Parser.hs), where all EBNF statements are fully detailed in comments.
diff --git a/docs/reference-material/the-language-ampersand/language-support.md b/docs/reference-material/the-language-ampersand/language-support.md
deleted file mode 100644
index dddd7b0813..0000000000
--- a/docs/reference-material/the-language-ampersand/language-support.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Language support
-
-## Purpose
-
-To generate documentation, Ampersand is language aware.
-
-## Description
-
-Ampersand assigns a language to every text written as documentation, whether it is a `MEANING`, `PURPOSE` or other text except comment.
-
-Ampersand does not recognize any language, so you must tell which language is meant. To tell Ampersand what language you use, you can append a language directive to a context, a meaning, and to a purpose statement. Currently English and Dutch are supported.
-
-## Syntax
-
-A language directive has the following syntax
-
-```text
-IN <language>
-```
-
-Where `<language>` can be `ENGLISH` or `DUTCH`.
-
-## Semantics by example
-
-The first example is a context declaration in which the language `ENGLISH` is specified.
-
-```text
-CONTEXT Foo IN ENGLISH
-...
-ENDCONTEXT
-```
-
-This means that all natural language elements within this context are written in `ENGLISH`, unless specified otherwise.
-
-The second example is a `MEANING`, which can be used in a `RULE` statement and in a `RELATION` statement. This example uses a `MEANING` in `ENGLISH`:
-
-```text
-RELATION ptpic[Pattern*Image] [UNI]
-MEANING IN ENGLISH "Relation ptpic relates a pattern to the image of its conceptual diagram."
-```
-
-The language directive `IN ENGLISH` means that the meaning of the relation `ptpic[Pattern*Image]` is written in `ENGLISH`.
-
-The third example is a `PURPOSE` statement in which the language `DUTCH` is specified.
-
-```text
-PURPOSE CONCEPT Person IN DUTCH
-{+ Een persoon is een natuurlijke persoon of een rechtspersoon +}
-```
-
-This means that the contents of this purpose statement is written in `DUTCH`.
-
-## Additional information
-
-Ampersand assumes that whatever is written is written in the language denoted in the language directive. It doesn't check whether that language is actually used, because it cannot recognize languages.
-
-If a `CONTEXT` has no language directive, `IN ENGLISH` is used by default. If a `CONTEXT` has a language directive, that language will be the default language of all natural language items within that context.
-
-If a `PURPOSE` statement or a `MEANING` has no language directive, Ampersand assumes this to be the language of its context. So, the user needs to specify a language only if it is an exception to the default.
-
-Documentation generated by the Ampersand-compiler is written in a single language, which is specified when the compiler is called.
-
-Documentation generated by RAP4 is written in `DUTCH`. Natural language items written in any other language are ignored. This is [not a mistake](https://github.com/AmpersandTarski/Ampersand/issues/702), but a feature. RAP4 only "speaks Dutch" and ignores anything else.
-
diff --git a/docs/reference-material/the-language-ampersand/patterns.md b/docs/reference-material/the-language-ampersand/patterns.md
deleted file mode 100644
index 0f02b670eb..0000000000
--- a/docs/reference-material/the-language-ampersand/patterns.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Patterns
-
-## Purpose
-
-Patterns are meant to isolate discussions and make solutions reusable, as known from [design patterns](http://en.wikipedia.org/wiki/Design\_pattern).
-
-## Description
-
-A pattern is a set of rules that describes a theme or a general reusable solution to a commonly occurring problem.
-
-For instance, if specific concerns about security arise, you might want to discuss this with stakeholders in security. With them you can discuss which rules in particular constitute your solution. Divide your problem in smaller pieces and discuss each piece with just the right stakeholders. This allows you to go deeper by talking to the right people. It saves time as well by freeing others from having to participate. An even larger benefit arises if you reuse patterns that have been discussed and scrutinized before. The best thing comes once your stakeholders agree. By that time, your pattern represents their agreement formally in Ampersand, so you can use it in the larger context of the information system.
-
-## Example
-
-```
-PATTERN Security
-
-RELATION required[Subject*Destination]
-MEANING "A subject that you must have passed to qualify for the school trip to a destination"
-
-RELATION pass[Subject*Student]
-MEANING "The subjects that have been passed by specific students"
-
-RELATION attends[Student*Destination]
-
-PURPOSE RULE guardPrerequisites
-{+ This rule prevents students from registering for a trip
-without having passed the required courses. +}
-RULE guardPrerequisites : attends;required |- pass
-
-ENDPATTERN
-```
-
-## Syntax
-
-Every pattern has the following form:
-
-```
-PATTERN <pattern name>
- <pattern element>*
-ENDPATTERN
-```
-
-A pattern consists of any number of pattern elements in an arbitrary order. The following pattern elements are allowed:
-
-| | |
-| ------------------ | -------------------------------------------------------------------------------------------------------- |
-| `<rule>` | a statement that declares a [rule](/ampersand/reference-material/syntax-of-ampersand#the-rule-statement) |
-| `<classify>` | a statement that specifies generalization/specialization of [concepts](/ampersand/reference-material/syntax-of-ampersand#the-classify-statement) |
-| `<relation>` | a declaration of a relation, stating the existence of a [relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) within the context |
-| `<conceptDef>` | a description of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement), to document its meaning |
-| `<representation>` | a statement that defines the atomic type of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement) |
-| `<roleRule>` | a statement that makes a role responsible for satisfying a rule |
-| `<ident>` | a rule that defines an [identity](/ampersand/reference-material/syntax-of-ampersand#the-ident-statement) on a concept |
-| `<viewDef>` | a statement for presenting facts in a readable sentence |
-| `<purpose>` | a statement to describe the [purpose](/ampersand/reference-material/syntax-of-ampersand#the-purpose-statement) of a pattern or a pattern element |
-| `<population>` | a statement that sums up the initial [population](/ampersand/reference-material/syntax-of-ampersand#the-population-statement) of a relation |
-
-## Good practice
-
-A model can have as many patterns as you want.\
-It has no effect on how the code is processed.
-
-The service definition must be outside a pattern
-
-A pattern contains rules in an arbitrary order.\
-The context in which these rules are valid must contain the definition for each of the relations that are used in those rules.\
-It is good practice to declare all relations in the pattern itself.\
-That practice makes the pattern self-contained and therefore more suitable for reuse.
-
-Ampersand advocates **one theme in one pattern**. Stakeholders confine their discussion to one theme, and deliver the result in one pattern.
-
-## Restrictions
-
-In the current implementation of Ampersand, patterns are defined within a context. (This will change in a future version.) If you want to reuse patterns, you have to cut-and-paste them from one context to another. In the future, there will be a better mechanism for reusing patterns in different contexts.
diff --git a/docs/reference-material/the-language-ampersand/syntactical-conventions/README.md b/docs/reference-material/the-language-ampersand/syntactical-conventions/README.md
deleted file mode 100644
index 1e8ab343c3..0000000000
--- a/docs/reference-material/the-language-ampersand/syntactical-conventions/README.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Syntax
-
-## Purpose
-
-This page is meant as a reference for syntactical details and conventions, reserved words, etc.
-
-To keep this chapter as readable as possible, we have chosen to omit some details that are irrelevant for practically all &-modelers. In the very rare case that these technicalities are of interest, the reader could have a look in [the sourcecode of the parser](https://github.com/AmpersandTarski/Ampersand/blob/master/src/Ampersand/Input/ADL1/Parser.hs), where all EBNF statements are in comments.
-
-## Syntactical Conventions
-## Symbols
-
-Ampersand has _reserved words_, such as `RELATION`, `CONTEXT`, `CONTAINS`. All reserved words are written in capital letters. They are introduced on the fly. You will find an exhaustive list of reserved words [here](## List of reserved words).
-
-Untyped atoms are written between double quotes, e.g. `"Peter"` or `"KD-686-D"`. If you want to introduce a double quote inside an atom, escape it with a backslash, e.g. `"the symbol \" is called double quote"`.
-Numeric atoms always start with a digit, e.g. `4711` or `75.88E3`. The boolean atoms are `TRUE` and `FALSE`. Dates and timestamps follow the Excel-syntax, e.g. ??? The atom `_SESSION` indicates the current user session, and is an instance of concept `SESSION`. It is used in services.
-
-Brackets must always match. For terms, we use round brackets `(` and `)`. For populations and services we use square brackets `[` and `]`.
-
-Constructs that contain Ampersand statements are contexts and patterns. They always come in pairs: `PATTERN` and `ENDPATTERN`, and `CONTEXT` and `ENDCONTEXT`.
-
-White space characters \(spaces, tabs, CRLF\) are meaningless. You can use them freely to layout your script in a way that helps you to recognize its structure.
-
-A comment on a single line starts with `--`. Everything after a `--` symbol is ignored until the line ends. Multiline comments are wrapped between comment brackets `{-` and `-}`. Multiline comments may be nested.
-
-Identifiers always start with a letter. Concepts start with a capital letter, as in `Person`, `Case`, `A`, and `Order`. Relation names start with a lower case letter, as in `contains`, `attr`, `sessionLogin`, or `r`.
-
-## terms
-
-terms are combined with operators. Binary operators may require brackets to avoid ambiguity. To save writing unneccessary brackets, some precedence rules are in place.
-
-| operator category | precedence | operators |
-| :--- | :--- | :--- |
-| logic | 1 \(weakest\) | \|- \(subset\), `=` \(equal\) |
-| binary boolean | 2 | `\/` \(union\), `/\` \(intersect\), `-` \(difference\) |
-| binary relational | 3 | `;` \(composition\), `!` \(relational addition\), `\` \(right residual\), `/` \(left residual\), `<>` \(diamond operator\) |
-| unary prefix, unary postfix | 4 \(strongest\) | `-` \(complement\), `~` \(converse\) |
-
-Within an operator category, you must place brackets to disambiguate. E.g. `r/\s\/t` is not allowed. You have to write either `(r/\s)\/t` or `r/\(s\/t)`. Across categories, you may omit brackets because a higher precedence binds stronger. So `r;s\/t` means `(r;s)\/t`. \(Note that `(r;s)\/t` and `r;(s\/t)` have different meanings\). Associative operators \(`\/`, `/\`, `;`\) need not be disambiguated with brackets. So `r\/s\/t` and `(r\/s)\/t` and `r\/(s\/t)` all mean exactly the same.
-
-## List of reserved words
-
-Keywords in Ampersand are always written in CAPITALS.
-
-* Keywords for the main structure of the code
- * [`CONTEXT`](./)
- * `ENDCONTEXT`
- * [`IN`](language-support.md)
- * `ENGLISH`
- * `DUTCH`
- * [`INCLUDE`](/ampersand/reference-material/syntax-of-ampersand#the-include-statement)
- * `META`
- * `THEMES`
- * [`PATTERN`](patterns.md)
- * `ENDPATTERN`
- * [`CONCEPT`](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement)
-* Keywords for [relations](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement)
- * [`RELATION`](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement)
- * `PRAGMA`
- * `UNI`
- * `INJ`
- * `SUR`
- * `TOT`
- * `SYM`
- * `ASY`
- * `TRN`
- * `RFX`
- * `IRF`
- * `PROP`
- * [`POPULATION`](/ampersand/reference-material/syntax-of-ampersand#the-population-statement)
- * `CONTAINS`
-* Keywords for [rules](/ampersand/reference-material/syntax-of-ampersand#the-rule-statement)
- * `RULE`
- * `MESSAGE`
- * `VIOLATION`
- * `TXT`
- * `SRC`
- * `TGT`
- * `I`
- * `V`
- * `ONE`
- * `ROLE`
- * `MAINTAINS`
-* Keywords for documentation
- * [`PURPOSE`](/ampersand/reference-material/syntax-of-ampersand#the-purpose-statement)
- * [`MEANING`](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement)
- * `REF`
- * `REST`
- * `HTML`
- * `LATEX`
- * `MARKDOWN`
-* Keywords for [services](../../The-language-Ampersand.md#syntax-of-interface-statements)
- * `INTERFACE`
- * `FOR`
- * `LINKTO`
- * `BOX`
-* Keywords for identities
- * [`IDENT`](/ampersand/reference-material/syntax-of-ampersand#the-ident-statement)
-* Keywords for views
- * `VIEW`
- * `ENDVIEW`
- * `DEFAULT`
- * `TEMPLATE`
- * `HTML`
-* Keywords for generalisations:
- * `CLASSIFY`
- * `ISA`
- * `IS`
-* Keywords for TType:
- * `REPRESENT`
- * `TYPE`
- * `ALPHANUMERIC`
- * `BIGALPHANUMERIC`
- * `HUGEALPHANUMERIC`
- * `PASSWORD`
- * `BINARY`
- * `BIGBINARY`
- * `HUGEBINARY`
- * `DATE`
- * `DATETIME`
- * `BOOLEAN`
- * `INTEGER`
- * `FLOAT`
- * `AUTOINCREMENT`
-* Reserved words for values of atoms:
- * `TRUE`
- * `FALSE` --for booleans
- * `_SESSION`
-* Reserved words for concepts
- * `ONE`
- * `SESSION`
-* Experimental keywords:
- * `SERVICE`
- * `EDITS`
-* Deprecated keywords:
- * `SPEC`
- * `KEY`
- * `PROCESS`
- * `ENDPROCESS`
-
diff --git a/docs/reference-material/the-language-ampersand/syntactical-conventions/language-support.md b/docs/reference-material/the-language-ampersand/syntactical-conventions/language-support.md
deleted file mode 100644
index dddd7b0813..0000000000
--- a/docs/reference-material/the-language-ampersand/syntactical-conventions/language-support.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Language support
-
-## Purpose
-
-To generate documentation, Ampersand is language aware.
-
-## Description
-
-Ampersand assigns a language to every text written as documentation, whether it is a `MEANING`, `PURPOSE` or other text except comment.
-
-Ampersand does not recognize any language, so you must tell which language is meant. To tell Ampersand what language you use, you can append a language directive to a context, a meaning, and to a purpose statement. Currently English and Dutch are supported.
-
-## Syntax
-
-A language directive has the following syntax
-
-```text
-IN <language>
-```
-
-Where `<language>` can be `ENGLISH` or `DUTCH`.
-
-## Semantics by example
-
-The first example is a context declaration in which the language `ENGLISH` is specified.
-
-```text
-CONTEXT Foo IN ENGLISH
-...
-ENDCONTEXT
-```
-
-This means that all natural language elements within this context are written in `ENGLISH`, unless specified otherwise.
-
-The second example is a `MEANING`, which can be used in a `RULE` statement and in a `RELATION` statement. This example uses a `MEANING` in `ENGLISH`:
-
-```text
-RELATION ptpic[Pattern*Image] [UNI]
-MEANING IN ENGLISH "Relation ptpic relates a pattern to the image of its conceptual diagram."
-```
-
-The language directive `IN ENGLISH` means that the meaning of the relation `ptpic[Pattern*Image]` is written in `ENGLISH`.
-
-The third example is a `PURPOSE` statement in which the language `DUTCH` is specified.
-
-```text
-PURPOSE CONCEPT Person IN DUTCH
-{+ Een persoon is een natuurlijke persoon of een rechtspersoon +}
-```
-
-This means that the contents of this purpose statement is written in `DUTCH`.
-
-## Additional information
-
-Ampersand assumes that whatever is written is written in the language denoted in the language directive. It doesn't check whether that language is actually used, because it cannot recognize languages.
-
-If a `CONTEXT` has no language directive, `IN ENGLISH` is used by default. If a `CONTEXT` has a language directive, that language will be the default language of all natural language items within that context.
-
-If a `PURPOSE` statement or a `MEANING` has no language directive, Ampersand assumes this to be the language of its context. So, the user needs to specify a language only if it is an exception to the default.
-
-Documentation generated by the Ampersand-compiler is written in a single language, which is specified when the compiler is called.
-
-Documentation generated by RAP4 is written in `DUTCH`. Natural language items written in any other language are ignored. This is [not a mistake](https://github.com/AmpersandTarski/Ampersand/issues/702), but a feature. RAP4 only "speaks Dutch" and ignores anything else.
-
diff --git a/docs/reference-material/the-language-ampersand/syntactical-conventions/patterns.md b/docs/reference-material/the-language-ampersand/syntactical-conventions/patterns.md
deleted file mode 100644
index 7aab8306cb..0000000000
--- a/docs/reference-material/the-language-ampersand/syntactical-conventions/patterns.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# Patterns
-
-## Purpose
-
-Patterns are meant to isolate discussions and make solutions reusable, as known from [design patterns](http://en.wikipedia.org/wiki/Design_pattern).
-
-## Description
-
-A pattern is a set of [rules](/ampersand/reference-material/syntax-of-ampersand#the-rule-statement) that describes a theme or a general reusable solution to a commonly occurring problem.
-
-For instance, if specific concerns about security arise, you might want to discuss this with stakeholders in security. With them you can discuss which rules in particular constitute your solution. Divide your problem in smaller pieces and discuss each piece with just the right stakeholders. This allows you to go deeper by talking to the right people. It saves time as well by freeing others from having to participate. An even larger benefit arises if you reuse patterns that have been discussed and scrutinized before. The best thing comes once your stakeholders agree. By that time, your pattern represents their agreement formally in Ampersand, so you can use it in the larger context of the information system.
-
-## Example
-
-```text
-PATTERN Security
-
-RELATION required[Subject*Destination]
-MEANING "A subject that you must have passed to qualify for the school trip to a destination"
-
-RELATION pass[Subject*Student]
-MEANING "The subjects that have been passed by specific students"
-
-RELATION attends[Student*Destination]
-
-PURPOSE RULE guardPrerequisites
-{+ This rule prevents students from registering for a trip
-without having passed the required courses. +}
-RULE guardPrerequisites : attends;required |- pass
-
-ENDPATTERN
-```
-
-## Syntax
-
-Every pattern has the following form:
-
-```text
-PATTERN <pattern name>
- <pattern element>*
-ENDPATTERN
-```
-
-A pattern consists of any number of pattern elements in an arbitrary order. The following pattern elements are allowed:
-
-| | |
-| :--- | :--- |
-| `<rule>` | a statement that declares a [rule](/ampersand/reference-material/syntax-of-ampersand#the-rule-statement) |
-| `<classify>` | a statement that specifies generalization/specialization of [concepts](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement) |
-| `<relation>` | a declaration of a relation, stating the existence of a [relation](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) within the context |
-| `<conceptDef>` | a description of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement), to document its meaning |
-| `<representation>` | a statement that defines the atomic type of a [concept](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement) |
-| `<roleRule>` | a statement that makes a role responsible for satisfying a rule |
-| `<ident>` | a rule that defines an identity on a concept |
-| `<viewDef>` | a statement for presenting facts in a readable sentence |
-| `<purpose>` | a statement to describe the purpose of a pattern or a pattern element |
-| `<population>` | a statement that sums up the initial population of a relation |
-
-## Good practice
-
-A model can have as many patterns as you want.
-It has no effect on how the code is processed.
-
-The service definition must be outside a pattern
-
-A pattern contains rules in an arbitrary order.
-The context in which these rules are valid must contain the definition for each of the relations that are used in those rules.
-It is good practice to declare all relations in the pattern itself.
-That practice makes the pattern self-contained and therefore more suitable for reuse.
-
-Ampersand advocates **one theme in one pattern**. Stakeholders confine their discussion to one theme, and deliver the result in one pattern.
-
-## Restrictions
-
-In the current implementation of Ampersand, patterns are defined within a context. \(This will change in a future version.\) If you want to reuse patterns, you have to cut-and-paste them from one context to another. In the future, there will be a better mechanism for reusing patterns in different contexts.
-
diff --git a/docs/reference-material/the-language-ampersand/terms/README.md b/docs/reference-material/the-language-ampersand/terms/README.md
deleted file mode 100644
index ab81968d3a..0000000000
--- a/docs/reference-material/the-language-ampersand/terms/README.md
+++ /dev/null
@@ -1,85 +0,0 @@
----
-description: >-
- This page describes the notion of term. Its subpages provide several
- interpretations of terms, all of which are valid so you can use each
- interpretation at your own discretion.
----
-
-# Terms
-
-## Purpose
-
-The purpose of a term is to compute pairs that constitute a relation. We use operators to assemble terms from smaller terms, to express in formal language precisely what is meant in the natural language of the business. The smallest term is a single relation.
-
-We noticed that our readers have different backgrounds. They have different preferences about the way we explain the operators in Ampersand. Some prefer an explanation in logic, others in algebra, and still others in set theory. So we decided to explain the operators in many different ways simultaneously, hoping that one of them suits your preference.
-
-## Description
-
-A term is a combination of operators and relations. Its meaning is a set of pairs, which is in fact a newly created relation. The word "expression" may be used as a synonym for "term" in the context of Ampersand.
-
-## Examples
-
-`owner`
-
-`r;s~`
-
-`I /\ goalkeeper;goalkeeper~`
-
-`destination;"Algarve" |- spoken;"Portugese"`
-
-## Syntax
-
-Every term is built out of relations, which are combined by operators. An term has one of the following 8 syntactic structures
-
-```
-<Term> <BinaryOperator> <Term>
-<UnaryOpPre> <Term>
-<Term> <UnaryOpPost>
-<RelationRef> <type>?
-I <type>?
-V <type>?
-<atom>
-( <Term> )
-```
-
-## `Operators`
-
-The operators come in families. We advise novices to study only the rule operators, boolean operators and relational operators. There is a wealth of things you can express with just these operators. The residual operators seem harder to learn and the Kleene operators are not fully implemented yet. You can click the hyperlink to navigate to the semantics of each family.
-
-| Family | binary operators | binding power | unary operators | binding power |
-| -------------------------------------------------------- | ---------------------------------: | ------------- | --------------------: | ------------- |
-| rules | $$=$$ and $$\subseteq\$$ | 1 (weakest) | | |
-| [boolean](semantics.md#boolean-operators-in-logic) | $$\cup$$, $$\cap$$, and $$-$$ | 2 | $$\overline{\strut}$$ | prefix |
-| [relational](semantics.md#relational-operators-in-logic) | $$;$$, $$\times$$, and $$\dagger$$ | 4 | $$\smallsmile$$ | postfix |
-| [residual](semantics.md#residual-operators-in-logic) | $$\backslash$$, $$/$$, and $$♢$$ | 3 | | |
-| Kleene | | | $$∗$$ and $$+$$ | postfix |
-
-## Brackets
-
-Operators with different binding power may be used in the same term without brackets, because the binding power tells how it is interpreted. For example, $$r\cap s;t$$ means $$r\cap(s;t)$$ because $$;$$ has a higher binding power than $$\cap$$.
-
-Operators with the same binding power must be used unambiguously. For example: $$r\cap(s-t)$$ means something different than $$(r\cap s)-t$$. In such cases Ampersand insists on the use of brackets, so readers without knowledge of the binding powers of the operators can read a term unambiguously.
-
-Repeated uses of an associative operator does not require brackets. So $$r\cap s \cap t$$ is allowed because $$\cap$$ is associative.
-
-## Notation on the keyboard
-
-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$$ | deprecated | |
-| reflexive transitive closure | `*` | $$∗$$ | in code: not implemented; in math: Postfix | |
-| transitive closure | `+` | $$+$$ | in code: not implemented; in math: Postfix | |
diff --git a/docs/reference-material/the-language-ampersand/the-preprocessor.md b/docs/reference-material/the-preprocessor.md
similarity index 100%
rename from docs/reference-material/the-language-ampersand/the-preprocessor.md
rename to docs/reference-material/the-preprocessor.md
diff --git a/docs/reference-material/the-language-ampersand/truth.md b/docs/reference-material/truth.md
similarity index 59%
rename from docs/reference-material/the-language-ampersand/truth.md
rename to docs/reference-material/truth.md
index 47332a069d..f92c3f0e4d 100644
--- a/docs/reference-material/the-language-ampersand/truth.md
+++ b/docs/reference-material/truth.md
@@ -8,12 +8,12 @@ description: >-
Let us introduce some language to talk about truth. Consider a fact "Joe Smith lives in New York." from an Ampersand perspective. In Ampersand, we can analyse this as follows:
-* Let `Person` and `City` be [_**concepts**_](/ampersand/reference-material/syntax-of-ampersand#the-concept-statement)_\*\*\*\*_
-* Let `"Joe Smith"` be an [_**atom**_](atoms.md) of the concept `Person` and `"New York"` an atom of the concept `City`.
-* Let us use the [_**relation**_](/ampersand/reference-material/syntax-of-ampersand#the-relation-statement) `livesIn[Person*City]` to contain our fact.
-* `livesIn` is the _**relation name**_ and `[Person*City]` is the _**signature**_ of this relation.
-* `Person` is the _**source**_ of this relation and `City` is the _**target**_.
-* If the pair `("Joe Smith","New York")` is an element of this relation, Ampersand considers the statement `"Joe Smith" livesIn "New York"` to be true. So all pairs in a relation represent _**facts**_, i.e. true statements.
+- Let `Person` and `City` be [_**concepts**_](./syntax-of-ampersand#the-concept-statement)_\*\*\*\*_
+- Let `"Joe Smith"` be an [_**atom**_](atoms.md) of the concept `Person` and `"New York"` an atom of the concept `City`.
+- Let us use the [_**relation**_](./syntax-of-ampersand#the-relation-statement) `livesIn[Person*City]` to contain our fact.
+- `livesIn` is the _**relation name**_ and `[Person*City]` is the _**signature**_ of this relation.
+- `Person` is the _**source**_ of this relation and `City` is the _**target**_.
+- If the pair `("Joe Smith","New York")` is an element of this relation, Ampersand considers the statement `"Joe Smith" livesIn "New York"` to be true. So all pairs in a relation represent _**facts**_, i.e. true statements.
## Language that makes sense to the business
@@ -21,4 +21,4 @@ Ampersand takes a pragmatic stance on truth: You model only things that make sen
## Truth in context
-Truth always has context. If we say "Jack was married to Jackie", this statement is true in a [context](context.md) where "Jack" refers to the 35th president of the United States, John F. Kennedy. However, this statement is not true in a context where there is no Jack. And in a context where marriage doesn't exist, this statement makes no sense.
+Truth always has context. If we say "Jack was married to Jackie", this statement is true in a [context](./syntax-of-ampersand#the-context-statement) where "Jack" refers to the 35th president of the United States, John F. Kennedy. However, this statement is not true in a context where there is no Jack. And in a context where marriage doesn't exist, this statement makes no sense.
diff --git a/docs/research.md b/docs/research.md
index 6da4a8e215..60d1f7a024 100644
--- a/docs/research.md
+++ b/docs/research.md
@@ -60,7 +60,7 @@ Stef Joosten, [Rekenen met Taal](https://www.researchgate.net/publication/236340
<!-- The main page in AmpersandTarski.github.io refers to this header, so please don't change it frivolously. -->
The application [RAP](https://rap.cs.ou.nl) was built as an educational tool, and developed further into a tool in which anyone can build and run their own prototypes.
-The project has contributed to the development of applications in relation algebra, which has lead to numerous publications in the [International Conference of Relation Algebraic Methods in Computer Science](http://www.ramics-conference.org).
+The project has contributed to the development of applications in relation algebra, which has lead to numerous publications in the [International Conference of Relation Algebraic Methods in Computer Science](https://ramics20.lis-lab.fr/).
Numerous students at the Open Universiteit have graduated in the context of Ampersand.
diff --git a/docs/reusing-available-modules.md b/docs/reusing-available-modules.md
index 19e1579ea6..c286be5bd6 100644
--- a/docs/reusing-available-modules.md
+++ b/docs/reusing-available-modules.md
@@ -26,11 +26,11 @@ The current set of modules include:
## Security
-Even though Ampersand was designed for prototyping, we are taking applications such as RAP2 and RAP3 to production. As the development of Ampersand is going in the direction of production software, we must be prepared for questions. Currently, I can hardly answer any questions about security. This page is for the purpose to discuss security questions, such that we are at least on the same ground wrt security. If any changes to Ampersand emerge from that, we should create separate issues for them. Here is a list of questions.
+Even though Ampersand was designed for prototyping, we are taking applications such as RAP4 and Semantic Treehouse to production. As the development of Ampersand is going in the direction of production software, we must be prepared for questions. Currently, I can hardly answer any questions about security. This page is for the purpose to discuss security questions, such that we are at least on the same ground wrt security. If any changes to Ampersand emerge from that, we should create separate issues for them. Here is a list of questions.
### Access control
-How is access control arranged in an Ampersand application? _Answer_: This can be arranged by using the SIAM modules, which provide role-based access controls, login possibilities and password security.
+How is access control arranged in an Ampersand application? _Answer_: An Ampersand programmer can arrange this by using the SIAM modules, which provide role-based access controls, login possibilities and password security. Yet, we advise to let the deployment platform (e.g.\ Kubernetes) take care of access control, keeping the Ampersand code clean and independent of any access control mechanism.
### Logging
@@ -38,11 +38,11 @@ How does an Ampersand application log critical activities, and transactions that
### Encryption of data
-How does Ampersand encrypt data? _Answer_: It doesn't. All data is stored as-is in the database.
+How does Ampersand encrypt data? _Answer_: It doesn't. All data is stored as-is in the database. We advise to put the database in a separate container, which is not connected to the outside world, to minimize the chance of illegal access to the database.
### Access control for specific purposes
-How does an Ampersand application control access for purposes that are known only to the Ampersand application designer? _Answer_: The designer can use the ROLE mechanism to provide different services to different roles. Also, the designer can model these purposes in the Ampersand-script and take it from there. In the latter case, every possible access control scheme can be built.
+How does an Ampersand application control access for purposes that are known only to the Ampersand application designer? _Answer_: The designer can use the ROLE mechanism to provide different interfaces to different roles. Also, the designer can model these purposes in the Ampersand-script and take it from there. In the latter case, every possible access control scheme can be built.
### Injection
@@ -50,7 +50,10 @@ How does an Ampersand application prevent injection flaws, by which hostile data
### Broken Authentication and Session Management
-How can we know that application functions related to authentication and session management are implemented correctly? Is there a chance that attackers can compromise passwords, keys, or session tokens, or exploit other implementation flaws to assume other users’ identities? _Answer_: The authentication and session management are described in the SIAM-module in Ampersand itself. So we have a mathematical handle on this, which gives more certainty than hand-crafted code. We have no security assessment on the SIAM-code for this risk. Of course, when this is embedded in for example a SSO-service, we would have to look for specific risks incurred by that. At the moment I have no idea how good or bad an Ampersand-application will do on this risk.
+How can we know that application functions related to authentication and session management are implemented correctly? Is there a chance that attackers can compromise passwords, keys, or session tokens, or exploit other implementation flaws to assume other users’ identities? _Answer_:
+ * In the browser, Ampersand runs a PHP session strict mode. This prevents a user defined session ID that is never generated
+ * The authentication and session management are described in the SIAM-module in Ampersand itself. So we have a mathematical handle on this, which gives more certainty than hand-crafted code. We have no security assessment on the SIAM-code for this risk. Of course, when this is embedded in for example a SSO-service, we would have to look for specific risks incurred by that.
+ * At the moment I have no idea how good or bad an Ampersand-application will do on this risk.
### Cross-Site Scripting
@@ -67,6 +70,7 @@ How do we know that a secure configuration is defined and deployed, and that sec
### Sensitive Data Exposure
Does Ampersand have extra protection for sensitive data, such as credit cards, tax IDs, and authentication credentials? _Answer_: No.
+We have a policy not to publish secrets in the Ampersand repository. GitHub (scans for secrets)[https://github.com/AmpersandTarski/Ampersand/security/secret-scanning], so we get notified of any violations of this policy.
### Missing Function Level Access Control
diff --git a/docs/sidebar.js b/docs/sidebar.js
index 4acd29c549..24f59cfca1 100644
--- a/docs/sidebar.js
+++ b/docs/sidebar.js
@@ -1,11 +1,4 @@
module.exports = {
- oldTableOfContent: [
- {
- type: 'doc',
- id: 'ampersand/toc'
- },
-
- ],
ampersandLandingpagesSidebar: [
{
label: 'Interested visitor',
@@ -33,39 +26,149 @@ module.exports = {
id: 'ampersand/landingpage/contributor'
}
],
+ ampersandReferenceSidebar: [
+ // This is for all documentation from the Ampersand repo that should go in the `Reference material` part of the menu.
+ {
+ label: 'Dictionary',
+ type: 'doc',
+ id: 'ampersand/reference-material/dictionary'
+ },
+ {
+ label: 'Meta syntax',
+ type: 'doc',
+ id: 'ampersand/reference-material/how-to-read-syntax-statements'
+ },
+ {
+ label: 'Syntax of Ampersand',
+ type: 'doc',
+ id: 'ampersand/reference-material/syntax-of-ampersand'
+ },
+ {
+ label: 'Atoms',
+ type: 'doc',
+ id: 'ampersand/reference-material/atoms'
+ },
+ {
+ label: 'Contexts',
+ type: 'doc',
+ id: 'ampersand/reference-material/context'
+ },
+ {
+ label: 'Terms',
+ type: 'doc',
+ id: 'ampersand/reference-material/terms'
+ },
+ {
+ label: 'Interfaces',
+ type: 'doc',
+ id: 'ampersand/reference-material/interfaces'
+ },
+ {
+ label: 'Architecture of generated systems',
+ type: 'doc',
+ id: 'ampersand/reference-material/architecture-of-an-ampersand-application'
+ },
+ {
+ label: 'Preprocessor',
+ type: 'doc',
+ id: 'ampersand/reference-material/the-preprocessor'
+ },
+ {
+ label: 'Importing data from Excel',
+ type: 'doc',
+ id: 'ampersand/the-excel-importer'
+ },
+ {
+ label: 'Command line functions',
+ type: 'doc',
+ id: 'ampersand/the-command-line-tool'
+ },
+ ],
ampersandGuideSidebar: [
// This is for all documentation from the Ampersand repo that should go in the `Guides` part of the menu.
{
+ label: 'Frequently asked questions',
type: 'doc',
- id: 'ampersand/reference-material/frequently-asked-questions'
+ id: 'ampersand/guides/frequently-asked-questions'
+ },
+ {
+ label: 'Installing Ampersand',
+ type: 'doc',
+ id: 'ampersand/guides/installing-ampersand'
+ },
+ {
+ label: 'Deploying your prototype',
+ type: 'doc',
+ id: 'ampersand/guides/deploying-your-prototype'
+ },
+ {
+ label: 'Manual installation',
+ type: 'doc',
+ id: 'ampersand/guides/best-practices'
},
- ],
- ampersandReferenceSidebar: [
- // This is for all documentation from the Ampersand repo that should go in the `Reference material` part of the menu.
{
+ label: 'Contributor\'s guide',
type: 'category',
- label: 'Language Reference',
items: [
- 'ampersand/reference-material/the-language-ampersand/README',
- 'ampersand/reference-material/the-language-ampersand/atoms',
- 'ampersand/reference-material/the-language-ampersand/best-practices',
- 'ampersand/reference-material/the-language-ampersand/context',
- 'ampersand/reference-material/the-language-ampersand/current-date',
- 'ampersand/reference-material/the-language-ampersand/design-considerations',
- 'ampersand/reference-material/the-language-ampersand/how-to-read-syntax-statements',
- 'ampersand/reference-material/the-language-ampersand/language-support',
- 'ampersand/reference-material/the-language-ampersand/patterns',
- 'ampersand/reference-material/the-language-ampersand/syntactical-conventions/README',
- 'ampersand/reference-material/the-language-ampersand/syntactical-conventions/language-support',
- 'ampersand/reference-material/the-language-ampersand/syntactical-conventions/patterns',
- 'ampersand/reference-material/the-language-ampersand/terms/README',
- 'ampersand/reference-material/the-language-ampersand/terms/semantics',
- 'ampersand/reference-material/the-language-ampersand/the-preprocessor',
- 'ampersand/reference-material/the-language-ampersand/truth',
- ]
+ 'ampersand/guides/onboarding',
+ 'ampersand/the-tools-we-use/README',
+ 'ampersand/the-tools-we-use/SUMMARY',
+ 'ampersand/the-tools-we-use/ampersand-language-support',
+ 'ampersand/the-tools-we-use/authentication-and-access-management-with-oauth',
+ 'ampersand/the-tools-we-use/automation-of-releasing-ci-cd/README',
+ 'ampersand/the-tools-we-use/automation-of-releasing-ci-cd/github-packages',
+ 'ampersand/the-tools-we-use/building/README',
+ 'ampersand/the-tools-we-use/building/automated-builds',
+ 'ampersand/the-tools-we-use/building/building-an-ampersand-compiler-as-docker-image',
+ 'ampersand/the-tools-we-use/building/haskell',
+ 'ampersand/the-tools-we-use/building/testing-with-docker-on-your-own-laptop',
+ 'ampersand/the-tools-we-use/deploying-rap3-with-azure',
+ 'ampersand/the-tools-we-use/deploying-rap3-with-azure/deploying-rap3-with-azure-on-windows-server',
+ 'ampersand/the-tools-we-use/deploying-with-kubernetes',
+ 'ampersand/the-tools-we-use/functionality-of-rap3/README',
+ 'ampersand/the-tools-we-use/git',
+ 'ampersand/the-tools-we-use/gitbook/README',
+ 'ampersand/the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation',
+ 'ampersand/the-tools-we-use/gitbook/getting-started-with-gitbook',
+ 'ampersand/the-tools-we-use/group-1/development-using-vs-code',
+ 'ampersand/the-tools-we-use/installation-of-rap/README',
+ 'ampersand/the-tools-we-use/installation-of-rap/deploying-ounl-rap3',
+ 'ampersand/the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu',
+ 'ampersand/the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop',
+ 'ampersand/the-tools-we-use/installation-of-rap/deployment-configuration',
+ 'ampersand/the-tools-we-use/installation-of-rap/details',
+ 'ampersand/the-tools-we-use/installation-of-rap/making-docker-images',
+ 'ampersand/the-tools-we-use/installation-of-rap/redeploying-rap3',
+ 'ampersand/the-tools-we-use/klad',
+ 'ampersand/the-tools-we-use/making-images',
+ 'ampersand/the-tools-we-use/prototype-framework',
+ 'ampersand/the-tools-we-use/rap3-student',
+ 'ampersand/the-tools-we-use/rap3-tutor',
+ 'ampersand/the-tools-we-use/releasing-ampersand-and-workflow-details',
+ 'ampersand/the-tools-we-use/tools-used-in-the-ampersand-project'
+ ]
+ },
+ {
+ label: 'Best practices for Ampersand modellers',
+ type: 'doc',
+ id: 'ampersand/guides/best-practices'
+ },
+ {
+ label: 'Configuring your application',
+ type: 'doc',
+ id: 'ampersand/reference-material/configuring-your-application'
},
],
ampersandTheorySidebar: [
+ {
+ label: 'Design considerations',
+ type: 'doc',
+ id: 'ampersand/reference-material/design-considerations'
+ },
+ {
+ type: 'doc',
+ id: 'ampersand/reference-material/truth'
+ },
{
type: 'doc',
id: 'ampersand/conceptual/theory'
@@ -83,15 +186,6 @@ module.exports = {
id: 'ampersand/future-plans'
},
- ],
- ampersandGuideElems: [
- 'ampersand/configuring-your-application',
- 'ampersand/the-excel-importer',
- 'ampersand/the-command-line-tool',
- ],
- ampersandReferenceElems: [
- 'ampersand/empty'
-
],
ampersandMainSidebar: [
@@ -104,50 +198,17 @@ module.exports = {
].concat((
[
- {
- label: 'Reference',
- type: 'category',
- items: [
- 'ampersand/reference-material/the-language-ampersand/README',
- 'ampersand/reference-material/the-language-ampersand/atoms',
- 'ampersand/reference-material/the-language-ampersand/best-practices',
- 'ampersand/reference-material/the-language-ampersand/context',
- 'ampersand/reference-material/the-language-ampersand/current-date',
- 'ampersand/reference-material/the-language-ampersand/design-considerations',
- 'ampersand/reference-material/the-language-ampersand/how-to-read-syntax-statements',
- 'ampersand/reference-material/the-language-ampersand/language-support',
- 'ampersand/reference-material/the-language-ampersand/patterns',
- 'ampersand/reference-material/the-language-ampersand/syntactical-conventions/README',
- 'ampersand/reference-material/the-language-ampersand/syntactical-conventions/language-support',
- 'ampersand/reference-material/the-language-ampersand/syntactical-conventions/patterns',
- 'ampersand/reference-material/the-language-ampersand/terms/README',
- 'ampersand/reference-material/the-language-ampersand/terms/semantics',
- 'ampersand/reference-material/the-language-ampersand/the-preprocessor',
- 'ampersand/reference-material/the-language-ampersand/truth',
- ]
- },
-
{
label: 'More documents',
type: 'category',
items: [
'ampersand/conceptual/why-declarative',
- 'ampersand/architecture-of-an-ampersand-application/README',
- 'ampersand/architecture-of-an-ampersand-application/backend-framework',
- 'ampersand/architecture-of-an-ampersand-application/extensions/README',
- 'ampersand/architecture-of-an-ampersand-application/extensions/the-execengine',
- 'ampersand/architecture-of-an-ampersand-application/hooks',
'ampersand/docker/README',
'ampersand/docker/compiler',
'ampersand/docker/modelling-environment',
'ampersand/docker/prototype-database',
'ampersand/docker/prototype-multi-stage-build',
- 'ampersand/exercises/README',
- 'ampersand/exercises/delivery',
- 'ampersand/exercises/vog-in-dutch',
- 'ampersand/installing-ampersand/README',
- 'ampersand/installing-ampersand/deploying-your-prototype',
- 'ampersand/installing-ampersand/installing-the-tools-manually',
+ 'ampersand/exercises',
'ampersand/modeling/README',
'ampersand/modeling/architecture',
'ampersand/modeling/conceptual-modeling',
@@ -168,56 +229,50 @@ module.exports = {
),
toolsWeUseMainSidebar: [
- {
- label: 'Tools for contributors',
- type: 'category',
- items: [
- 'the-tools-we-use/README',
- 'the-tools-we-use/SUMMARY',
- 'the-tools-we-use/ampersand-language-support',
- 'the-tools-we-use/authentication-and-access-management-with-oauth',
- 'the-tools-we-use/automation-of-releasing-ci-cd/README',
- 'the-tools-we-use/automation-of-releasing-ci-cd/github-packages',
- 'the-tools-we-use/building/README',
- 'the-tools-we-use/building/automated-builds',
- 'the-tools-we-use/building/building-an-ampersand-compiler-as-docker-image',
- 'the-tools-we-use/building/haskell',
- 'the-tools-we-use/building/testing-with-docker-on-your-own-laptop',
- 'the-tools-we-use/deploying-rap3-with-azure',
- 'the-tools-we-use/deploying-rap3-with-azure/deploying-rap3-with-azure-on-windows-server',
- 'the-tools-we-use/deploying-with-kubernetes',
- 'the-tools-we-use/functionality-of-rap3/README',
- 'the-tools-we-use/functionality-of-rap3/account-manager',
- 'the-tools-we-use/functionality-of-rap3/graduate-student',
- 'the-tools-we-use/functionality-of-rap3/logging-in',
- 'the-tools-we-use/functionality-of-rap3/student',
- 'the-tools-we-use/functionality-of-rap3/tutor',
- 'the-tools-we-use/git',
- 'the-tools-we-use/gitbook/README',
- 'the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation',
- 'the-tools-we-use/gitbook/getting-started-with-gitbook',
- 'the-tools-we-use/group-1/development-using-vs-code',
- 'the-tools-we-use/installation-of-rap/README',
- 'the-tools-we-use/installation-of-rap/deploying-ounl-rap3',
- 'the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu',
- 'the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop',
- 'the-tools-we-use/installation-of-rap/deployment-configuration',
- 'the-tools-we-use/installation-of-rap/details',
- 'the-tools-we-use/installation-of-rap/making-docker-images',
- 'the-tools-we-use/installation-of-rap/redeploying-rap3',
- 'the-tools-we-use/klad',
- 'the-tools-we-use/making-images',
- 'the-tools-we-use/prototype-framework',
- 'the-tools-we-use/rap3-student',
- 'the-tools-we-use/rap3-tutor',
- 'the-tools-we-use/releasing-ampersand-and-workflow-details',
- 'the-tools-we-use/tools-used-in-the-ampersand-project'
- ]
- }
+ // {
+ // label: 'Tools for contributors',
+ // type: 'category',
+ // items: [
+ // 'the-tools-we-use/README',
+ // 'the-tools-we-use/SUMMARY',
+ // 'the-tools-we-use/ampersand-language-support',
+ // 'the-tools-we-use/authentication-and-access-management-with-oauth',
+ // 'the-tools-we-use/automation-of-releasing-ci-cd/README',
+ // 'the-tools-we-use/automation-of-releasing-ci-cd/github-packages',
+ // 'the-tools-we-use/building/README',
+ // 'the-tools-we-use/building/automated-builds',
+ // 'the-tools-we-use/building/building-an-ampersand-compiler-as-docker-image',
+ // 'the-tools-we-use/building/haskell',
+ // 'the-tools-we-use/building/testing-with-docker-on-your-own-laptop',
+ // 'the-tools-we-use/deploying-rap3-with-azure',
+ // 'the-tools-we-use/deploying-rap3-with-azure/deploying-rap3-with-azure-on-windows-server',
+ // 'the-tools-we-use/deploying-with-kubernetes',
+ // 'the-tools-we-use/functionality-of-rap3/README',
+ // 'the-tools-we-use/git',
+ // 'the-tools-we-use/gitbook/README',
+ // 'the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation',
+ // 'the-tools-we-use/gitbook/getting-started-with-gitbook',
+ // 'the-tools-we-use/group-1/development-using-vs-code',
+ // 'the-tools-we-use/installation-of-rap/README',
+ // 'the-tools-we-use/installation-of-rap/deploying-ounl-rap3',
+ // 'the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu',
+ // 'the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop',
+ // 'the-tools-we-use/installation-of-rap/deployment-configuration',
+ // 'the-tools-we-use/installation-of-rap/details',
+ // 'the-tools-we-use/installation-of-rap/making-docker-images',
+ // 'the-tools-we-use/installation-of-rap/redeploying-rap3',
+ // 'the-tools-we-use/klad',
+ // 'the-tools-we-use/making-images',
+ // 'the-tools-we-use/prototype-framework',
+ // 'the-tools-we-use/rap3-student',
+ // 'the-tools-we-use/rap3-tutor',
+ // 'the-tools-we-use/releasing-ampersand-and-workflow-details',
+ // 'the-tools-we-use/tools-used-in-the-ampersand-project'
+ // ]
+ // }
],
notOnOldSite: [
- 'ampersand/conceptual/theory',
'ampersand/conceptual/automated-rules',
]
diff --git a/docs/the-command-line-tool.md b/docs/the-command-line-tool.md
index d29e426f9d..38b8b295f0 100644
--- a/docs/the-command-line-tool.md
+++ b/docs/the-command-line-tool.md
@@ -41,8 +41,7 @@ In the sequel we will use `ampersand` as an alias for `docker run -it -v "$(pwd)
## Description
-The command `ampersand` takes a file as input. It must contain a valid ampersand script, i.e. a script that complies to the [syntax](./the-language-ampersand/syntactical-conventions/) and semantics of ampersand. The compiler will not generate any output unless the script is valid.
-
+The command `ampersand` takes a file as input. It must contain a valid ampersand script, i.e. a script that complies to the [syntax](./reference-material/how-to-read-syntax-statements) and semantics of ampersand. The compiler will not generate any output unless the script is valid.
## Examples
@@ -68,7 +67,7 @@ We are happy to receive [bug reports at AmpersandTarski](https://github.com/Ampe
In case the Ampersand compiler is called by software and fails, it is useful to have an exit code to give some information about the nature of the failure. The Ampersand compiler [produces the following exit codes](https://github.com/AmpersandTarski/Ampersand/blob/main/src/Ampersand/Basics/Exit.hs):
| Code | Name | Meaning |
-| ---- | --- | --- |
+| ---- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | Success | Compilation has terminated without failures |
| 2 | Fatal | This is a software error in the Ampersand compiler, that should never have occured in operational use. Please [report an issue](https://github.com/AmpersandTarski/ampersand/issues). |
| 10 | Invalid | The script is not valid and the compiler has produced error messages to help you diagnose your mistake(s). |
diff --git a/docs/the-tools-we-use/Initial loading of RAP.JPG b/docs/the-tools-we-use/Initial loading of RAP.JPG
new file mode 100644
index 0000000000..c085818518
Binary files /dev/null and b/docs/the-tools-we-use/Initial loading of RAP.JPG differ
diff --git a/docs/the-tools-we-use/Modify release title.PNG b/docs/the-tools-we-use/Modify release title.PNG
new file mode 100644
index 0000000000..c1ad17057e
Binary files /dev/null and b/docs/the-tools-we-use/Modify release title.PNG differ
diff --git a/docs/the-tools-we-use/README.md b/docs/the-tools-we-use/README.md
new file mode 100644
index 0000000000..93cb2ade45
--- /dev/null
+++ b/docs/the-tools-we-use/README.md
@@ -0,0 +1,38 @@
+# Introduction
+
+## Introduction
+
+In the early days of the development of Ampersand, it was a single person's project. Haskell was used as programming language, and the source code was kept on a single PC. Fortunately, things have evolved. Now we have a team, and we use quite a lot of open source tooling to help us along. The downside is that not everybody in the team knows all there is to know about the tooling. The purpose of this guide is to help out. It will also be a great place to start for new team members.
+
+The [up to date version of this book](http://ampersandtarski.gitbooks.io/the-tools-we-use-for-ampersand/) is published automatically every time a commit is done to the master branch.
+
+Documentation on actually using Ampersand - e.g. for making and running prototypes (including the ways to install on your computer what it takes to do so) - is in another document, called [Ampersand Documentation](https://ampersandtarski.gitbook.io/documentation/)
+
+## Working Principles
+
+* The Ampersand project produces free open source software, available to everyone.
+* "We" is the [Ampersand community](https://github.com/orgs/AmpersandTarski/people) as specified on Github. We adhere to our own working principles to the best of our ability.
+* We respect the intellectual contribution of all. We wish to keep it that way by acknowledging intellectual ownership wherever appropriate.
+* We write software for maintainability, to facilitate others to contribute. This implies simplicity and understandability of all software artifacts. It means we document code to be relevant (for new team members), complete (for finding everything you need), and minimal (to save readers some reading effort). It implies we reuse code and strive for orthogonal design.
+* We automate the production of software to the max, to obtain robust and fast deployments and save ourselves repeated work.
+* When in trouble, we write an issue on [GitHub](https://github.com/AmpersandTarski/Ampersand/). We diagnose each problem before suggesting solutions. The diagnosis is documented on Github by means of comments to the issue. Once an issue is closed, we edit the issue to minimize text and focus on the correct diagnosis.
+* Ampersand is under construction all the time. We accept the consequences and make them as bearable as we can.
+* We believe in a formal foundation of software engineering.
+* We seek to adopt sound software engineering practices that have demonstrated quality.
+* We want to reuse good software built by others, not only to save ourselves maintenance work, but also to benefit from things that others have done in a better way.
+
+## Contributions to the documentation
+
+If you have anything to fix or details to add, just post a comment next to the paragraph. We really appreciate if you do so, because our readers know best what it is they are looking for in the docs.
+
+You can do that by clicking the icon that appears when you hover above the paragraph. Don't be shy! Try it out! (you need to be logged in however, but it is totally free to create an account).
+
+## Licence
+
+Unless otherwise specified, everything in this repository is covered by the following licence:
+
+
+
+_**Ampersand Documentation**_ by the [the Ampersand team](http://www.gitbook.com/@ampersandtarski/) is licensed under a [Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by-sa/4.0/).
+
+Based on a work at [https://github.com/AmpersandTarski/TheToolsWeUse](https://github.com/AmpersandTarski/TheToolsWeUse)
diff --git a/docs/the-tools-we-use/SUMMARY.md b/docs/the-tools-we-use/SUMMARY.md
new file mode 100644
index 0000000000..ac349cd53c
--- /dev/null
+++ b/docs/the-tools-we-use/SUMMARY.md
@@ -0,0 +1,33 @@
+# Table of contents
+
+* [Introduction](README.md)
+* [Tools used in the Ampersand project](tools-used-in-the-ampersand-project.md)
+* [Version control with Git](git.md)
+* [How to release an Ampersand upgrade](releasing-ampersand-and-workflow-details.md)
+* [Documenting with GitBook](gitbook/README.md)
+ * [Getting started with GitBook](gitbook/getting-started-with-gitbook.md)
+ * [Do's and Dont's in Ampersand documentation](gitbook/dos-and-donts-in-ampersand-documentation.md)
+* [Building](building/README.md)
+ * [Building an Ampersand Compiler with Stack](building/haskell.md)
+ * [Baking a Docker image that contains the Ampersand Compiler](building/building-an-ampersand-compiler-as-docker-image.md)
+ * [Testing with Docker on your own laptop](building/testing-with-docker-on-your-own-laptop.md)
+ * [Automated builds](building/automated-builds.md)
+* [Prototype framework](prototype-framework.md)
+* [Automation of releasing (CI/CD)](automation-of-releasing-ci-cd/README.md)
+ * [Github packages](automation-of-releasing-ci-cd/github-packages.md)
+* [Installation of RAP](installation-of-rap/README.md)
+ * [Deploying to your own laptop](installation-of-rap/deploying-to-your-own-laptop.md)
+ * [Deploying RAP4 in the Azure cloud](installation-of-rap/deploying-rap3-with-azure-on-ubuntu.md)
+ * [Deploying OUNL RAP4](installation-of-rap/deploying-ounl-rap3.md)
+ * [Maintaining RAP4](installation-of-rap/redeploying-rap3.md)
+ * [Making Docker images](installation-of-rap/making-docker-images.md)
+ * [Deployment Configuration](installation-of-rap/deployment-configuration.md)
+ * [Details](installation-of-rap/details.md)
+* [Functionality of RAP4](functionality-of-rap3/README.md)
+* [Deploying with Kubernetes](deploying-with-kubernetes.md)
+* [Authentication and access management with OAuth](authentication-and-access-management-with-oauth.md)
+* [Ampersand language support](ampersand-language-support.md)
+
+## Group 1
+
+* [Development using VS Code](group-1/development-using-vs-code.md)
diff --git a/docs/the-tools-we-use/ampersand-language-support.md b/docs/the-tools-we-use/ampersand-language-support.md
new file mode 100644
index 0000000000..becb7da679
--- /dev/null
+++ b/docs/the-tools-we-use/ampersand-language-support.md
@@ -0,0 +1,22 @@
+---
+description: This page describes tooling and workflow in relation to our VSCode extention
+---
+
+# Ampersand language support
+
+As we start fiddling around with getting a first version of VSCode extention, it turns out all kind of tooling needs to be in place. The vision of the extention is that it will eventually give ampersand modellers a rich integrated development environment, including syntax colouring, prettyprint, syntax supported editing, script execution etc etc.
+
+At first, I had a look at [language-haskell](https://github.com/JustusAdam/language-haskell). They have some IDE support in place, so it seems a reasonable first start. I don't like to invent the wheel myself.
+
+
+
+### [npm](https://docs.npmjs.com/)
+
+There is a lot of javascript going on, so we need a package manager for it.
+
+### Releasing of this vs-code extension
+
+We have a release pipeline in place using travis-ci. See the travis.yml file in the root directory. Documentation of extentions can be found [here](https://code.visualstudio.com/api/working-with-extensions/publishing-extension).
+
+The personal access token in use has an expiry date on it. An email is sent to the owner of that token \(currently Han\), in advance of the expiry. It can be renewed or the expire date [can be extended](https://dev.azure.com/hanjoostenhan/_usersSettings/tokens).
+
diff --git a/docs/the-tools-we-use/assets/Comparing master and development.PNG b/docs/the-tools-we-use/assets/Comparing master and development.PNG
new file mode 100644
index 0000000000..d71e76586b
Binary files /dev/null and b/docs/the-tools-we-use/assets/Comparing master and development.PNG differ
diff --git a/docs/the-tools-we-use/assets/CompilationOK.png b/docs/the-tools-we-use/assets/CompilationOK.png
new file mode 100644
index 0000000000..c051588310
Binary files /dev/null and b/docs/the-tools-we-use/assets/CompilationOK.png differ
diff --git a/docs/the-tools-we-use/assets/Docker store.png b/docs/the-tools-we-use/assets/Docker store.png
new file mode 100644
index 0000000000..9fb2ac1cc2
Binary files /dev/null and b/docs/the-tools-we-use/assets/Docker store.png differ
diff --git a/docs/the-tools-we-use/assets/Filezilla transfer confirmation.png b/docs/the-tools-we-use/assets/Filezilla transfer confirmation.png
new file mode 100644
index 0000000000..12a3a64e27
Binary files /dev/null and b/docs/the-tools-we-use/assets/Filezilla transfer confirmation.png differ
diff --git a/docs/the-tools-we-use/assets/Filezilla with RAP3.png b/docs/the-tools-we-use/assets/Filezilla with RAP3.png
new file mode 100644
index 0000000000..8f7937b51c
Binary files /dev/null and b/docs/the-tools-we-use/assets/Filezilla with RAP3.png differ
diff --git a/docs/the-tools-we-use/assets/Login2.png b/docs/the-tools-we-use/assets/Login2.png
new file mode 100644
index 0000000000..1276e1c877
Binary files /dev/null and b/docs/the-tools-we-use/assets/Login2.png differ
diff --git a/docs/the-tools-we-use/assets/MySQL authorization.png b/docs/the-tools-we-use/assets/MySQL authorization.png
new file mode 100644
index 0000000000..068ebcf452
Binary files /dev/null and b/docs/the-tools-we-use/assets/MySQL authorization.png differ
diff --git a/docs/the-tools-we-use/assets/NieuwScript.png b/docs/the-tools-we-use/assets/NieuwScript.png
new file mode 100644
index 0000000000..2d8bf9235e
Binary files /dev/null and b/docs/the-tools-we-use/assets/NieuwScript.png differ
diff --git a/docs/the-tools-we-use/assets/appveyor-2.svg b/docs/the-tools-we-use/assets/appveyor-2.svg
new file mode 100644
index 0000000000..ba5aa2182e
--- /dev/null
+++ b/docs/the-tools-we-use/assets/appveyor-2.svg
@@ -0,0 +1,813 @@
+
+
+
+
+
+
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <link rel="dns-prefetch" href="https://github.githubassets.com">
+ <link rel="dns-prefetch" href="https://avatars0.githubusercontent.com">
+ <link rel="dns-prefetch" href="https://avatars1.githubusercontent.com">
+ <link rel="dns-prefetch" href="https://avatars2.githubusercontent.com">
+ <link rel="dns-prefetch" href="https://avatars3.githubusercontent.com">
+ <link rel="dns-prefetch" href="https://github-cloud.s3.amazonaws.com">
+ <link rel="dns-prefetch" href="https://user-images.githubusercontent.com/">
+
+
+
+ <link crossorigin="anonymous" media="all" integrity="sha512-pWLt6abkYhNeAHaDrPVG0yXCtIGRuCkwSUqQpsyN6smAIpIt+Iuq2IZKmoH9l3Cy/9ZnjvVrFZnvFFjGiqE3EA==" rel="stylesheet" href="https://github.githubassets.com/assets/frameworks-a3b8a10d4a9e37a78f033ef4a4f525f5.css" />
+ <link crossorigin="anonymous" media="all" integrity="sha512-dxPXgds3OIQjU78JRRCF458uNHP68hRYga8g2b3tp305KzBWfi0YhaW1laHSt4/De3h4AQe3ZiDfJp1xw4azHQ==" rel="stylesheet" href="https://github.githubassets.com/assets/github-06318b2393831ab28f1e07793316df55.css" />
+
+
+ <link crossorigin="anonymous" media="all" integrity="sha512-N5cRdPCXHO5wgAMNwip0pdEIY0qHrTsCnrGLSLxLiQ8TVr0Mi2xZjL6/CzD3LakUjPrFHc06OU5i0jEQ8hCwJA==" rel="stylesheet" href="https://github.githubassets.com/assets/site-bdd55e67f0ed3e8974c7c941589e8c6a.css" />
+
+
+
+ <meta name="viewport" content="width=device-width">
+
+ <title>logos/appveyor.svg at master · gilbarbara/logos · GitHub</title>
+ <meta name="description" content="A huge collection of SVG logos. Contribute to gilbarbara/logos development by creating an account on GitHub.">
+ <link rel="search" type="application/opensearchdescription+xml" href="/opensearch.xml" title="GitHub">
+ <link rel="fluid-icon" href="https://github.com/fluidicon.png" title="GitHub">
+ <meta property="fb:app_id" content="1401488693436528">
+
+
+ <meta property="og:image" content="https://avatars2.githubusercontent.com/u/31954?s=400&v=4" /><meta property="og:site_name" content="GitHub" /><meta property="og:type" content="object" /><meta property="og:title" content="gilbarbara/logos" /><meta property="og:url" content="https://github.com/gilbarbara/logos" /><meta property="og:description" content="A huge collection of SVG logos. Contribute to gilbarbara/logos development by creating an account on GitHub." />
+
+ <link rel="assets" href="https://github.githubassets.com/">
+
+ <meta name="pjax-timeout" content="1000">
+
+ <meta name="request-id" content="E8F7:CAEF:53D2C5C:7FF9F1E:5C55B661" data-pjax-transient>
+
+
+
+
+ <meta name="selected-link" value="repo_source" data-pjax-transient>
+
+ <meta name="google-site-verification" content="KT5gs8h0wvaagLKAVWq8bbeNwnZZK1r1XQysX3xurLU">
+ <meta name="google-site-verification" content="ZzhVyEFwb7w3e0-uOTltm8Jsck2F5StVihD0exw2fsA">
+ <meta name="google-site-verification" content="GXs5KoUUkNCoaAZn7wPN-t01Pywp9M3sEjnt_3_ZWPc">
+
+ <meta name="octolytics-host" content="collector.githubapp.com" /><meta name="octolytics-app-id" content="github" /><meta name="octolytics-event-url" content="https://collector.githubapp.com/github-external/browser_event" /><meta name="octolytics-dimension-request_id" content="E8F7:CAEF:53D2C5C:7FF9F1E:5C55B661" /><meta name="octolytics-dimension-region_edge" content="ams" /><meta name="octolytics-dimension-region_render" content="iad" />
+<meta name="analytics-location" content="/<user-name>/<repo-name>/blob/show" data-pjax-transient="true" />
+
+
+
+ <meta name="google-analytics" content="UA-3769691-2">
+
+
+<meta class="js-ga-set" name="dimension1" content="Logged Out">
+
+
+
+
+
+ <meta name="hostname" content="github.com">
+ <meta name="user-login" content="">
+
+ <meta name="expected-hostname" content="github.com">
+ <meta name="js-proxy-site-detection-payload" content="NmI5NWQyNmFkNTVjNTI1NGM2MzAxOTE1NGI1NmFlZDg2NWI0ZWM0Nzc4MzU4M2YwMjI1NGFhYWRlOGJiZTNlOHx7InJlbW90ZV9hZGRyZXNzIjoiODMuMTYwLjE2OS4yNDUiLCJyZXF1ZXN0X2lkIjoiRThGNzpDQUVGOjUzRDJDNUM6N0ZGOUYxRTo1QzU1QjY2MSIsInRpbWVzdGFtcCI6MTU0OTEyMTEyMSwiaG9zdCI6ImdpdGh1Yi5jb20ifQ==">
+
+ <meta name="enabled-features" content="UNIVERSE_BANNER,MARKETPLACE_PLAN_RESTRICTION_EDITOR">
+
+ <meta name="html-safe-nonce" content="ba9e43d2e74b8242932385daf29edce1d50f1000">
+
+ <meta http-equiv="x-pjax-version" content="75d9550d00ed8d3248175033d00a1ca1">
+
+
+ <link href="https://github.com/gilbarbara/logos/commits/master.atom" rel="alternate" title="Recent Commits to logos:master" type="application/atom+xml">
+
+ <meta name="go-import" content="github.com/gilbarbara/logos git https://github.com/gilbarbara/logos.git">
+
+ <meta name="octolytics-dimension-user_id" content="31954" /><meta name="octolytics-dimension-user_login" content="gilbarbara" /><meta name="octolytics-dimension-repository_id" content="37291982" /><meta name="octolytics-dimension-repository_nwo" content="gilbarbara/logos" /><meta name="octolytics-dimension-repository_public" content="true" /><meta name="octolytics-dimension-repository_is_fork" content="false" /><meta name="octolytics-dimension-repository_network_root_id" content="37291982" /><meta name="octolytics-dimension-repository_network_root_nwo" content="gilbarbara/logos" /><meta name="octolytics-dimension-repository_explore_github_marketplace_ci_cta_shown" content="false" />
+
+
+ <link rel="canonical" href="https://github.com/gilbarbara/logos/blob/master/logos/appveyor.svg" data-pjax-transient>
+
+
+ <meta name="browser-stats-url" content="https://api.github.com/_private/browser/stats">
+
+ <meta name="browser-errors-url" content="https://api.github.com/_private/browser/errors">
+
+ <link rel="mask-icon" href="https://github.githubassets.com/pinned-octocat.svg" color="#000000">
+ <link rel="icon" type="image/x-icon" class="js-site-favicon" href="https://github.githubassets.com/favicon.ico">
+
+<meta name="theme-color" content="#1e2327">
+
+
+
+ <link rel="manifest" href="/manifest.json" crossOrigin="use-credentials">
+
+ </head>
+
+ <body class="logged-out env-production page-blob">
+
+
+ <div class="position-relative js-header-wrapper ">
+ <a href="#start-of-content" tabindex="1" class="px-2 py-4 bg-blue text-white show-on-focus js-skip-to-content">Skip to content</a>
+ <div id="js-pjax-loader-bar" class="pjax-loader-bar"><div class="progress"></div></div>
+
+
+
+ <div class="unsupported-browser">
+ <div class="container clearfix d-flex flex-items-center py-2">
+ <img src="https://github.githubassets.com/images/icons/ie-notice.png" class="flex-self-start flex-shrink-0 pt-1 mr-2 ">
+ <div class="d-flex flex-auto flex-row">
+ <div class="flex-auto min-width-0 mr-2">
+ <h5>Please note that GitHub no longer supports Internet Explorer.</h5>
+ <p class="m-0">We recommend upgrading to the latest <a href="https://www.microsoft.com/en-us/windows/microsoft-edge">Microsoft Edge</a>, <a href="https://chrome.google.com">Google Chrome</a>, or <a href="https://mozilla.org/firefox/">Firefox</a>.</p>
+ </div>
+ <div class="d-flex flex-items-center flex-shrink-0 ">
+ <!-- '"` --><!-- </textarea></xmp> --></option></form><form action="/site/dismiss_unsupported_browser" accept-charset="UTF-8" method="post"><input name="utf8" type="hidden" value="✓" /><input type="hidden" name="authenticity_token" value="6YMyySNthoN5ThDE/bGtH6oumE/31KGLWFN1EZULyOCvJfmLFR0nB8ENZSWLk7QIMFI+dro5mkQ9KVjR8iJZ5w==" />
+ <button type="submit" class="btn btn-danger">Ignore</button>
+</form> <a href="https://help.github.com/articles/supported-browsers" class="btn ml-2">Learn more</a>
+ </div>
+ </div>
+ </div>
+</div>
+
+
+
+
+<header class="Header header-logged-out position-relative f4 py-3" role="banner">
+ <div class="container-lg d-flex px-3">
+ <div class="d-flex flex-justify-between flex-items-center">
+ <a class="mr-4" href="https://github.com/" aria-label="Homepage" data-ga-click="(Logged out) Header, go to homepage, icon:logo-wordmark">
+ <svg height="32" class="octicon octicon-mark-github text-white" viewBox="0 0 16 16" version="1.1" width="32" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
+ </a>
+ </div>
+
+ <div class="HeaderMenu HeaderMenu--logged-out d-flex flex-justify-between flex-items-center flex-auto">
+ <div class="d-none">
+ <button class="btn-link js-details-target" type="button" aria-label="Toggle navigation" aria-expanded="false">
+ <svg height="24" class="octicon octicon-x text-gray" viewBox="0 0 12 16" version="1.1" width="18" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48L7.48 8z"/></svg>
+ </button>
+ </div>
+
+ <nav class="mt-0" aria-label="Global">
+ <ul class="d-flex list-style-none">
+ <li class=" mr-3 mr-lg-3 edge-item-fix position-relative flex-wrap flex-justify-between d-flex flex-items-center ">
+ <details class="HeaderMenu-details details-overlay details-reset width-full">
+ <summary class="HeaderMenu-summary HeaderMenu-link px-0 py-3 border-0 no-wrap d-inline-block">
+ Why GitHub?
+ <svg x="0px" y="0px" viewBox="0 0 14 8" xml:space="preserve" fill="none" class="icon-chevon-down-mktg position-relative">
+ <path d="M1,1l6.2,6L13,1"></path>
+ </svg>
+ </summary>
+ <div class="dropdown-menu flex-auto rounded-1 bg-white px-0 mt-0 p-4 left-n4 position-absolute">
+ <a href="/features" class="py-2 lh-condensed-ultra d-block link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Features">Features <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a>
+ <ul class="list-style-none f5 pb-3">
+ <li class="edge-item-fix"><a href="/features/code-review/" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Code review">Code review</a></li>
+ <li class="edge-item-fix"><a href="/features/project-management/" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Project management">Project management</a></li>
+ <li class="edge-item-fix"><a href="/features/integrations" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Integrations">Integrations</a></li>
+ <li class="edge-item-fix"><a href="/features/actions" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Actions">Actions</a>
+ <li class="edge-item-fix"><a href="/features#team-management" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Team management">Team management</a></li>
+ <li class="edge-item-fix"><a href="/features#social-coding" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Social coding">Social coding</a></li>
+ <li class="edge-item-fix"><a href="/features#documentation" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Documentation">Documentation</a></li>
+ <li class="edge-item-fix"><a href="/features#code-hosting" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Code hosting">Code hosting</a></li>
+ </ul>
+
+ <ul class="list-style-none mb-0 border-lg-top pt-lg-3">
+ <li class="edge-item-fix"><a href="/case-studies" class="py-2 lh-condensed-ultra d-block no-underline link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Case studies">Case Studies <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a></li>
+ <li class="edge-item-fix"><a href="/security" class="py-2 lh-condensed-ultra d-block no-underline link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Security">Security <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a></li>
+ </ul>
+ </div>
+ </details>
+ </li>
+ <li class=" mr-3 mr-lg-3">
+ <a href="/enterprise" class="HeaderMenu-link no-underline py-3 d-block d-lg-inline-block" data-ga-click="(Logged out) Header, click, go to Enterprise">Enterprise</a>
+ </li>
+
+ <li class=" mr-3 mr-lg-3 edge-item-fix position-relative flex-wrap flex-justify-between d-flex flex-items-center ">
+ <details class="HeaderMenu-details details-overlay details-reset width-full">
+ <summary class="HeaderMenu-summary HeaderMenu-link px-0 py-3 border-0 no-wrap d-inline-block">
+ Explore
+ <svg x="0px" y="0px" viewBox="0 0 14 8" xml:space="preserve" fill="none" class="icon-chevon-down-mktg position-relative">
+ <path d="M1,1l6.2,6L13,1"></path>
+ </svg>
+ </summary>
+
+ <div class="dropdown-menu flex-auto rounded-1 bg-white px-0 pt-2 pb-0 mt-0 p-4 left-n4 position-absolute">
+ <ul class="list-style-none mb-3">
+ <li class="edge-item-fix"><a href="/explore" class="py-2 lh-condensed-ultra d-block link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Features">Explore GitHub <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a></li>
+ </ul>
+
+ <h4 class="text-gray-light text-normal text-mono f5 mb-2 border-top pt-3">Learn & contribute</h4>
+ <ul class="list-style-none mb-3">
+ <li class="edge-item-fix"><a href="/topics" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Topics">Topics</a></li>
+ <li class="edge-item-fix"><a href="/collections" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Collections">Collections</a></li>
+ <li class="edge-item-fix"><a href="/trending" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Trending">Trending</a></li>
+ <li class="edge-item-fix"><a href="https://lab.github.com/" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Learning lab">Learning Lab</a></li>
+ <li class="edge-item-fix"><a href="https://opensource.guide" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Open source guides">Open source guides</a></li>
+ </ul>
+
+ <h4 class="text-gray-light text-normal text-mono f5 mb-2 border-top pt-3">Connect with others</h4>
+ <ul class="list-style-none mb-0">
+ <li class="edge-item-fix"><a href="/events" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Events">Events</a></li>
+ <li class="edge-item-fix"><a href="https://github.community" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Community forum">Community forum</a></li>
+ <li class="edge-item-fix"><a href="https://education.github.com" class="py-2 pb-0 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to GitHub Education">GitHub Education</a></li>
+ </ul>
+ </div>
+ </details>
+ </li>
+
+ <li class=" mr-3 mr-lg-3">
+ <a href="/marketplace" class="HeaderMenu-link no-underline py-3 d-block d-lg-inline-block" data-ga-click="(Logged out) Header, go to Marketplace">Marketplace</a>
+ </li>
+
+ <li class=" mr-3 mr-lg-3 edge-item-fix position-relative flex-wrap flex-justify-between d-flex flex-items-center ">
+ <details class="HeaderMenu-details details-overlay details-reset width-full">
+ <summary class="HeaderMenu-summary HeaderMenu-link px-0 py-3 border-0 no-wrap d-inline-block">
+ Pricing
+ <svg x="0px" y="0px" viewBox="0 0 14 8" xml:space="preserve" fill="none" class="icon-chevon-down-mktg position-relative">
+ <path d="M1,1l6.2,6L13,1"></path>
+ </svg>
+ </summary>
+
+ <div class="dropdown-menu flex-auto rounded-1 bg-white px-0 pt-2 pb-4 mt-0 p-4 left-n4 position-absolute">
+ <a href="/pricing" class="pb-2 lh-condensed-ultra d-block link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Pricing">Plans <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a>
+
+ <ul class="list-style-none mb-3">
+ <li class="edge-item-fix"><a href="/pricing#feature-comparison" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Compare features">Compare plans</a></li>
+ <li class="edge-item-fix"><a href="https://enterprise.github.com/contact" class="py-2 lh-condensed-ultra d-block link-gray no-underline f5" data-ga-click="(Logged out) Header, go to Compare features">Contact Sales</a></li>
+ </ul>
+
+ <ul class="list-style-none mb-0 border-top pt-3">
+ <li class="edge-item-fix"><a href="/nonprofit" class="py-2 lh-condensed-ultra d-block no-underline link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Nonprofits">Nonprofit <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a></li>
+ <li class="edge-item-fix"><a href="https://education.github.com" class="py-2 pb-0 lh-condensed-ultra d-block no-underline link-gray-dark no-underline h5 Bump-link--hover" data-ga-click="(Logged out) Header, go to Education">Education <span class="Bump-link-symbol float-right text-normal text-gray-light">→</span></a></li>
+ </ul>
+ </div>
+ </details>
+ </li>
+ </ul>
+ </nav>
+
+ <div class="d-flex flex-items-center px-0 text-center text-left">
+ <div class="d-lg-flex mr-3">
+ <div class="header-search scoped-search site-scoped-search js-site-search position-relative js-jump-to"
+ role="combobox"
+ aria-owns="jump-to-results"
+ aria-label="Search or jump to"
+ aria-haspopup="listbox"
+ aria-expanded="false"
+>
+ <div class="position-relative">
+ <!-- '"` --><!-- </textarea></xmp> --></option></form><form class="js-site-search-form" data-scope-type="Repository" data-scope-id="37291982" data-scoped-search-url="/gilbarbara/logos/search" data-unscoped-search-url="/search" action="/gilbarbara/logos/search" accept-charset="UTF-8" method="get"><input name="utf8" type="hidden" value="✓" />
+ <label class="form-control header-search-wrapper header-search-wrapper-jump-to position-relative d-flex flex-justify-between flex-items-center js-chromeless-input-container">
+ <input type="text"
+ class="form-control header-search-input jump-to-field js-jump-to-field js-site-search-focus js-site-search-field is-clearable"
+ data-hotkey="s,/"
+ name="q"
+ value=""
+ placeholder="Search"
+ data-unscoped-placeholder="Search GitHub"
+ data-scoped-placeholder="Search"
+ autocapitalize="off"
+ aria-autocomplete="list"
+ aria-controls="jump-to-results"
+ aria-label="Search"
+ data-jump-to-suggestions-path="/_graphql/GetSuggestedNavigationDestinations#csrf-token=Qd9uv44mCSRj5lhSz+INqeiuHZuqSsw6H3LrZioRywSZmJg+mHA0eQJ6KEDQN+2JOcc4BBl0llM6bP80tMwplQ=="
+ spellcheck="false"
+ autocomplete="off"
+ >
+ <input type="hidden" class="js-site-search-type-field" name="type" >
+ <img src="https://github.githubassets.com/images/search-key-slash.svg" alt="" class="mr-2 header-search-key-slash">
+
+ <div class="Box position-absolute overflow-hidden d-none jump-to-suggestions js-jump-to-suggestions-container">
+
+<ul class="d-none js-jump-to-suggestions-template-container">
+
+
+<li class="d-flex flex-justify-start flex-items-center p-0 f5 navigation-item js-navigation-item js-jump-to-suggestion" role="option">
+ <a tabindex="-1" class="no-underline d-flex flex-auto flex-items-center jump-to-suggestions-path js-jump-to-suggestion-path js-navigation-open p-2" href="">
+ <div class="jump-to-octicon js-jump-to-octicon flex-shrink-0 mr-2 text-center d-none">
+ <svg height="16" width="16" class="octicon octicon-repo flex-shrink-0 js-jump-to-octicon-repo d-none" title="Repository" aria-label="Repository" viewBox="0 0 12 16" version="1.1" role="img"><path fill-rule="evenodd" d="M4 9H3V8h1v1zm0-3H3v1h1V6zm0-2H3v1h1V4zm0-2H3v1h1V2zm8-1v12c0 .55-.45 1-1 1H6v2l-1.5-1.5L3 16v-2H1c-.55 0-1-.45-1-1V1c0-.55.45-1 1-1h10c.55 0 1 .45 1 1zm-1 10H1v2h2v-1h3v1h5v-2zm0-10H2v9h9V1z"/></svg>
+ <svg height="16" width="16" class="octicon octicon-project flex-shrink-0 js-jump-to-octicon-project d-none" title="Project" aria-label="Project" viewBox="0 0 15 16" version="1.1" role="img"><path fill-rule="evenodd" d="M10 12h3V2h-3v10zm-4-2h3V2H6v8zm-4 4h3V2H2v12zm-1 1h13V1H1v14zM14 0H1a1 1 0 0 0-1 1v14a1 1 0 0 0 1 1h13a1 1 0 0 0 1-1V1a1 1 0 0 0-1-1z"/></svg>
+ <svg height="16" width="16" class="octicon octicon-search flex-shrink-0 js-jump-to-octicon-search d-none" title="Search" aria-label="Search" viewBox="0 0 16 16" version="1.1" role="img"><path fill-rule="evenodd" d="M15.7 13.3l-3.81-3.83A5.93 5.93 0 0 0 13 6c0-3.31-2.69-6-6-6S1 2.69 1 6s2.69 6 6 6c1.3 0 2.48-.41 3.47-1.11l3.83 3.81c.19.2.45.3.7.3.25 0 .52-.09.7-.3a.996.996 0 0 0 0-1.41v.01zM7 10.7c-2.59 0-4.7-2.11-4.7-4.7 0-2.59 2.11-4.7 4.7-4.7 2.59 0 4.7 2.11 4.7 4.7 0 2.59-2.11 4.7-4.7 4.7z"/></svg>
+ </div>
+
+ <img class="avatar mr-2 flex-shrink-0 js-jump-to-suggestion-avatar d-none" alt="" aria-label="Team" src="" width="28" height="28">
+
+ <div class="jump-to-suggestion-name js-jump-to-suggestion-name flex-auto overflow-hidden text-left no-wrap css-truncate css-truncate-target">
+ </div>
+
+ <div class="border rounded-1 flex-shrink-0 bg-gray px-1 text-gray-light ml-1 f6 d-none js-jump-to-badge-search">
+ <span class="js-jump-to-badge-search-text-default d-none" aria-label="in this repository">
+ In this repository
+ </span>
+ <span class="js-jump-to-badge-search-text-global d-none" aria-label="in all of GitHub">
+ All GitHub
+ </span>
+ <span aria-hidden="true" class="d-inline-block ml-1 v-align-middle">↵</span>
+ </div>
+
+ <div aria-hidden="true" class="border rounded-1 flex-shrink-0 bg-gray px-1 text-gray-light ml-1 f6 d-none d-on-nav-focus js-jump-to-badge-jump">
+ Jump to
+ <span class="d-inline-block ml-1 v-align-middle">↵</span>
+ </div>
+ </a>
+</li>
+
+</ul>
+
+<ul class="d-none js-jump-to-no-results-template-container">
+ <li class="d-flex flex-justify-center flex-items-center f5 d-none js-jump-to-suggestion p-2">
+ <span class="text-gray">No suggested jump to results</span>
+ </li>
+</ul>
+
+<ul id="jump-to-results" role="listbox" class="p-0 m-0 js-navigation-container jump-to-suggestions-results-container js-jump-to-suggestions-results-container">
+
+
+<li class="d-flex flex-justify-start flex-items-center p-0 f5 navigation-item js-navigation-item js-jump-to-scoped-search d-none" role="option">
+ <a tabindex="-1" class="no-underline d-flex flex-auto flex-items-center jump-to-suggestions-path js-jump-to-suggestion-path js-navigation-open p-2" href="">
+ <div class="jump-to-octicon js-jump-to-octicon flex-shrink-0 mr-2 text-center d-none">
+ <svg height="16" width="16" class="octicon octicon-repo flex-shrink-0 js-jump-to-octicon-repo d-none" title="Repository" aria-label="Repository" viewBox="0 0 12 16" version="1.1" role="img"><path fill-rule="evenodd" d="M4 9H3V8h1v1zm0-3H3v1h1V6zm0-2H3v1h1V4zm0-2H3v1h1V2zm8-1v12c0 .55-.45 1-1 1H6v2l-1.5-1.5L3 16v-2H1c-.55 0-1-.45-1-1V1c0-.55.45-1 1-1h10c.55 0 1 .45 1 1zm-1 10H1v2h2v-1h3v1h5v-2zm0-10H2v9h9V1z"/></svg>
+ <svg height="16" width="16" class="octicon octicon-project flex-shrink-0 js-jump-to-octicon-project d-none" title="Project" aria-label="Project" viewBox="0 0 15 16" version="1.1" role="img"><path fill-rule="evenodd" d="M10 12h3V2h-3v10zm-4-2h3V2H6v8zm-4 4h3V2H2v12zm-1 1h13V1H1v14zM14 0H1a1 1 0 0 0-1 1v14a1 1 0 0 0 1 1h13a1 1 0 0 0 1-1V1a1 1 0 0 0-1-1z"/></svg>
+ <svg height="16" width="16" class="octicon octicon-search flex-shrink-0 js-jump-to-octicon-search d-none" title="Search" aria-label="Search" viewBox="0 0 16 16" version="1.1" role="img"><path fill-rule="evenodd" d="M15.7 13.3l-3.81-3.83A5.93 5.93 0 0 0 13 6c0-3.31-2.69-6-6-6S1 2.69 1 6s2.69 6 6 6c1.3 0 2.48-.41 3.47-1.11l3.83 3.81c.19.2.45.3.7.3.25 0 .52-.09.7-.3a.996.996 0 0 0 0-1.41v.01zM7 10.7c-2.59 0-4.7-2.11-4.7-4.7 0-2.59 2.11-4.7 4.7-4.7 2.59 0 4.7 2.11 4.7 4.7 0 2.59-2.11 4.7-4.7 4.7z"/></svg>
+ </div>
+
+ <img class="avatar mr-2 flex-shrink-0 js-jump-to-suggestion-avatar d-none" alt="" aria-label="Team" src="" width="28" height="28">
+
+ <div class="jump-to-suggestion-name js-jump-to-suggestion-name flex-auto overflow-hidden text-left no-wrap css-truncate css-truncate-target">
+ </div>
+
+ <div class="border rounded-1 flex-shrink-0 bg-gray px-1 text-gray-light ml-1 f6 d-none js-jump-to-badge-search">
+ <span class="js-jump-to-badge-search-text-default d-none" aria-label="in this repository">
+ In this repository
+ </span>
+ <span class="js-jump-to-badge-search-text-global d-none" aria-label="in all of GitHub">
+ All GitHub
+ </span>
+ <span aria-hidden="true" class="d-inline-block ml-1 v-align-middle">↵</span>
+ </div>
+
+ <div aria-hidden="true" class="border rounded-1 flex-shrink-0 bg-gray px-1 text-gray-light ml-1 f6 d-none d-on-nav-focus js-jump-to-badge-jump">
+ Jump to
+ <span class="d-inline-block ml-1 v-align-middle">↵</span>
+ </div>
+ </a>
+</li>
+
+
+
+<li class="d-flex flex-justify-start flex-items-center p-0 f5 navigation-item js-navigation-item js-jump-to-global-search d-none" role="option">
+ <a tabindex="-1" class="no-underline d-flex flex-auto flex-items-center jump-to-suggestions-path js-jump-to-suggestion-path js-navigation-open p-2" href="">
+ <div class="jump-to-octicon js-jump-to-octicon flex-shrink-0 mr-2 text-center d-none">
+ <svg height="16" width="16" class="octicon octicon-repo flex-shrink-0 js-jump-to-octicon-repo d-none" title="Repository" aria-label="Repository" viewBox="0 0 12 16" version="1.1" role="img"><path fill-rule="evenodd" d="M4 9H3V8h1v1zm0-3H3v1h1V6zm0-2H3v1h1V4zm0-2H3v1h1V2zm8-1v12c0 .55-.45 1-1 1H6v2l-1.5-1.5L3 16v-2H1c-.55 0-1-.45-1-1V1c0-.55.45-1 1-1h10c.55 0 1 .45 1 1zm-1 10H1v2h2v-1h3v1h5v-2zm0-10H2v9h9V1z"/></svg>
+ <svg height="16" width="16" class="octicon octicon-project flex-shrink-0 js-jump-to-octicon-project d-none" title="Project" aria-label="Project" viewBox="0 0 15 16" version="1.1" role="img"><path fill-rule="evenodd" d="M10 12h3V2h-3v10zm-4-2h3V2H6v8zm-4 4h3V2H2v12zm-1 1h13V1H1v14zM14 0H1a1 1 0 0 0-1 1v14a1 1 0 0 0 1 1h13a1 1 0 0 0 1-1V1a1 1 0 0 0-1-1z"/></svg>
+ <svg height="16" width="16" class="octicon octicon-search flex-shrink-0 js-jump-to-octicon-search d-none" title="Search" aria-label="Search" viewBox="0 0 16 16" version="1.1" role="img"><path fill-rule="evenodd" d="M15.7 13.3l-3.81-3.83A5.93 5.93 0 0 0 13 6c0-3.31-2.69-6-6-6S1 2.69 1 6s2.69 6 6 6c1.3 0 2.48-.41 3.47-1.11l3.83 3.81c.19.2.45.3.7.3.25 0 .52-.09.7-.3a.996.996 0 0 0 0-1.41v.01zM7 10.7c-2.59 0-4.7-2.11-4.7-4.7 0-2.59 2.11-4.7 4.7-4.7 2.59 0 4.7 2.11 4.7 4.7 0 2.59-2.11 4.7-4.7 4.7z"/></svg>
+ </div>
+
+ <img class="avatar mr-2 flex-shrink-0 js-jump-to-suggestion-avatar d-none" alt="" aria-label="Team" src="" width="28" height="28">
+
+ <div class="jump-to-suggestion-name js-jump-to-suggestion-name flex-auto overflow-hidden text-left no-wrap css-truncate css-truncate-target">
+ </div>
+
+ <div class="border rounded-1 flex-shrink-0 bg-gray px-1 text-gray-light ml-1 f6 d-none js-jump-to-badge-search">
+ <span class="js-jump-to-badge-search-text-default d-none" aria-label="in this repository">
+ In this repository
+ </span>
+ <span class="js-jump-to-badge-search-text-global d-none" aria-label="in all of GitHub">
+ All GitHub
+ </span>
+ <span aria-hidden="true" class="d-inline-block ml-1 v-align-middle">↵</span>
+ </div>
+
+ <div aria-hidden="true" class="border rounded-1 flex-shrink-0 bg-gray px-1 text-gray-light ml-1 f6 d-none d-on-nav-focus js-jump-to-badge-jump">
+ Jump to
+ <span class="d-inline-block ml-1 v-align-middle">↵</span>
+ </div>
+ </a>
+</li>
+
+
+</ul>
+
+ </div>
+ </label>
+</form> </div>
+</div>
+
+ </div>
+
+ <a class="HeaderMenu-link no-underline mr-3" href="/login?return_to=%2Fgilbarbara%2Flogos%2Fblob%2Fmaster%2Flogos%2Fappveyor.svg" data-ga-click="(Logged out) Header, clicked Sign in, text:sign-in">Sign in</a>
+ <a class="HeaderMenu-link d-inline-block no-underline border border-gray-dark rounded-1 px-2 py-1" href="/join" data-ga-click="(Logged out) Header, clicked Sign up, text:sign-up">Sign up</a>
+ </div>
+ </div>
+ </div>
+</header>
+
+ </div>
+
+ <div id="start-of-content" class="show-on-focus"></div>
+
+ <div id="js-flash-container">
+
+</div>
+
+
+
+ <div role="main" class="application-main " data-commit-hovercards-enabled>
+ <div itemscope itemtype="http://schema.org/SoftwareSourceCode" class="">
+ <div id="js-repo-pjax-container" data-pjax-container >
+
+
+
+
+
+
+
+
+
+ <div class="pagehead repohead instapaper_ignore readability-menu experiment-repo-nav ">
+ <div class="repohead-details-container clearfix container">
+
+ <ul class="pagehead-actions">
+ <li>
+ <a href="/login?return_to=%2Fgilbarbara%2Flogos"
+ class="btn btn-sm btn-with-count tooltipped tooltipped-s"
+ aria-label="You must be signed in to watch a repository" rel="nofollow">
+ <svg class="octicon octicon-eye v-align-text-bottom" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M8.06 2C3 2 0 8 0 8s3 6 8.06 6C13 14 16 8 16 8s-3-6-7.94-6zM8 12c-2.2 0-4-1.78-4-4 0-2.2 1.8-4 4-4 2.22 0 4 1.8 4 4 0 2.22-1.78 4-4 4zm2-4c0 1.11-.89 2-2 2-1.11 0-2-.89-2-2 0-1.11.89-2 2-2 1.11 0 2 .89 2 2z"/></svg>
+ Watch
+ </a>
+ <a class="social-count" href="/gilbarbara/logos/watchers"
+ aria-label="102 users are watching this repository">
+ 102
+ </a>
+
+ </li>
+
+ <li>
+ <a href="/login?return_to=%2Fgilbarbara%2Flogos"
+ class="btn btn-sm btn-with-count tooltipped tooltipped-s"
+ aria-label="You must be signed in to star a repository" rel="nofollow">
+ <svg class="octicon octicon-star v-align-text-bottom" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M14 6l-4.9-.64L7 1 4.9 5.36 0 6l3.6 3.26L2.67 14 7 11.67 11.33 14l-.93-4.74L14 6z"/></svg>
+ Star
+ </a>
+
+ <a class="social-count js-social-count" href="/gilbarbara/logos/stargazers"
+ aria-label="4176 users starred this repository">
+ 4,176
+ </a>
+
+ </li>
+
+ <li>
+ <a href="/login?return_to=%2Fgilbarbara%2Flogos"
+ class="btn btn-sm btn-with-count tooltipped tooltipped-s"
+ aria-label="You must be signed in to fork a repository" rel="nofollow">
+ <svg class="octicon octicon-repo-forked v-align-text-bottom" viewBox="0 0 10 16" version="1.1" width="10" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M8 1a1.993 1.993 0 0 0-1 3.72V6L5 8 3 6V4.72A1.993 1.993 0 0 0 2 1a1.993 1.993 0 0 0-1 3.72V6.5l3 3v1.78A1.993 1.993 0 0 0 5 15a1.993 1.993 0 0 0 1-3.72V9.5l3-3V4.72A1.993 1.993 0 0 0 8 1zM2 4.2C1.34 4.2.8 3.65.8 3c0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2zm3 10c-.66 0-1.2-.55-1.2-1.2 0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2zm3-10c-.66 0-1.2-.55-1.2-1.2 0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2z"/></svg>
+ Fork
+ </a>
+
+ <a href="/gilbarbara/logos/network/members" class="social-count"
+ aria-label="411 users forked this repository">
+ 411
+ </a>
+ </li>
+</ul>
+
+ <h1 class="public ">
+ <svg class="octicon octicon-repo" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M4 9H3V8h1v1zm0-3H3v1h1V6zm0-2H3v1h1V4zm0-2H3v1h1V2zm8-1v12c0 .55-.45 1-1 1H6v2l-1.5-1.5L3 16v-2H1c-.55 0-1-.45-1-1V1c0-.55.45-1 1-1h10c.55 0 1 .45 1 1zm-1 10H1v2h2v-1h3v1h5v-2zm0-10H2v9h9V1z"/></svg>
+ <span class="author" itemprop="author"><a class="url fn" rel="author" data-hovercard-type="user" data-hovercard-url="/hovercards?user_id=31954" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="/gilbarbara">gilbarbara</a></span><!--
+--><span class="path-divider">/</span><!--
+--><strong itemprop="name"><a data-pjax="#js-repo-pjax-container" href="/gilbarbara/logos">logos</a></strong>
+
+</h1>
+
+ </div>
+
+<nav class="reponav js-repo-nav js-sidenav-container-pjax container"
+ itemscope
+ itemtype="http://schema.org/BreadcrumbList"
+ aria-label="Repository"
+ data-pjax="#js-repo-pjax-container">
+
+ <span itemscope itemtype="http://schema.org/ListItem" itemprop="itemListElement">
+ <a class="js-selected-navigation-item selected reponav-item" itemprop="url" data-hotkey="g c" aria-current="page" data-selected-links="repo_source repo_downloads repo_commits repo_releases repo_tags repo_branches repo_packages /gilbarbara/logos" href="/gilbarbara/logos">
+ <svg class="octicon octicon-code" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M9.5 3L8 4.5 11.5 8 8 11.5 9.5 13 14 8 9.5 3zm-5 0L0 8l4.5 5L6 11.5 2.5 8 6 4.5 4.5 3z"/></svg>
+ <span itemprop="name">Code</span>
+ <meta itemprop="position" content="1">
+</a> </span>
+
+ <span itemscope itemtype="http://schema.org/ListItem" itemprop="itemListElement">
+ <a itemprop="url" data-hotkey="g i" class="js-selected-navigation-item reponav-item" data-selected-links="repo_issues repo_labels repo_milestones /gilbarbara/logos/issues" href="/gilbarbara/logos/issues">
+ <svg class="octicon octicon-issue-opened" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"/></svg>
+ <span itemprop="name">Issues</span>
+ <span class="Counter">21</span>
+ <meta itemprop="position" content="2">
+</a> </span>
+
+ <span itemscope itemtype="http://schema.org/ListItem" itemprop="itemListElement">
+ <a data-hotkey="g p" itemprop="url" class="js-selected-navigation-item reponav-item" data-selected-links="repo_pulls checks /gilbarbara/logos/pulls" href="/gilbarbara/logos/pulls">
+ <svg class="octicon octicon-git-pull-request" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M11 11.28V5c-.03-.78-.34-1.47-.94-2.06C9.46 2.35 8.78 2.03 8 2H7V0L4 3l3 3V4h1c.27.02.48.11.69.31.21.2.3.42.31.69v6.28A1.993 1.993 0 0 0 10 15a1.993 1.993 0 0 0 1-3.72zm-1 2.92c-.66 0-1.2-.55-1.2-1.2 0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2zM4 3c0-1.11-.89-2-2-2a1.993 1.993 0 0 0-1 3.72v6.56A1.993 1.993 0 0 0 2 15a1.993 1.993 0 0 0 1-3.72V4.72c.59-.34 1-.98 1-1.72zm-.8 10c0 .66-.55 1.2-1.2 1.2-.65 0-1.2-.55-1.2-1.2 0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2zM2 4.2C1.34 4.2.8 3.65.8 3c0-.65.55-1.2 1.2-1.2.65 0 1.2.55 1.2 1.2 0 .65-.55 1.2-1.2 1.2z"/></svg>
+ <span itemprop="name">Pull requests</span>
+ <span class="Counter">0</span>
+ <meta itemprop="position" content="3">
+</a> </span>
+
+
+ <a data-hotkey="g b" class="js-selected-navigation-item reponav-item" data-selected-links="repo_projects new_repo_project repo_project /gilbarbara/logos/projects" href="/gilbarbara/logos/projects">
+ <svg class="octicon octicon-project" viewBox="0 0 15 16" version="1.1" width="15" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M10 12h3V2h-3v10zm-4-2h3V2H6v8zm-4 4h3V2H2v12zm-1 1h13V1H1v14zM14 0H1a1 1 0 0 0-1 1v14a1 1 0 0 0 1 1h13a1 1 0 0 0 1-1V1a1 1 0 0 0-1-1z"/></svg>
+ Projects
+ <span class="Counter" >1</span>
+</a>
+
+
+ <a class="js-selected-navigation-item reponav-item" data-selected-links="repo_graphs repo_contributors dependency_graph pulse alerts security people /gilbarbara/logos/pulse" href="/gilbarbara/logos/pulse">
+ <svg class="octicon octicon-graph" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M16 14v1H0V0h1v14h15zM5 13H3V8h2v5zm4 0H7V3h2v10zm4 0h-2V6h2v7z"/></svg>
+ Insights
+</a>
+
+</nav>
+
+
+ </div>
+
+<div class="container new-discussion-timeline experiment-repo-nav ">
+ <div class="repository-content ">
+
+
+
+
+
+
+
+ <a class="d-none js-permalink-shortcut" data-hotkey="y" href="/gilbarbara/logos/blob/b65a7dc930f6bd4b4fe8040d6961483391305078/logos/appveyor.svg">Permalink</a>
+
+ <!-- blob contrib key: blob_contributors:v21:daf38884be2a0c1e8b61982c8342f7d8 -->
+
+ <div class="signup-prompt-bg rounded-1">
+ <div class="signup-prompt p-4 text-center mb-4 rounded-1">
+ <div class="position-relative">
+ <!-- '"` --><!-- </textarea></xmp> --></option></form><form action="/site/dismiss_signup_prompt" accept-charset="UTF-8" method="post"><input name="utf8" type="hidden" value="✓" /><input type="hidden" name="authenticity_token" value="GaFdykOGKJOTNKCw6jt1Jr3UYtR+ez1nMEnvem7cC/UiLHvhgFJYJPTdLMNUBtQof8/rbXRz0N5FKASE04Sa9w==" />
+ <button type="submit" class="position-absolute top-0 right-0 btn-link link-gray" data-ga-click="(Logged out) Sign up prompt, clicked Dismiss, text:dismiss">
+ Dismiss
+ </button>
+</form> <h3 class="pt-2">Join GitHub today</h3>
+ <p class="col-6 mx-auto">GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.</p>
+ <a class="btn btn-primary" href="/join?source=prompt-blob-show" data-ga-click="(Logged out) Sign up prompt, clicked Sign up, text:sign-up">Sign up</a>
+ </div>
+ </div>
+ </div>
+
+
+ <div class="file-navigation">
+
+<div class="select-menu branch-select-menu js-menu-container js-select-menu float-left js-load-contents"
+ data-contents-url="/gilbarbara/logos/ref-list/master/logos/appveyor.svg?source_action=show&source_controller=blob">
+ <button class="btn btn-sm select-menu-button js-menu-target css-truncate" data-hotkey="w"
+
+ type="button" aria-label="Switch branches or tags" aria-expanded="false" aria-haspopup="true">
+ <i>Branch:</i>
+ <span class="js-select-button css-truncate-target">master</span>
+ </button>
+
+ <div class="select-menu-modal-holder js-menu-content js-navigation-container" data-pjax>
+ <div class="select-menu-modal">
+ <div class="js-select-menu-deferred-content"></div>
+ <div class="select-menu-loading-overlay anim-pulse">
+ <svg height="32" class="octicon octicon-octoface" viewBox="0 0 16 16" version="1.1" width="32" aria-hidden="true"><path fill-rule="evenodd" d="M14.7 5.34c.13-.32.55-1.59-.13-3.31 0 0-1.05-.33-3.44 1.3-1-.28-2.07-.32-3.13-.32s-2.13.04-3.13.32c-2.39-1.64-3.44-1.3-3.44-1.3-.68 1.72-.26 2.99-.13 3.31C.49 6.21 0 7.33 0 8.69 0 13.84 3.33 15 7.98 15S16 13.84 16 8.69c0-1.36-.49-2.48-1.3-3.35zM8 14.02c-3.3 0-5.98-.15-5.98-3.35 0-.76.38-1.48 1.02-2.07 1.07-.98 2.9-.46 4.96-.46 2.07 0 3.88-.52 4.96.46.65.59 1.02 1.3 1.02 2.07 0 3.19-2.68 3.35-5.98 3.35zM5.49 9.01c-.66 0-1.2.8-1.2 1.78s.54 1.79 1.2 1.79c.66 0 1.2-.8 1.2-1.79s-.54-1.78-1.2-1.78zm5.02 0c-.66 0-1.2.79-1.2 1.78s.54 1.79 1.2 1.79c.66 0 1.2-.8 1.2-1.79s-.53-1.78-1.2-1.78z"/></svg>
+ </div>
+ </div>
+ </div>
+</div>
+
+ <div class="BtnGroup float-right">
+ <a href="/gilbarbara/logos/find/master"
+ class="js-pjax-capture-input btn btn-sm BtnGroup-item"
+ data-pjax
+ data-hotkey="t">
+ Find file
+ </a>
+ <clipboard-copy for="blob-path" class="btn btn-sm BtnGroup-item">
+ Copy path
+ </clipboard-copy>
+ </div>
+ <div id="blob-path" class="breadcrumb">
+ <span class="repo-root js-repo-root"><span class="js-path-segment"><a data-pjax="true" href="/gilbarbara/logos"><span>logos</span></a></span></span><span class="separator">/</span><span class="js-path-segment"><a data-pjax="true" href="/gilbarbara/logos/tree/master/logos"><span>logos</span></a></span><span class="separator">/</span><strong class="final-path">appveyor.svg</strong>
+ </div>
+ </div>
+
+
+
+ <div class="commit-tease">
+ <span class="float-right">
+ <a class="commit-tease-sha" href="/gilbarbara/logos/commit/f892a9d96fa1d68a350f988ef9b98b74b1ffc09c" data-pjax>
+ f892a9d
+ </a>
+ <relative-time datetime="2016-08-26T17:09:44Z">Aug 26, 2016</relative-time>
+ </span>
+ <div>
+ <a rel="author" data-skip-pjax="true" data-hovercard-type="user" data-hovercard-url="/hovercards?user_id=31954" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="/gilbarbara"><img class="avatar" src="https://avatars2.githubusercontent.com/u/31954?s=40&v=4" width="20" height="20" alt="@gilbarbara" /></a>
+ <a class="user-mention" rel="author" data-hovercard-type="user" data-hovercard-url="/hovercards?user_id=31954" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="/gilbarbara">gilbarbara</a>
+ <a data-pjax="true" title="7 new logos — apollo, appveyor, dependencyci, front, perf-rocks, scaphold, snupps" class="message" href="/gilbarbara/logos/commit/f892a9d96fa1d68a350f988ef9b98b74b1ffc09c">7 new logos — apollo, appveyor, dependencyci, front, perf-rocks, scap…</a>
+ </div>
+
+ <div class="commit-tease-contributors">
+
+<details class="details-reset details-overlay details-overlay-dark lh-default text-gray-dark float-left mr-2" id="blob_contributors_box">
+ <summary
+ class="btn-link"
+ aria-haspopup="dialog"
+
+
+ >
+
+ <span><strong>1</strong> contributor</span>
+ </summary>
+ <details-dialog class="Box Box--overlay d-flex flex-column anim-fade-in fast " aria-label="Users who have contributed to this file">
+ <div class="Box-header">
+ <button class="Box-btn-octicon btn-octicon float-right" type="button" aria-label="Close dialog" data-close-dialog>
+ <svg class="octicon octicon-x" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48L7.48 8z"/></svg>
+ </button>
+ <h3 class="Box-title">Users who have contributed to this file</h3>
+ </div>
+
+ <ul class="list-style-none overflow-auto">
+ <li class="Box-row">
+ <a class="link-gray-dark no-underline" href="/gilbarbara">
+ <img class="avatar mr-2" alt="" src="https://avatars2.githubusercontent.com/u/31954?s=40&v=4" width="20" height="20" />
+ gilbarbara
+</a> </li>
+ </ul>
+
+ </details-dialog>
+</details>
+
+ </div>
+ </div>
+
+
+
+
+ <div class="file ">
+
+<div class="file-header">
+
+ <div class="file-actions">
+
+ <div class="BtnGroup">
+ <a class="btn btn-sm BtnGroup-item tooltipped tooltipped tooltipped-n source "
+ href="/gilbarbara/logos/blob/master/logos/appveyor.svg?short_path=71a23a1" aria-label="Display the source blob">
+ <svg class="octicon octicon-code" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M9.5 3L8 4.5 11.5 8 8 11.5 9.5 13 14 8 9.5 3zm-5 0L0 8l4.5 5L6 11.5 2.5 8 6 4.5 4.5 3z"/></svg>
+ </a>
+ <a class="btn btn-sm BtnGroup-item tooltipped tooltipped-n rendered selected"
+ href="/gilbarbara/logos/blob/master/logos/appveyor.svg" aria-label="Display the rendered blob">
+ <svg class="octicon octicon-file" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M6 5H2V4h4v1zM2 8h7V7H2v1zm0 2h7V9H2v1zm0 2h7v-1H2v1zm10-7.5V14c0 .55-.45 1-1 1H1c-.55 0-1-.45-1-1V2c0-.55.45-1 1-1h7.5L12 4.5zM11 5L8 2H1v12h10V5z"/></svg>
+ </a>
+ </div>
+
+ <div class="BtnGroup">
+ <a id="raw-url" class="btn btn-sm BtnGroup-item" href="/gilbarbara/logos/raw/master/logos/appveyor.svg">Raw</a>
+ <a class="btn btn-sm js-update-url-with-hash BtnGroup-item" data-hotkey="b" href="/gilbarbara/logos/blame/master/logos/appveyor.svg">Blame</a>
+ <a rel="nofollow" class="btn btn-sm BtnGroup-item" href="/gilbarbara/logos/commits/master/logos/appveyor.svg">History</a>
+ </div>
+
+ <a class="btn-octicon tooltipped tooltipped-nw"
+ href="https://desktop.github.com"
+ aria-label="Open this file in GitHub Desktop"
+ data-ga-click="Repository, open with desktop, type:windows">
+ <svg class="octicon octicon-device-desktop" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M15 2H1c-.55 0-1 .45-1 1v9c0 .55.45 1 1 1h5.34c-.25.61-.86 1.39-2.34 2h8c-1.48-.61-2.09-1.39-2.34-2H15c.55 0 1-.45 1-1V3c0-.55-.45-1-1-1zm0 9H1V3h14v8z"/></svg>
+ </a>
+
+ <button type="button" class="btn-octicon disabled tooltipped tooltipped-nw"
+ aria-label="You must be signed in to make or propose changes">
+ <svg class="octicon octicon-pencil" viewBox="0 0 14 16" version="1.1" width="14" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M0 12v3h3l8-8-3-3-8 8zm3 2H1v-2h1v1h1v1zm10.3-9.3L12 6 9 3l1.3-1.3a.996.996 0 0 1 1.41 0l1.59 1.59c.39.39.39 1.02 0 1.41z"/></svg>
+ </button>
+ <button type="button" class="btn-octicon btn-octicon-danger disabled tooltipped tooltipped-nw"
+ aria-label="You must be signed in to make or propose changes">
+ <svg class="octicon octicon-trashcan" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M11 2H9c0-.55-.45-1-1-1H5c-.55 0-1 .45-1 1H2c-.55 0-1 .45-1 1v1c0 .55.45 1 1 1v9c0 .55.45 1 1 1h7c.55 0 1-.45 1-1V5c.55 0 1-.45 1-1V3c0-.55-.45-1-1-1zm-1 12H3V5h1v8h1V5h1v8h1V5h1v8h1V5h1v9zm1-10H2V3h9v1z"/></svg>
+ </button>
+ </div>
+
+ <div class="file-info">
+ 7 lines (6 sloc)
+ <span class="file-info-divider"></span>
+ 1.34 KB
+ </div>
+</div>
+
+
+
+ <div itemprop="text" class="blob-wrapper data type-svg ">
+
+ <div class="render-wrapper ">
+ <div class="render-container is-render-pending js-render-target "
+ data-identity="58e5a16e-0123-417e-8de7-89a734eec5b9"
+ data-host="https://render.githubusercontent.com"
+ data-type="svg">
+ <img class="octospinner mx-auto" alt="" src="https://github.githubassets.com/images/spinners/octocat-spinner-128.gif" width="64" height="64" />
+ <div class="render-viewer-error">Sorry, something went wrong. <a href="https://github.com/gilbarbara/logos/blob/master/logos/appveyor.svg">Reload?</a></div>
+ <div class="render-viewer-fatal">Sorry, we cannot display this file.</div>
+ <div class="render-viewer-invalid">Sorry, this file is invalid so it cannot be displayed.</div>
+ <iframe class="render-viewer " src="https://render.githubusercontent.com/view/svg?commit=b65a7dc930f6bd4b4fe8040d6961483391305078&enc_url=68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f67696c626172626172612f6c6f676f732f623635613764633933306636626434623466653830343064363936313438333339313330353037382f6c6f676f732f6170707665796f722e737667&nwo=gilbarbara%2Flogos&path=logos%2Fappveyor.svg&repository_id=37291982&repository_type=Repository#58e5a16e-0123-417e-8de7-89a734eec5b9" sandbox="allow-scripts allow-same-origin allow-top-navigation " title="File display">
+ Viewer requires iframe.
+ </iframe>
+ </div>
+ </div>
+
+ </div>
+
+ </div>
+
+
+
+ <details class="details-reset details-overlay details-overlay-dark">
+ <summary data-hotkey="l" aria-label="Jump to line"></summary>
+ <details-dialog class="Box Box--overlay d-flex flex-column anim-fade-in fast linejump" aria-label="Jump to line">
+ <!-- '"` --><!-- </textarea></xmp> --></option></form><form class="js-jump-to-line-form Box-body d-flex" action="" accept-charset="UTF-8" method="get"><input name="utf8" type="hidden" value="✓" />
+ <input class="form-control flex-auto mr-3 linejump-input js-jump-to-line-field" type="text" placeholder="Jump to line…" aria-label="Jump to line" autofocus>
+ <button type="submit" class="btn" data-close-dialog>Go</button>
+</form> </details-dialog>
+ </details>
+
+
+
+ </div>
+ <div class="modal-backdrop js-touch-events"></div>
+</div>
+
+ </div>
+ </div>
+
+ </div>
+
+
+<div class="footer container-lg px-3" role="contentinfo">
+ <div class="position-relative d-flex flex-justify-between pt-6 pb-2 mt-6 f6 text-gray border-top border-gray-light ">
+ <ul class="list-style-none d-flex flex-wrap ">
+ <li class="mr-3">© 2019 <span title="0.12743s from unicorn-776675b497-pccd9">GitHub</span>, Inc.</li>
+ <li class="mr-3"><a data-ga-click="Footer, go to terms, text:terms" href="https://github.com/site/terms">Terms</a></li>
+ <li class="mr-3"><a data-ga-click="Footer, go to privacy, text:privacy" href="https://github.com/site/privacy">Privacy</a></li>
+ <li class="mr-3"><a data-ga-click="Footer, go to security, text:security" href="https://github.com/security">Security</a></li>
+ <li class="mr-3"><a href="https://githubstatus.com/" data-ga-click="Footer, go to status, text:status">Status</a></li>
+ <li><a data-ga-click="Footer, go to help, text:help" href="https://help.github.com">Help</a></li>
+ </ul>
+
+ <a aria-label="Homepage" title="GitHub" class="footer-octicon mr-lg-4" href="https://github.com">
+ <svg height="24" class="octicon octicon-mark-github" viewBox="0 0 16 16" version="1.1" width="24" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
+</a>
+ <ul class="list-style-none d-flex flex-wrap ">
+ <li class="mr-3"><a data-ga-click="Footer, go to contact, text:contact" href="https://github.com/contact">Contact GitHub</a></li>
+ <li class="mr-3"><a href="https://github.com/pricing" data-ga-click="Footer, go to Pricing, text:Pricing">Pricing</a></li>
+ <li class="mr-3"><a href="https://developer.github.com" data-ga-click="Footer, go to api, text:api">API</a></li>
+ <li class="mr-3"><a href="https://training.github.com" data-ga-click="Footer, go to training, text:training">Training</a></li>
+ <li class="mr-3"><a href="https://github.blog" data-ga-click="Footer, go to blog, text:blog">Blog</a></li>
+ <li><a data-ga-click="Footer, go to about, text:about" href="https://github.com/about">About</a></li>
+
+ </ul>
+ </div>
+ <div class="d-flex flex-justify-center pb-6">
+ <span class="f6 text-gray-light"></span>
+ </div>
+</div>
+
+
+
+ <div id="ajax-error-message" class="ajax-error-message flash flash-error">
+ <svg class="octicon octicon-alert" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"/></svg>
+ <button type="button" class="flash-close js-ajax-error-dismiss" aria-label="Dismiss error">
+ <svg class="octicon octicon-x" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48L7.48 8z"/></svg>
+ </button>
+ You can’t perform that action at this time.
+ </div>
+
+
+ <script crossorigin="anonymous" integrity="sha512-yD4CpPY9CbGcZVRfSqvQcU1Ii3cjOOMbi8mG+41mYBoiHxYXTvxYvQmhn7mNo38sg0sH3pSSWfO76FdcoQtJbw==" type="application/javascript" src="https://github.githubassets.com/assets/unsupported-c73ee0e52399b297ab1e95df46945948.js"></script>
+ <div class="js-stale-session-flash stale-session-flash flash flash-warn flash-banner d-none">
+ <svg class="octicon octicon-alert" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"/></svg>
+ <span class="signed-in-tab-flash">You signed in with another tab or window. <a href="">Reload</a> to refresh your session.</span>
+ <span class="signed-out-tab-flash">You signed out in another tab or window. <a href="">Reload</a> to refresh your session.</span>
+ </div>
+ <template id="site-details-dialog">
+ <details class="details-reset details-overlay details-overlay-dark lh-default text-gray-dark" open>
+ <summary aria-haspopup="dialog" aria-label="Close dialog"></summary>
+ <details-dialog class="Box Box--overlay d-flex flex-column anim-fade-in fast">
+ <button class="Box-btn-octicon m-0 btn-octicon position-absolute right-0 top-0" type="button" aria-label="Close dialog" data-close-dialog>
+ <svg class="octicon octicon-x" viewBox="0 0 12 16" version="1.1" width="12" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48L7.48 8z"/></svg>
+ </button>
+ <div class="octocat-spinner my-6 js-details-dialog-spinner"></div>
+ </details-dialog>
+ </details>
+</template>
+
+ <div class="Popover js-hovercard-content position-absolute" style="display: none; outline: none;" tabindex="0">
+ <div class="Popover-message Popover-message--bottom-left Popover-message--large Box box-shadow-large" style="width:360px;">
+ </div>
+</div>
+
+<div id="hovercard-aria-description" class="sr-only">
+ Press h to open a hovercard with more details.
+</div>
+
+ <div aria-live="polite" class="js-global-screen-reader-notice sr-only"></div>
+
+ </body>
+</html>
+
diff --git a/docs/the-tools-we-use/assets/appveyor_logo.svg.png b/docs/the-tools-we-use/assets/appveyor_logo.svg.png
new file mode 100644
index 0000000000..6ca58bf338
Binary files /dev/null and b/docs/the-tools-we-use/assets/appveyor_logo.svg.png differ
diff --git a/docs/the-tools-we-use/assets/comparing-master-and-development.PNG b/docs/the-tools-we-use/assets/comparing-master-and-development.PNG
new file mode 100644
index 0000000000..d71e76586b
Binary files /dev/null and b/docs/the-tools-we-use/assets/comparing-master-and-development.PNG differ
diff --git a/docs/the-tools-we-use/assets/create pull request.PNG b/docs/the-tools-we-use/assets/create pull request.PNG
new file mode 100644
index 0000000000..9cf7520693
Binary files /dev/null and b/docs/the-tools-we-use/assets/create pull request.PNG differ
diff --git a/docs/the-tools-we-use/assets/create-pull-request.PNG b/docs/the-tools-we-use/assets/create-pull-request.PNG
new file mode 100644
index 0000000000..9cf7520693
Binary files /dev/null and b/docs/the-tools-we-use/assets/create-pull-request.PNG differ
diff --git a/docs/the-tools-we-use/assets/image (1).png b/docs/the-tools-we-use/assets/image (1).png
new file mode 100644
index 0000000000..efe3381dbd
Binary files /dev/null and b/docs/the-tools-we-use/assets/image (1).png differ
diff --git a/docs/the-tools-we-use/assets/image.png b/docs/the-tools-we-use/assets/image.png
new file mode 100644
index 0000000000..8a801f9b19
Binary files /dev/null and b/docs/the-tools-we-use/assets/image.png differ
diff --git a/docs/the-tools-we-use/assets/import (1).png b/docs/the-tools-we-use/assets/import (1).png
new file mode 100644
index 0000000000..e3013d8bbd
Binary files /dev/null and b/docs/the-tools-we-use/assets/import (1).png differ
diff --git a/docs/the-tools-we-use/assets/import.png b/docs/the-tools-we-use/assets/import.png
new file mode 100644
index 0000000000..e3013d8bbd
Binary files /dev/null and b/docs/the-tools-we-use/assets/import.png differ
diff --git a/docs/the-tools-we-use/assets/initial RAP3 screen.png b/docs/the-tools-we-use/assets/initial RAP3 screen.png
new file mode 100644
index 0000000000..cce7d5ada0
Binary files /dev/null and b/docs/the-tools-we-use/assets/initial RAP3 screen.png differ
diff --git a/docs/the-tools-we-use/assets/login.png b/docs/the-tools-we-use/assets/login.png
new file mode 100644
index 0000000000..68accf5b49
Binary files /dev/null and b/docs/the-tools-we-use/assets/login.png differ
diff --git a/docs/the-tools-we-use/assets/logo-2x-1.png b/docs/the-tools-we-use/assets/logo-2x-1.png
new file mode 100644
index 0000000000..f4518b1095
Binary files /dev/null and b/docs/the-tools-we-use/assets/logo-2x-1.png differ
diff --git a/docs/the-tools-we-use/assets/logout.png b/docs/the-tools-we-use/assets/logout.png
new file mode 100644
index 0000000000..cef8ce94dc
Binary files /dev/null and b/docs/the-tools-we-use/assets/logout.png differ
diff --git a/docs/the-tools-we-use/assets/menuNieuwScript.png b/docs/the-tools-we-use/assets/menuNieuwScript.png
new file mode 100644
index 0000000000..366bfe938c
Binary files /dev/null and b/docs/the-tools-we-use/assets/menuNieuwScript.png differ
diff --git a/docs/the-tools-we-use/assets/modify-release-title.PNG b/docs/the-tools-we-use/assets/modify-release-title.PNG
new file mode 100644
index 0000000000..c1ad17057e
Binary files /dev/null and b/docs/the-tools-we-use/assets/modify-release-title.PNG differ
diff --git a/docs/the-tools-we-use/assets/parseError.png b/docs/the-tools-we-use/assets/parseError.png
new file mode 100644
index 0000000000..98be17294a
Binary files /dev/null and b/docs/the-tools-we-use/assets/parseError.png differ
diff --git a/docs/the-tools-we-use/assets/phpMyAdmin.png b/docs/the-tools-we-use/assets/phpMyAdmin.png
new file mode 100644
index 0000000000..b315f37f89
Binary files /dev/null and b/docs/the-tools-we-use/assets/phpMyAdmin.png differ
diff --git a/docs/the-tools-we-use/assets/release-train-rap3.png b/docs/the-tools-we-use/assets/release-train-rap3.png
new file mode 100644
index 0000000000..64b2363ea7
Binary files /dev/null and b/docs/the-tools-we-use/assets/release-train-rap3.png differ
diff --git a/docs/the-tools-we-use/assets/reopen-in-container.png b/docs/the-tools-we-use/assets/reopen-in-container.png
new file mode 100644
index 0000000000..ef4801da52
Binary files /dev/null and b/docs/the-tools-we-use/assets/reopen-in-container.png differ
diff --git a/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.31.22.png b/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.31.22.png
new file mode 100644
index 0000000000..8127ef7b1f
Binary files /dev/null and b/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.31.22.png differ
diff --git a/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.36.16.png b/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.36.16.png
new file mode 100644
index 0000000000..a83f068559
Binary files /dev/null and b/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.36.16.png differ
diff --git a/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.37.47.png b/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.37.47.png
new file mode 100644
index 0000000000..93ec965e80
Binary files /dev/null and b/docs/the-tools-we-use/assets/schermafbeelding-2021-07-31-om-08.37.47.png differ
diff --git a/docs/the-tools-we-use/assets/travisci-full-color-1.png b/docs/the-tools-we-use/assets/travisci-full-color-1.png
new file mode 100644
index 0000000000..fc1b9673ae
Binary files /dev/null and b/docs/the-tools-we-use/assets/travisci-full-color-1.png differ
diff --git a/docs/the-tools-we-use/authentication-and-access-management-with-oauth.md b/docs/the-tools-we-use/authentication-and-access-management-with-oauth.md
new file mode 100644
index 0000000000..4edf93c122
--- /dev/null
+++ b/docs/the-tools-we-use/authentication-and-access-management-with-oauth.md
@@ -0,0 +1,26 @@
+# Authentication and access management with OAuth
+
+An Ampersand application may grant access to named users. We have done this before using the [open standard OAuth ](https://oauth.net)\(Open Authorization\). This allows access to specific private data on a different website, without requiring the user to hand over their credentials \(e.g. username/password\).
+
+## Setting up with Github as access provider
+
+I made a separate Github organization, RAP-OUNL, to serve as access provider for RAP4.
+
+callback URL: [http://example.com/AmpersandPrototypes/RAP4/api/v1/oauthlogin/callback/github](http://example.com/AmpersandPrototypes/RAP3/api/v1/oauthlogin/callback/github)
+
+## Experimenting from a laptop
+
+For experimentation purposes, I added the following line to `C:\Windows\System32\drivers\etc` on my Windows 7 laptop.
+
+```text
+127.0.0.1 example.com
+```
+
+Then I flushed the local name server in a command line window.
+
+```text
+C:\> ipconfig /flushdns
+```
+
+Then I brought up a browser window, to see that `example.com` is a valid URL. Now I can experiment with OUauth from the laptop, because the OAuth server can return messages to `example.com`.
+
diff --git a/docs/the-tools-we-use/automation-of-releasing-ci-cd/README.md b/docs/the-tools-we-use/automation-of-releasing-ci-cd/README.md
new file mode 100644
index 0000000000..23d8893560
--- /dev/null
+++ b/docs/the-tools-we-use/automation-of-releasing-ci-cd/README.md
@@ -0,0 +1,33 @@
+---
+description: This page describes the release train for Ampersand.
+---
+
+# Automation of releasing \(CI/CD\)
+
+### The purpose of automation.
+
+The release of Ampersand is largely automated because we want:
+
+1. to save ourselves work;
+2. to release frequently in a predictable rythm, to bring new functionality to users quickly and predictably;
+3. reliable releases, to prevent our mistakes to hit users and to avoid delays caused by the release process;
+4. reproducible releases, to allow any team members to step in when the release is due.
+
+### What we want to achieve.
+
+#### Version managment
+
+First of all, we want to be **in control** of our software. We use Git\(hub\) to do version management. We use git flow strategy. We have a master branch that holds the code of the latest stable release. Then we have a development branch that holds the latest added features and bugfixes. We want this branch to be stable too. It must be buildable at all times, and no half-on-its-way functionality should be in it. For new features or other issues, we use feature branches. These branches are work in progress. They might be buildable, or they might not. Feature branches should be used for work in progress only. This keeps the amount of branches manageable. Tags can be created for all kind of other reference purposes to specific commits.
+
+:::info
+
+To learn more about Git, head over to [this documentation](https://git-scm.com/).
+
+:::
+
+#### Automatic build & test
+
+We use [github actions](https://github.com/features/actions) to build and test the code whenever a commit is done on github. Github actions is pretty well [documented](https://docs.github.com/en/actions). Our specific code can be found in the repository at the designated directory: `.github/workflows/` .
+
+
+
diff --git a/docs/the-tools-we-use/automation-of-releasing-ci-cd/github-packages.md b/docs/the-tools-we-use/automation-of-releasing-ci-cd/github-packages.md
new file mode 100644
index 0000000000..bc09e5e6e1
--- /dev/null
+++ b/docs/the-tools-we-use/automation-of-releasing-ci-cd/github-packages.md
@@ -0,0 +1,62 @@
+# Github packages
+
+## Querying packages using Github's GraphQL API
+
+* The query below returns a list of all packages and package versions pushed to github repo of Ampersand
+* The packages api is still in development, therefore you must include a HTTP Accept header to indicate you want to use this feature
+* Make sure the right access right are set for your personal access token. Inluding read repo + read/write packages
+
+ > `POST https://api.github.com/graphql`
+
+headers: >
+
+```text
+Content-Type: application/json
+Authorization: bearer [put your personal access token here]
+Accept: application/vnd.github.packages-preview+json
+```
+
+body \(grapql query\):
+
+> ```javascript
+> {
+> "query": "query {
+> viewer { login }
+> repository(name: \"ampersand\", owner: \"ampersandtarski\") {
+> id
+> packages (first: 10) {
+> nodes {
+> id
+> name
+> versions (first: 100) {
+> nodes {
+> id version
+> }
+> }
+> }
+> }
+> }
+> }"
+> }
+> ```
+
+## Deleting specific packages
+
+**NOTE! Doesn't work with public packages, like we have**
+
+> `POST https://api.github.com/graphql`
+
+headers: >
+
+```text
+Content-Type: application/json
+Authorization: bearer [put your personal access token here]
+Accept: application/vnd.github.package-deletes-preview+json
+```
+
+body \(graphql query\) >
+
+```javascript
+{ "query" : "mutation { deletePackageVersion(input:{packageVersionId:\"[package-version-id]==\"}) { success }}" }
+```
+
diff --git a/docs/the-tools-we-use/book.json b/docs/the-tools-we-use/book.json
new file mode 100644
index 0000000000..2ff76c4e30
--- /dev/null
+++ b/docs/the-tools-we-use/book.json
@@ -0,0 +1,3 @@
+{
+ "plugins": ["mathjax"]
+}
diff --git a/docs/the-tools-we-use/building/README.md b/docs/the-tools-we-use/building/README.md
new file mode 100644
index 0000000000..8ad1051c33
--- /dev/null
+++ b/docs/the-tools-we-use/building/README.md
@@ -0,0 +1,14 @@
+---
+description: This chapter describes how and why the various items are built.
+---
+
+# Building
+
+| Item | build tool | Purpose |
+| :--- | :--- | :--- |
+| [Ampersand Compiler](haskell.md) | Stack | build a binary on MacOS or Windows |
+| [Ampersand Compiler](building-an-ampersand-compiler-as-docker-image.md) | Docker | build a Docker image for the Ampersand compiler |
+| Application | Docker | build a Docker image for an application generated by Ampersand. |
+| RAP | Docker | build a Docker image for RAP |
+| [Automated build](automated-builds.md) | Docker Cloud | explains the automated build process that produces up-to-date images on docker cloud. |
+
diff --git a/docs/the-tools-we-use/building/automated-builds.md b/docs/the-tools-we-use/building/automated-builds.md
new file mode 100644
index 0000000000..78c27bbaf0
--- /dev/null
+++ b/docs/the-tools-we-use/building/automated-builds.md
@@ -0,0 +1,16 @@
+---
+description: This page explains how Ampersand images are built automatically
+---
+
+# Automated builds
+
+We followed [docker's instruction for automated builds](https://docs.docker.com/docker-hub/builds/), to automate the workflow from committing to the [Ampersand repository on Github](https://github.com/AmpersandTarski/Ampersand) to the corresponding docker image on [Docker hub](https://hub.docker.com/r/ampersandtarski/ampersand).
+
+## Manual builds
+
+If you must do things on your own, you might want to reproduce parts of the builds.
+
+The Dockerfile for the Ampersand compiler resides in the root of the Ampersand repository. So from the command line, if you are at the root of the Ampersand repository, you can call `docker build .` to create the image. See [this page](building-an-ampersand-compiler-as-docker-image.md) for more details.
+
+The package.yaml file for the Ampersand compiler resides in the root of the Ampersand repository. So from the command line, if you are at the root of the Ampersand repository, you can call `stack install` to create the image. See [this page](haskell.md) for more details.
+
diff --git a/docs/the-tools-we-use/building/building-an-ampersand-compiler-as-docker-image.md b/docs/the-tools-we-use/building/building-an-ampersand-compiler-as-docker-image.md
new file mode 100644
index 0000000000..431a3d8817
--- /dev/null
+++ b/docs/the-tools-we-use/building/building-an-ampersand-compiler-as-docker-image.md
@@ -0,0 +1,113 @@
+---
+description: >-
+ If you need an Ampersand compiler in a Docker image, use the one on Docker
+ hub. It sits there ready for you to use. However, if you want to know how it
+ is baked, carry on reading.
+---
+
+# Baking a Docker image that contains the Ampersand Compiler
+
+## The magic
+
+To get a docker container I took the file [Dockerfile](https://github.com/AmpersandTarski/Ampersand/blob/feature/dockerize/docker/Dockerfile) and built an image called "myampersand", using the following command:
+
+```text
+docker build -t myampersand ~/Ampersand/
+```
+
+It took 45 minutes to build, but I got an image called `myampersand` in the docker repository on my laptop.
+
+To see it work, I executed the newly created image on a little file in my working directory, `hello.adl` from the command line with the following command:
+
+```text
+docker run -it -v "$(pwd)":/scripts myampersand hello.adl
+```
+
+The same command in the Windows command line is:
+
+```text
+docker run -it -v "%cd%":/scripts myampersand hello.adl
+```
+
+## Do you want to reproduce this?
+
+The Ampersand repository contains a file, [Dockerfile](https://github.com/AmpersandTarski/Ampersand/blob/development/Dockerfile), that contains a recipe for building an Ampersand compiler and put it in your Ampersand repository. You need the following ingredients to run it:
+
+1. A machine to run docker, for building your docker image with. I ran it on my MacBook.
+2. Docker, which you need [installed on your machine](https://docs.docker.com/install/).
+3. Docker needs least 5G of memory to build Ampersand, which is more than the standard 2G. I used [this instruction](https://stackoverflow.com/questions/44533319/how-to-assign-more-memory-to-docker-container/44533437#44533437) to increase Docker's memory on my Macbook.
+
+To run it, I cloned the Ampersand repository, into `~/Ampersand/`, and built the image with:
+
+```text
+docker build -t myampersand ~/Ampersand/
+```
+
+It runs on my Mac for over half an hour, so some patience is required. If you don't have that patience, consider using the image [ampersandtarski/ampersand](https://hub.docker.com/r/ampersandtarski/ampersand) from docker hub. It was built for your convenience.
+
+The resulting docker image sits in the docker repository on you laptop \(placed there when docker was installed\).
+
+## So which steps does Docker take?
+
+If you want a slightly different image \(for reasons of your own\), you may want to repeat this process yourself. For that purpose, let us walk through the different steps described in Dockerfile.
+
+Let us discuss the steps one-by-one. \(Please check the [Dockerfile](https://github.com/AmpersandTarski/Ampersand/blob/feature/dockerize/docker/Dockerfile), just in case it is inconsistent with this documentation.\) All of these steps happen automatically, as they are in the docker file.
+
+The first statement states that the compiler is built on a well-defined Haskell image.
+
+```text
+FROM haskell:8.6.5 AS buildstage
+```
+
+This building stage is called buildstage because we want to use a [2-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) to obtain a small Ampersand image without excess-software.
+
+We decide to work in the build-container from a working directory called `/Ampersand`.
+
+```text
+WORKDIR /Ampersand/
+```
+
+Normally we want to generate Ampersand from the source code on GitHub. For this purpose we clone the Ampersand-repository into the \(working directory in the\) build environment.
+
+```text
+RUN git clone https://github.com/AmpersandTarski/Ampersand/ .
+```
+
+In this case I wanted to build from a specific feature, so I checked it out.
+
+```text
+RUN git checkout feature/Archimate3
+```
+
+Now everything is in place to compile Ampersand. Running `stack install` results in a full-fledged Ampersand compiler in `/root/.local/bin`. Mind you, this takes a while...
+
+```text
+RUN stack install
+```
+
+If we were to stop here, we get an image larger than 4GB. We can do better than that by starting over with a clean machine. So we introduce a second `FROM`-line in the Dockerfile which starts with a clean slate. We use an empty ubuntu machine \(form some reason yet unknown, the smaller alpine image doesn't work\)
+
+```text
+FROM ubuntu:16.04
+```
+
+Now we must copy the ampersand executable to `/bin`, from where we can run it as though it were a normal ubuntu-command. It is the only software we will copy into this image. \(Haskell and the intermediate files are all absent\). This results in an image that is slightly over 220MB.
+
+```text
+COPY --from=buildstage /root/.local/bin/ampersand /bin/
+```
+
+When compiling, we will work in a directory called scripts. When using this container, we will volume-map this directory to the actual working directory that contains the ampersand-files we want to compile.
+
+```text
+WORKDIR /scripts
+VOLUME ["/scripts"]
+```
+
+The program to be called when running the container is of course `ampersand` \(residing in `/bin/`\). If called without arguments it will use `--verbose`.
+
+```text
+ENTRYPOINT ["/bin/ampersand"]
+CMD ["--verbose"]
+```
+
diff --git a/docs/the-tools-we-use/building/haskell.md b/docs/the-tools-we-use/building/haskell.md
new file mode 100644
index 0000000000..0454fd1074
--- /dev/null
+++ b/docs/the-tools-we-use/building/haskell.md
@@ -0,0 +1,25 @@
+---
+description: >-
+ To build your own Ampersand compiler is something to avoid as a user. As a
+ developer, however, you may have reasons to do this yourself. For instance to
+ verify what happens in older versions.
+---
+
+# Building an Ampersand Compiler with Stack
+
+The Ampersand compiler is a Haskell program built with [stack](https://haskellstack.org/). Stack is a build tool for Haskell projects such as Ampersand. We have automated the building process \(using stack\) for the following purposes:
+
+1. to prevent mistakes such as dependency conflicts inside and between Haskell packages, for an uninterrupted compilation process \(robust building\);
+2. to generate ampersand compilers for different platforms \(platform independence\);
+3. to provide a reproducible and reliable build process to developers with diverse development tools, operating systems, and working environments \(uniform building\);
+4. to allow for generating images for docker containers \(containerization\);
+5. to accellerate the build process to increase the release frequency of Ampersand.
+
+## Installation
+
+[Haskell](https://www.haskell.org/) comes as part of [Stack](http://haskellstack.org), so there is no need to install Haskell separately.
+
+The [instructions to install Stack](http://haskellstack.org) are pretty clear for the various platforms. Make sure you read the part about the STACK\_ROOT environment variable.
+
+To compile Ampersand you need a file [package.yaml](https://github.com/AmpersandTarski/Ampersand/blob/development/package.yaml), which sits in the Ampersand repository. Fetch it and put it in you working directory. From the command-line, call command `stack install` and after a while \(go get coffee!\) your ampersand compiler exists! NB: If you want to build Rieks' preprocessor as well, the magic spell is `stack install --flag ampersand:buildAll`
+
diff --git a/docs/the-tools-we-use/building/testing-with-docker-on-your-own-laptop.md b/docs/the-tools-we-use/building/testing-with-docker-on-your-own-laptop.md
new file mode 100644
index 0000000000..1cbdabaed0
--- /dev/null
+++ b/docs/the-tools-we-use/building/testing-with-docker-on-your-own-laptop.md
@@ -0,0 +1,62 @@
+---
+description: >-
+ If you want to test your application on your own laptop, you need to configure
+ localhost to let it behave like a regular top-level domain.
+---
+
+# Testing with Docker on your own laptop
+
+## Requirement
+
+The proper use of Docker ensures that your application will run on any location on the internet. Yet, when testing your application on your laptop, you may discover that your laptop is not configured as a domain on the internet. To run any Ampersand application locally without changes, your laptop must behave like an ordinary top-level domain: `localhost`. Your computer must believe that `localhost` is like `com`, or `edu`, or `nl`. All requests from your browser(s) to `localhost` must be routed to IP-address `127.0.0.1`, which is your laptop.
+
+## The desired result
+
+:::tip
+
+When the following experiments are successful on your computer, you may consider this requirement to be fulfilled
+
+:::
+
+First demonstrate that an arbitrary internet domain (here: `nu.nl`) is visible.
+
+`> ping -c 1 nu.nl`\
+`PING nu.nl (99.86.122.115): 56 data bytes 64 bytes from 99.86.122.115: icmp_seq=0 ttl=232 time=24.367 ms`\
+`--- nu.nl ping statistics --- 1 packets transmitted, 1 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 24.367/24.367/24.367/0.000 ms`
+
+Now demonstrate that `localhost` is routed to IP-address `127.0.0.1`.
+
+`> ping -c 1 localhost`\
+`PING localhost (127.0.0.1): 56 data bytes 64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.040 ms`\
+`--- localhost ping statistics --- 1 packets transmitted, 1 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 0.040/0.040/0.040/0.000 ms`
+
+Then demonstrate that an arbitrary subdomain of `localhost` is routed to IP-address `127.0.0.1`.
+
+`> ping -c 1 rap.localhost`\
+`PING rap.localhost (127.0.0.1): 56 data bytes 64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.029 ms`\
+`--- rap.localhost ping statistics --- 1 packets transmitted, 1 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 0.029/0.029/0.029/0.000 ms`
+
+Finally, show that this works recursively on an arbitrary sub-subdomain.
+
+`> ping -c 1 foo.rap.localhost`\
+`PING foo.rap.localhost (127.0.0.1): 56 data bytes 64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.032 ms`\
+`--- foo.rap.localhost ping statistics --- 1 packets transmitted, 1 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 0.032/0.032/0.032/0.000 ms`
+
+## Complications
+
+So why should this NOT work?
+
+1. Your machine might not be connected to the internet. And if it is connected, it needs access to a domain name server to find locations on the internet. For most laptops this is the case, so you have no problems here. Some corporate laptops are connected only to the local corporate network. This means that you cannot let your application communicate with the outside world, or you have to organize that your laptop gains access (e.g. through a proxy).
+2. You cannot run your application locally if `localhost` is not configured. On some laptops there is a file called `hosts` or `.hosts`, which contains the redirection from `localhost` to IP-address `127.0.0.1`. However, this redirection does not cater for subdomains. Consider this to partially fulfill the requirement, which is sufficient if your application works without subdomains.
+3. If your application works with subdomains, `localhost` must behave like a top-level domain. For this purpose you must install and configure a domain name server on your laptop (which is typically not there).
+
+## Solutions
+
+- Turn to [http://passingcuriosity.com/2013/dnsmasq-dev-osx/](http://passingcuriosity.com/2013/dnsmasq-dev-osx/) to install a local DNS-server on your Macbook.
+- Turn to ??? to install a local DNS-server on your Windows laptop.
+- Turn to [https://support.microsoft.com/nl-nl/help/972034/how-to-reset-the-hosts-file-back-to-the-default](https://support.microsoft.com/nl-nl/help/972034/how-to-reset-the-hosts-file-back-to-the-default) for setting the hosts-file on your Windows laptop. (Don't do this if you are installing a domain name server)
+- Turn to [https://www.techjunkie.com/edit-hosts-file-mac-os-x/](https://www.techjunkie.com/edit-hosts-file-mac-os-x/) for setting the hosts-file on your Macbook. (Don't do this if you are installing a domain name server)
+
+## Workarounds
+
+If you cannot get your laptop configured, you might test your application on a separate test-server that runs Linux.
diff --git a/docs/the-tools-we-use/create pull request.PNG b/docs/the-tools-we-use/create pull request.PNG
new file mode 100644
index 0000000000..e181216780
Binary files /dev/null and b/docs/the-tools-we-use/create pull request.PNG differ
diff --git a/docs/the-tools-we-use/deploying-rap3-with-azure.md b/docs/the-tools-we-use/deploying-rap3-with-azure.md
new file mode 100644
index 0000000000..d6ceb4ae36
--- /dev/null
+++ b/docs/the-tools-we-use/deploying-rap3-with-azure.md
@@ -0,0 +1,391 @@
+
+---
+
+# Ampersand in Ordina's cloud
+
+In early 2017 the need arose for an Ampersand implementation in Ordina's cloud, to let young professionals get acquainted with Ampersand. We chose to implement RAP3 in Azure, because Ordina has an Azure subscription. RAP3 is the same environment that our students use at the Open Universiteit, so the maintainance of RAP3 can be reused for both target audiences.
+
+This chapter is an account of the installation process. It is an example for those who want to deploy Ampersand by hand.
+I suppose this is useless, because we can now deploy Ampersand automatically, using docker. But I cannot exclude there are reasons for doing this.
+
+1. It documents the installation we made for Ordina.
+ We want maintenance of RAP3 to be transferrable to other persons, so we need to document the choices made and the reasons for making them.
+
+2. It contains all information needed to make a deployment script for automated deployment.
+ We want to automate deployment, so that RAP3 will always be up to date with the most recent stable release of Ampersand.
+
+Each step in the installation process gets a separate section in this text. It is not necessary to do them in the given order.dir
+
+## 1. Setting up the virtual machine
+
+I needed an Azure account to enter the Azure portal and install a server for Ampersand. I got my account from Ordina, using the Azure subscription named 'Ordina TC - RT O Pega - Learning'. Azure offers preconfigured installations to kick-start a virtual machine. I picked LAMP by Bitnami.
+
+The following settings were \(or will be\) made:
+
+| | |
+| :--- | :--- |
+| server name | Wolfram |
+| type VM-disk | HDD |
+| OS | Ubuntu 14.04.5 |
+| configuration | Bitnami LAMP 5.6.27-0 |
+| documentation | [https://docs.bitnami.com/azure/infrastructure/lamp](https://docs.bitnami.com/azure/infrastructure/lamp) |
+| Admin user name | ampersandadmin |
+| verification type | password \(Stef Joosten knows the password\) |
+| Resource group \(in Azure\) | Ampersand |
+| location \(in Azure\) | Western Europe |
+| Size | 4 core, 8 GB, 8 disks, Max. IOP's 8x500 |
+| Inbound port: HTTP | TCP/80 |
+| Inbound port: HTTPS | TCP/443 |
+| Inbound port: SSH | TCP/22 |
+| Inbound port: SFTP | TCP/22 |
+| Public IP-adres | 52.174.4.78 |
+| PHP version \(RAP3 requires PHP version 5.6 or higher\) | 5.6.27 |
+| `{APPDIR}`= the directory into which the RAP3 files will be deployed | /home/bitnami/htdocs |
+| `{APPACC}`= the account under which the RAP3 application will run \(the apache account, i.e. ${APACHE\_RUN\_USER} c.q. ${APACHE\_RUN\_GROUP} as defined in apache2.conf\) | daemon \(this name is set in /opt/bitnami/apache2/conf/original/httpd.conf\) |
+| `{APPHOST}` = the URI of the machine that hosts the RAP3 application \(e.g. 'mydomain.org', or 'rap3.mydomain.org'\) | |
+| `{APPPORT}` = the port at which the Apache server will be listening | 80 |
+| `{APPURI}` = the URI at which the RAP3 application will be accessible for browsers \(e.g. 'mydomain.org/RAP3', or 'RAP3.mydomain.org'\) | |
+| `{APPURL}` = the full name for calling the application \(e.g. [https://mydomain.org:8080/RAP3](https://mydomain.org:8080/spreg)', or [https://RAP3.mydomain.org\](https://RAP3.mydomain.org%29\) | |
+
+I have been able to access this machine through SSH, using the Admin user name and password. I have verified the PHP-version by using the command `php --version`. In the sequel, I will refer to this machine as "the server".
+
+TODO: make sure that `{APPHOST}` can be found by DNS.
+
+I have verified that that any applicable firewalls allow traffic on port 80 `{APPPORT}` by browsing from outside the network to 52.174.4.78 \(the public IP-address\).
+
+* if you want to use HTTPS, then ensure you install a valid server certificate \(e.g. through [https://letsencrypt.org/\](https://letsencrypt.org/%29\)
+
+## 2. Getting MySQL and phpMyAdmin to work
+
+To run RAP3 requires Apache and MySQL. Both are already installed on the server. However, you need the database administrator password to set it up for Ampersand. This step requires a server, so you must have finished section 1 successfully.
+
+To get into phpMyAdmin can only be done in localhost. This requires an SSH-tunnel into the server. The instruction is found on [https://docs.bitnami.com/azure/components/phpmyadmin](https://docs.bitnami.com/azure/components/phpmyadmin). I got it done using PuTTY as my SSH-client. Upon success, you can log in to phpMyAdmin in your browser using [http://127.0.0.1:8888/phpmyadmin](http://127.0.0.1:8888/phpmyadmin) \(case sensitive!\)
+
+Instructions on how to find the initial password for phpMyAdmin are found on [https://docs.bitnami.com/azure/faq/\#find\_credentials](https://docs.bitnami.com/azure/faq/#find_credentials). Since Bitnami-documentation on the web describes different ways to obtain the phpMyAdmin root password and only one of them works, I had a hard time getting the right password. I found it in the diagnostic data for startup, as described in the abovementioned link. When installing the virtual machine, DO NOT switch off the diagnostics for startup, because you will not get the log that contains the root-password.
+
+After logging into phpMyAdmin as root, I created a user called 'ampersand' with password 'ampersand' and host 'localhost', in compliance with the defaults used in the Ampersand compiler. I have issued limited authorizations:
+
+
+
+## 3. Uploading and running RAP3
+
+To run RAP3, the web-application must be installed on `/home/bitnami/htdocs`. This step requires sections 1 and 2 to be finished successfully. It also requires you to have a complete RAP3 web-application available for uploading to the server. If you don't have that web-application, you need to build it. Upon completion of step 8 you will have built that web-application by yourself.
+
+To upload RAP3, I followed the instructions on [https://docs.bitnami.com/azure/faq/\#how-to-upload-files-to-the-server-with-sftp](https://docs.bitnami.com/azure/faq/#how-to-upload-files-to-the-server-with-sftp) to upload the RAP3 web-application from my laptop onto the server. I put it on /home/bitnami/htdocs, which is the location of web-applications on this particular configuration. \(On vanilla Linux this would be on /var/www, I guess\). This screenshot shows the situation after the transfer:
+
+To allow the computer to upload files and write logs if needed, you must make `daemon` the owner of these files, because that user represents the Apache server.
+
+`sudo chown -R daemon /opt/bitnami/apache2/htdocs/RAP3/`
+
+Remark: This is not the way to go. The best practice is to tell Apache2 to behave as ampersandadmin. That way, in case of problems Apache can only "destroy" RAP3-stuff, rather than wreck the entire system because he is "daemon".
+
+You can test whether this is successful by browsing to `52.174.4.78/RAP3/`
+
+It should show:
+
+
+
+Because the Apache server needs to write files and create directories, it is necessary that it has a shell. I checked this in the file `/etc/passwd`. This file contains a line that starts with `daemon`, which is the user of the Apache server.
+
+daemon:x:1:1:daemon:/usr/sbin:/bin/bash
+
+If the last part of that line reads`/bin/bash`, you know that Apache can execute shell commands. \(I discovered this while solving a Slim Application Error, saying that `mkdir()`fails, which was caused by Apache not having a shell at its disposal.\)
+
+Now you are done.
+
+If you need to restart the apache server for whatever reason, here is the command:
+
+`sudo /opt/bitnami/ctlscript.sh restart apache`
+
+If there are problems, check the Apache server:
+
+* Make sure that {APPACC} can read all files in {APPDIR}.
+
+* Make sure that {APPACC} has write permissions \(on all files\) in the directory {APPDIR}/Log.
+
+* If needed, edit Apache's config.ini so that:
+
+ a\) it listens at {APPPORT}
+
+ b\) users that call {APPURL} will be served {APPDIR}/index.php
+
+ c\) Apache's .htaccess files are processed within {APPDIR} and its subdirectories.
+
+ \(see e.g. [https://help.ubuntu.com/community/EnablingUseOfApacheHtaccessFiles\](https://help.ubuntu.com/community/EnablingUseOfApacheHtaccessFiles%29\)
+
+ \`AllowOverride All\` should be set in the <Directory /> section, for example \(the directory statement must apply to at least {APPDIR}\):
+
+ <Directory /var/www/>
+
+ ```
+ Options Indexes FollowSymLinks
+
+ AllowOverride All
+
+ Require all granted
+ ```
+
+ </Directory>
+
+* enable \`mod-rewrite\` extension \(see [http://askubuntu.com/questions/422027/mod-rewrite-is-enabled-but-not-working\](http://askubuntu.com/questions/422027/mod-rewrite-is-enabled-but-not-working%29\)
+
+ * you can check if modules are enabled with cmd: apache2ctl -M. You should then find that the \`rewrite\_module\` is listed.
+
+* ensure that the following extensions are enabled: curl, mysqli \(you might be able to check that by browsing to {APPURL}/phpinfo.php\).
+
+## 4. Filling and updating the Git repository with Ampersand files and Ampersand models
+
+To build an Ampersand-compiler, we need the Ampersand source files, which reside in a GitHub repository. We can download these source files on a fresh server, so this step merely requires section 1 to be finished successfully. The RAP3 source files reside in a GitHub repository as well, so we'll just clone both repositories into the server.
+
+Git comes preconfigured in Bitnami's LAMP configuration.
+
+### First time: make Git repositories
+
+I have used Git on the command line to get the Ampersand source code and the Ampersand model repository cloned onto the server.
+
+I have created `/home/ampersandadmin/git` for storing the local clones. Here is what I did:
+
+`mkdir ~/git`
+
+`cd ~/git`
+
+`git clone https://github.com/AmpersandTarski/Ampersand`
+
+`git clone https://github.com/AmpersandTarski/Ampersand-models`
+
+Now you are done. The directory `/home/ampersandadmin/git/Ampersand` contains the source code of the Ampersand compiler. The directory `/home/ampersandadmin/git/Ampersand-models` contains the source code of the Ampersand models.
+
+To verify that the Ampersand clone has succeeded and that you are in the development branch, navigate to `~/git/Ampersand` and ask for the Git status:
+
+`bitnami@Wolfram:~/git/Ampersand$ git status`
+
+`On branch development`
+
+`Your branch is up-to-date with 'origin/development'.`
+
+`nothing to commit, working directory clean`
+
+You can do the same in the `Ampersand-models` directory. There you must verify that you are in the master branch:
+
+`bitnami@Wolfram:~/git/Ampersand$ cd ../Ampersand-models/`
+
+`bitnami@Wolfram:~/git/Ampersand-models$ git status`
+
+`On branch master`
+
+`Your branch is up-to-date with 'origin/master'.`
+
+`nothing to commit, working directory clean`
+
+### Subsequent use: update Git repositories
+
+To update RAP3 to a new version, I have pulled the sources from the Github repository into the git-repository on Wolfram:
+
+```
+cd ~/git/Ampersand-models/
+git pull
+```
+
+This works, because a pull action does a fetch automatically. To update the Ampersand compiler to to a new version, I have pulled the sources from the Github repository into the git-repository on Wolfram:
+
+```
+cd ~/git/Ampersand/
+git pull
+```
+
+## 5. Installing Haskell
+
+In order to build an Ampersand-compiler, we need a Haskell installation. This can be done on a clean machine, so this step merely requires section 1 to be finished successfully.
+
+I have used Haskell stack for installing Haskell. First I installed `stack` by following the instructions on the internet for a generic Linux installation:
+
+`bitnami@Wolfram:~$ sudo apt-get update`
+
+`bitnami@Wolfram:~$ curl -sSL https://get.haskellstack.org/ | sh`
+
+Stack works. It is installed to `/usr/local/bin/stack`.
+
+Stack gives a warning about the PATH:
+
+`WARNING: '/home/ampersandadmin/.local/bin' is not on your PATH.`
+
+`For best results, please add it to the beginning of PATH in your profile.`
+
+Haskell puts the binaries it produces on `~/.local/bin/`. For this reason I have added this directory to the `$PATH` variable by changing the file `~/.profile`. In this file I edited:
+
+`# set PATH so it includes user's private bin if it exists`
+
+`if [ -d "$HOME/.local/bin" ] ; then`
+
+`PATH="$HOME/.local/bin:$PATH"`
+
+`fi`
+
+## 6. Creating an Ampersand-compiler
+
+To generate RAP3 we need an Ampersand-compiler. The RAP3 user will also use that compiler. For both reasons, we need a working Ampersand compiler on the server. This step requires sections 4 and 5 to be finished successfully.
+
+Having the source code of the Ampersand-compiler on the system, I created an executable by running `stack install`. Here is what I did:
+
+`cd ~/git/Ampersand`
+
+`stack setup`
+
+`stack install`
+
+A 1-core machine with 1.75GB memory has been shown too small to build the Ampersand-compiler. In that case, stack install does not show any progress. It got stuck without any hints about what is wrong. It did succeed on a 4-core 8GB configuration \(A4\).
+
+## 7. Installing LaTeX and GraphViz
+
+When the RAP3-user generates documentation, RAP3 will call on pdflatex, neato and dot. For this purpose we must install LaTeX and GraphViz. This can be done on a fresh server, so this step only requires section 1 to be finished successfully.
+
+For generating pictures, Ampersand needs the commands `dot` and `neato`. For that purpose I installed:
+
+```
+bitnami@Wolfram:~$ sudo apt-get install graphviz
+```
+
+That worked.
+
+As RAP3 lets the user generate documentation, Ampersand needs the command `pdflatex` . For that purpose I followed the instructions on `https://www.tug.org/texlive/quickinstall.html`.
+
+Here is what I did to install texlive:
+
+1. I decided to [Install TeX Live over the Internet](https://www.tug.org/texlive/acquire-netinstall.html).
+2. I downloaded [install-tl-unx.tar.gz](http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz) to my home directory `/home/ampersandadmin`. This gave me the archive file.
+3. I unpacked the archive saying `tar -zxvf install-tl-unx.tar.gz`. This resulted in a directory `install-tl-20170411`.
+4. Then I changed to the new directory by saying: `cd install-tl-20170411`.
+5. I then ran `./install-tl`. \(Somehow it didn't work without ./ up front\).
+6. In install-tl, I selected options `abcfgkvwXIKPS` \(by running command `C`\) to get a not-too-large installation that does everything Ampersand needs. After selection I returned to the main menu by command `R`. By the way, this can be done using a profile file, which is useful for unattended installation.
+7. Then I ran the installer by running command I. That took a while \(about an hour or so\).
+8. I updated the file `/home/ampersandadmin/.profile` to prepend `"/usr/local/texlive/2016/bin/x86_64-linux"` to the PATH, so that the shell can find the required binaries.
+9. I ran a test to see whether all packages for TeX Live are present. They weren't. When running the test, pdflatex provides the name of a missing package, e.g. "``! LaTeX Error: File `glossaries.sty' not found.``" I used `tlmgr install glossaries` to install the missing package. I did that for each missing package.
+10. The directories used by TeX Live are:
+
+`TEXDIR (the main TeX directory):`
+
+`/usr/local/texlive/2016`
+
+`TEXMFLOCAL (directory for site-wide local files):`
+
+`/usr/local/texlive/texmf-local`
+
+`TEXMFSYSVAR (directory for variable and automatically generated data):`
+
+`/usr/local/texlive/2016/texmf-var`
+
+`TEXMFSYSCONFIG (directory for local config):`
+
+`/usr/local/texlive/2016/texmf-config`
+
+`TEXMFVAR (personal directory for variable and automatically generated data):`
+
+`~/.texlive2016/texmf-var`
+
+`TEXMFCONFIG (personal directory for local config):`
+
+`~/.texlive2016/texmf-config`
+
+`TEXMFHOME (directory for user-specific files):`
+
+`~/texmf`
+
+The easier way seems to be:
+
+`bitnami@Wolfram:~$ sudo apt-get install texlive`
+
+However, that did not work. On internet, `apt-get install texlive`is discouraged because it results in outdated latex stuff.
+
+## 8. Installing SmartGit \(a nice-to-have\)
+
+For looking into the local Git repository, it is nice to have a Git-client installed. This step requires section 1 to be finished successfully.
+
+When updates of Ampersand are being deployed, this is done via GitHub. For this reason it is convenient to have a Git-client on this machine. Sourcetree, however, does not work on Linux. So I installed Smartgit:
+
+```
+bitnami@Wolfram:~$ sudo add-apt-repository ppa:eugenesan/ppa
+
+bitnami@Wolfram:~$ sudo apt-get update
+
+bitnami@Wolfram:~$ sudo apt-get install smartgit
+```
+
+I have not yet figured out how to run Smartgit. I presume to have to make a graphical terminal tunnel of some sort to run it.
+
+## 9. Local Settings
+
+To inspect and change the local settings, you need the file `localsettings.php` on directory `~/git/Ampersand-models/RAP3/include`. This step requires section 4 to be finished successfully. This file contains comments that guide you to use the correct settings in a development situation and in a production situation. Read the file and follow the instructions it contains, especially when making the transition from development to production.
+
+Logging can be switched on and off \(or tuned\) in your `localsettings.php` file.
+
+I have made a file called `localSettingsAzure.php`, to use for copying the right settings just after RAP3 has been updated from GitHub. The `localSettings.php` in GitHUb is of course not the one needed in Wolfram.
+
+## 10. Generating the RAP3 application
+
+To generate the code of the RAP3 web-application, you need to run the Ampersand compiler on the RAP3 source code. So, this step requires sections 4 and 6 to be finished successfully.
+
+It requires to execute the following commands:
+
+```
+ cd ~/git/Ampersand-models/
+git pull
+cd ~/git/Ampersand-models/RAP3/
+sudo chown -R bitnami /home/bitnami/htdocs/RAP3
+ampersand --meta-tables --add-semantic-metamodel -p/home/bitnami/htdocs/RAP3 RAP3.adl --verbose
+sudo chown -R bitnami /home/bitnami/htdocs/RAP3
+sudo chmod -R g+w /home/bitnami/htdocs/RAP3
+sudo cp ./include/localSettingsAzure.php /home/bitnami/htdocs/RAP3/localSettings.php
+```
+
+Generating RAP3 takes a while. If everything works out, the compiler terminates with the message: "Finished processing your model." Whenever I want to monitor progress, I have appended `--verbose` to the `ampersand` command, to get information about intermediate results. I used the `chgrp` and `chmod` commands to allow the Apache server write access to the RAP3 directory. Generating everything first to a new directory, RAP, keeps the downtime between updates low for the user. Before compiling RAP3, I checked the version and the current branch of the RAP3 source code:
+
+```
+cd ~/git/Ampersand-models/
+git status
+```
+
+If, for whatever reason, you want to delete earlier versions of the deployed RAP3-code, use this command:
+
+`sudo rm -rfd /home/bitnami/htdocs/RAP3`
+
+## 11. Last minute changes before going to production
+
+1. In the source code of RAP3, in the file SIAM\_importer.adl:
+ 1. disable "RAP3\_LoginForDevelopment.ifc", to prevent users from seeing
+ 2. enable "RAP3\_LoginForProduction.ifc"
+ 3. disable "../SIAM/SIAM\_AutoLoginAccount.adl"
+2. Edit the file `/home/ampersandadmin/git/RAP3/include/localSettingsAzure.php` and follow instructions in it. Make sure to copy it to `/home/bitnami/htdocs/RAP3/localSettings.php` before going live.
+
+## 12. Security measures
+
+The following measures have to be taken. Currently, they are not in effect.
+
+1. SSH configuration: prevent that outside users log in as daemon \(nor as root\) \(see for example [http://serverfault.com/questions/285800/how-to-disable-ssh-login-with-password-for-some-users\](http://serverfault.com/questions/285800/how-to-disable-ssh-login-with-password-for-some-users%29\)
+2. Apache: see [https://httpd.apache.org/docs/trunk/misc/security\_tips.html](https://httpd.apache.org/docs/trunk/misc/security_tips.html)
+3. HTTPS-cookies need a flag "Secure", "HHTP-only", and "Samesite". This needs to be addressed in the application code; not in the deployment.
+
+## 13. Troubleshooting
+
+### 13.1 When reinstalling the database ...
+
+A symptom of installation problems with the database is excessive waiting for a reponse, while "Hello, world!" is in the browser screen. It does take a while, because all rules must be checked. However, anything over 10 minutes is excessive.
+
+If the browser shows messages in this process, check whether a database exists in the first place. \(See step 2 for instructions\). If there is no database, check the file `/home/bitnami/htdocs/RAP/localSettings.php`
+
+Check the database credentials \(`dbUser`, `dbHost`, `dbPassword`\) are set to the correct values in the local settings. Do not set `dbName`. Make sure that `Config::set('productionEnv', 'global', false)` is set to enable reinstallation of the database.
+Be sure to set it back to `true` after a new database is made.
+
+### 31.2 Deadlock on all signals table
+
+At some point in time, while Stef and Han were accessing RAP3 in different sessions, we got a timeout \(See [this issue](https://github.com/AmpersandTarski/Ampersand/issues/662)\). While unsure what the exact problem is, we guessed that the all\_sessions table could cause this problem.
+
+After googleing around, I decided that it might be a good idea to increase the timeout value. So I added the following line into the file /opt/bitnami/mysql/my.cnf :
+
+> innodb\_lock\_wait\_timeout=600
+
+Also, because we do not know what is going on, I decided to enable the logging of deadlocks:
+
+> innodb print all deadlocks = ON
+
+
+
diff --git a/docs/the-tools-we-use/deploying-rap3-with-azure/deploying-rap3-with-azure-on-windows-server.md b/docs/the-tools-we-use/deploying-rap3-with-azure/deploying-rap3-with-azure-on-windows-server.md
new file mode 100644
index 0000000000..51ec168975
--- /dev/null
+++ b/docs/the-tools-we-use/deploying-rap3-with-azure/deploying-rap3-with-azure-on-windows-server.md
@@ -0,0 +1,71 @@
+# Deploying on a windows server machine \(Azure cloud\)
+
+In order to obtain a working machine with RAP3, we had difficulties getting everything to work on an Ubuntu machine. This is probably because of a lack of knowledge on our side about that infrastructure.
+
+Because of these difficulties, we decided to install everything on a Windows server. This is a log of what we did.
+
+## 1 Setting up the virtual machine
+
+Resourcegroep\([wijzigen](https://portal.azure.com/)\)
+
+[Ampersand](https://portal.azure.com/)
+
+Computernaam
+
+Renium
+
+Besturingssysteem
+
+Windows
+
+Grootte
+
+Standard DS2 versie 2 \(2 kernen, 7 GB geheugen\)
+
+Openbaar IP-adres
+
+[52.174.32.40](https://portal.azure.com/)
+
+Virtueel netwerk/subnet
+
+[Ampersand-vnet/default](https://portal.azure.com/)
+
+## 2 Getting the required software
+
+Once the VM has been launched, [connect](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/connect-logon "How to connect to an azure VM") to it. The following software was installed, using default settings, unless stated otherwise:
+
+1. Google Chrome
+2. [Git](https://git-scm.com/download/) \(version 2.12.2.2 - 64-bit\)
+3. [Xampp](https://www.apachefriends.org/download.html) \(version 7.0.15 / PHP 7.0.15\)
+4. [The Haskell Tool Stack](https://docs.haskellstack.org/en/stable/README/)
+5. [graphviz](http://www.graphviz.org/Download_windows.php)
+6. [MiKTeX](https://miktex.org/download) \(all defaults, except choose to install missing packages on-the-fly: Yes\)
+7. [Composer](https://getcomposer.org/doc/00-intro.md#installation-windows)
+
+## 3 Configuring
+
+Now all the software is in place, some of it needs configuration. This is what I did:
+
+| What | Why | How I did it |
+| :--- | :--- | :--- |
+| We need a place to store all Git repo's | All repo's are nicely together | Create directory **c:\git** |
+| Clone the ampersand repo | So we can build ampersand executable | git clone [https://github.com/AmpersandTarski/Ampersand.git](https://github.com/AmpersandTarski/Ampersand.git) |
+| Clone the ampersand-models repo | So we have the models at hand | git clone [https://github.com/AmpersandTarski/Ampersand-models.git](https://github.com/AmpersandTarski/Ampersand-models.git) |
+| Setup stack for ampersand repo | we need stack to be able to generate ampersand. It will put GHC in place and other stuff. | in c:\git\ampersand say 'stack setup' |
+| Restart the shell | because MSYS2 says so! | restart the shell |
+| Build ampersand.exe | That is what we need to run RAP3 | in c:\git\ampersand say 'stack install' |
+| Let apache listen at port 8088 | Use a non-standard port, so it can be configured with tunneling | Go to the xampp control panel, choose config in the Apache row. httpd.conf wil open in notepad. Edit the listen port number. Also click the config button at the upper right corner of the xampp control panel. Then click Service and Port Settings. Edit the Apache Main Port. Also check the Autostart of modules: Apache and MySQL. Stop and start Apache \(from the xampp control panel\) |
+| Build RAP3 application | | goto RAP3 directory; say: ampersand.exe --meta-tables --add-semantic-metamodel --verbose -pC:\xampp\htdocs\RAP3 RAP3.adl |
+| Putting Graphviz into your path | So ampersand can use dot and neato executables to build graphics | The path to add is C:\Program Files \(x86\)\Graphviz2.38\bin |
+| create a user for ampersand in mysql | So RAP3 can access mysql | Use phpmyadmin to do this. |
+
+Changes to Localsettings.php
+
+* Under RAP3 settings, change the path where ampersand can be found. On Remium, this will be C:\Users\ampersandadmin\AppData\Roaming\local\bin\ampersand.exe
+
+
+
+Unfortunately, we ran into a [bug with Graphviz](http://www.graphviz.org/mantisbt/view.php?id=2108). It seems, that graphviz doesn't run on windows server. For that reason, Remium doesn't work currently.
+
+
+
diff --git a/docs/the-tools-we-use/deploying-with-kubernetes.md b/docs/the-tools-we-use/deploying-with-kubernetes.md
new file mode 100644
index 0000000000..3445e839cb
--- /dev/null
+++ b/docs/the-tools-we-use/deploying-with-kubernetes.md
@@ -0,0 +1,270 @@
+---
+description: >-
+ This page is under construction and does not work yet. Help is appreciated.
+ Currently, the move from docker-compose to Kubernetes has low priority.
+---
+
+# Deploying with Kubernetes
+
+## Purpose
+
+Deploying your Ampersand application to production can be done fast and frequent. For this purpose we are working on deployment on the Kubernetes platform. This allows you to deploy easily on your laptop \(for testing\), in your own data center \(The minimum you need is a virtual machiine that runs kubernetes\), or in the cloud \(to benefit from the reliability and security provided by hosting providers\). We use Kubernetes because it is open, free, well known, widely used, and is continuously being impoved by a large community. It lets you deploy fast and lets you upgrade the application without taking it offline.
+
+## Way of working
+
+1. A Kubernetes cluster is needed as the platform from which to launch and maintain the application. If it is there, that's fine. Otherwise you get one from a provider, from a data center, or you create one yourself \(e.g. on your laptop\). The cluster is built on top of virtual or physical machines and hosts and exposes the services that constitute the application.
+2. On the platform I need a registry from which Kubernetes can pull the image\(s\).
+
+I tried it out for myself. I stole my inspiration from [Kevin Smets' instruction](https://gist.github.com/kevin-smets/b91a34cea662d0c523968472a81788f7). Thank you Kevin! I ran the following from my terminal \(i.e. MacOS cli\), just for the purpose of getting some hands-on experience...
+
+### Requirements
+
+To make a Kubernetes cluster, I used Minikube. Minikube requires that VT-x/AMD-v virtualization is enabled in BIOS. To check that this is enabled on OSX / macOS, I ran:
+
+```text
+sysctl -a | grep machdep.cpu.features | grep VMX
+```
+
+If there's output, it works!
+
+### Prerequisites
+
+* kubectl
+* docker \(for Mac\)
+* minikube
+* virtualbox
+
+```text
+brew update && brew install kubectl && brew cask install docker minikube virtualbox
+```
+
+### Verify
+
+```text
+docker --version # Docker version 17.09.0-ce, build afdb6d4
+docker-compose --version # docker-compose version 1.16.1, build 6d1ac21
+docker-machine --version # docker-machine version 0.12.2, build 9371605
+minikube version # minikube version: v0.22.3
+kubectl version --client # Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.1", GitCommit:"f38e43b221d08850172a9a4ea785a86a3ffa3b3a", GitTreeState:"clean", BuildDate:"2017-10-12T00:45:05Z", GoVersion:"go1.9.1", Compiler:"gc", Platform:"darwin/amd64"}
+```
+
+### Start
+
+```text
+minikube start
+```
+
+This can take a while, expected output:
+
+```text
+Starting local Kubernetes cluster...
+Kubectl is now configured to use the cluster.
+```
+
+Great! You now have a running Kubernetes cluster locally. Minikube started a virtual machine for you, and a Kubernetes cluster is now running in that VM.
+
+### Check k8s
+
+```text
+kubectl get nodes
+```
+
+Should output something like:
+
+```text
+NAME STATUS ROLES AGE VERSION
+minikube Ready <none> 40s v1.7.5
+```
+
+Within minikube, a docker platform is running. However, on my Mac I have another docker daemon running. So which docker do we want to talk to? In this case that is definitely the docker daemon that is inside minikube...
+
+### Use minikube's built-in docker daemon
+
+```text
+eval $(minikube docker-env)
+```
+
+\(You might add this line to `.bash_profile` or `.zshrc` or ... to use minikube's daemon by default. Or if you do not want to set this every time you open a new terminal\).
+
+If I want to talk to the docker daemon on my Mac, I have to revert back to it by running:
+
+```text
+eval $(docker-machine env -u)
+```
+
+When running `docker ps`, it showed the following output:
+
+```text
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+3835176d93bb k8s.gcr.io/k8s-dns-sidecar-amd64 "/sidecar --v=2 --lo…" 30 minutes ago Up 30 minutes k8s_sidecar_kube-dns-86f4d74b45-4b48w_kube-system_91346644-e424-11e8-bae2-080027501972_0
+3c803544be8a k8s.gcr.io/kubernetes-dashboard-amd64 "/dashboard --insecu…" 30 minutes ago Up 30 minutes k8s_kubernetes-dashboard_kubernetes-dashboard-6f4cfc5d87-mvtgw_kube-system_962829f4-e424-11e8-bae2-080027501972_0
+1d74c735c1df k8s.gcr.io/coredns "/coredns -conf /etc…" 30 minutes ago Up 30 minutes k8s_coredns_coredns-c4cffd6dc-xn62h_kube-system_961c845a-e424-11e8-bae2-080027501972_0
+308bd132b35a gcr.io/k8s-minikube/storage-provisioner "/storage-provisioner" 31 minutes ago Up 30 minutes k8s_storage-provisioner_storage-provisioner_kube-system_963bf651-e424-11e8-bae2-080027501972_0
+```
+
+The list was in fact a little bit longer: it contained 22 containers.
+
+#### Build, deploy and run an image on your local k8s setup
+
+To setup a local registry, so Kubernetes can pull the image\(s\) from there:
+
+```text
+docker run -d -p 5000:5000 --restart=always --name registry registry:2
+```
+
+To test whether there is a local registry, ask docker:
+
+```bash
+BA92-C02VP224HTDF:RAP stefjoosten$ docker ps | grep registry
+97dc5ed7102d registry:2 "/entrypoint.sh /etc…" 4 days ago Up 4 days 0.0.0.0:5000->5000/tcp registry
+BA92-C02VP224HTDF:RAP stefjoosten$
+
+```
+
+### Build
+
+First of, store all files \(Dockerfile, my-app.yml, index.html\) in this gist locally in some new \(empty\) directory.
+
+You can build the Dockerfile below locally if you want to follow this guide to the letter. Store the Dockerfile locally, preferably in an empty directory and run:
+
+```text
+docker build . --tag my-app
+```
+
+You should now have an image named 'my-app' locally, check by using `docker images` \(or your own image of course\). You can then publish it to your local docker registry:
+
+```text
+docker tag my-app localhost:5000/my-app:0.1.0
+```
+
+Running `docker images` should now output the following:
+
+```text
+REPOSITORY TAG IMAGE ID CREATED SIZE
+my-app latest cc949ad8c8d3 44 seconds ago 89.3MB
+localhost:5000/my-app 0.1.0 cc949ad8c8d3 44 seconds ago 89.3MB
+httpd 2.4-alpine fe26194c0b94 7 days ago 89.3MB
+```
+
+### Deploy and run from docker-compose.yml
+
+I have a file called `docker-compose.yml`, which I have used to deploy RAP with docker-compose \(rather than Kubernetes\). I used `kompose` to transform that into the necessary Kubernetes .yaml files.
+
+```text
+brew install kompose
+```
+
+I deployed straight from the `docker-compose.yml` file:
+
+```text
+kompose up
+```
+
+However, I can also create the necessary Kubernetes files and deploy from `kubectl`:
+
+```text
+kompose convert
+```
+
+This converts `docker-compose.yml` into the following files:
+
+```text
+db-claim0-persistentvolumeclaim.yaml
+db-deployment.yaml
+phptools-deployment.yaml
+phptools-service.yaml
+rap3-claim0-persistentvolumeclaim.yaml
+rap3-claim1-persistentvolumeclaim.yaml
+rap3-deployment.yaml
+rap3-service.yaml
+```
+
+Having run `kompose up` to deploy the three RAP services, I now have the following situation on my minikube:
+
+```text
+BA92-C02VP224HTDF:RAP stefjoosten$ kubectl get all
+NAME READY STATUS RESTARTS AGE
+pod/db-56c6b7b6cc-442k9 1/1 Running 1 3d
+pod/phptools-555cc5db49-w7z6k 1/1 Running 0 3d
+pod/rap3-668d94bb95-cp8vs 1/1 Running 0 3d
+
+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+service/kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4d
+service/phptools ClusterIP 10.107.212.219 <none> 8080/TCP 3d
+service/rap3 ClusterIP 10.101.81.211 <none> 80/TCP 3d
+
+NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
+deployment.apps/db 1 1 1 1 3d
+deployment.apps/phptools 1 1 1 1 3d
+deployment.apps/rap3 1 1 1 1 3d
+
+NAME DESIRED CURRENT READY AGE
+replicaset.apps/db-56c6b7b6cc 1 1 1 3d
+replicaset.apps/phptools-555cc5db49 1 1 1 3d
+replicaset.apps/rap3-668d94bb95 1 1 1 3d
+```
+
+\(I got even more information with the command `kubectl get all --output=wide`.\)
+
+So we see three pods \(containers\) running. Each of the pods is wrapped in a service of its own and exposed internally on the local network of this cluster. \(In Kubernetes, [nodes](https://kubernetes.io/docs/admin/node), [pods](https://kubernetes.io/docs/user-guide/pods) and [services](https://kubernetes.io/docs/user-guide/services) all have their own IPs. In many cases, the node IPs, pod IPs, and some service IPs on a cluster will not be routable, so they will not be reachable from a machine outside the cluster, such as your desktop machine.\)
+
+To access these services from a browser, we now need to expose these services to localhost. I did this by exposing both services from the minikube platform:
+
+```text
+BA92-C02VP224HTDF:RAP stefjoosten$ minikube service rap3
+Opening kubernetes service default/rap3 in default browser...
+BA92-C02VP224HTDF:RAP stefjoosten$ minikube service phptools
+Opening kubernetes service default/phptools in default browser...
+```
+
+### Deploy and run from Kubernetes yml files
+
+Store the file below `my-app.yml` on your system and run the following:
+
+```text
+kubectl create -f my-app.yml
+```
+
+You should now see your pod and your service:
+
+```text
+kubectl get all
+```
+
+The configuration exposes `my-app` outside of the cluster, you can get the address to access it by running:
+
+```text
+minikube service my-app --url
+```
+
+This should give an output like `http://192.168.99.100:30304` \(the port will most likely differ\). Go there with your favorite browser, you should see "Hello world!". You just accessed your application from outside of your local Kubernetes cluster!
+
+### Kubernetes GUI
+
+```text
+minikube dashboard
+```
+
+### Delete deployment of my-app
+
+```text
+kubectl delete deploy my-app
+kubectl delete service my-app
+```
+
+You're now good to go and deploy other images!
+
+## Reset everything
+
+```text
+minikube stop;
+minikube delete;
+rm -rf ~/.minikube .kube;
+brew uninstall kubectl;
+brew cask uninstall docker virtualbox minikube;
+```
+
+### Version
+
+Last tested on 2017 October 20th macOS Sierra 10.12.6
+
diff --git a/docs/the-tools-we-use/functionality-of-rap3/README.md b/docs/the-tools-we-use/functionality-of-rap3/README.md
new file mode 100644
index 0000000000..3a57bd5c7e
--- /dev/null
+++ b/docs/the-tools-we-use/functionality-of-rap3/README.md
@@ -0,0 +1,87 @@
+# Functionality of RAP4
+
+These pages are meant to describe the functionality of RAP4. As RAP4 is still under development, some of this functionality is still work in progress. We will tell the current status of everything mentioned here. While doing so, this document will grow until it describes everything one can do with RAP4.
+
+The purpose of RAP4 is to be a platform for people to learn how to work with Ampersand. We distinguage the following ROLEs:
+
+* Student.
+* Tutor. This role is to watch the progress of students, and being able to give guidance.
+* AccountMgr. This role is to create accounts and to grant access rights to users.
+* GradStudent. This role is for more advanced students.
+
+All of the above users have access to the login page. Further functionality is based on specific roles.
+
+## Logging in <a id="rap3-login"></a>
+
+
+
+When you log in, a userid and password must be entered.
+
+## Logging out
+
+After you have logged in, this screen turns into a logout-screen. The menu bar gives you the options you are entitled to by the role\(s\) you have. In this case you get `MyScripts` and `My Account`:
+
+
+
+In the sequel, the functionality is described by role.
+
+
+## Student
+
+As a student, your main objective with RAP3 is to write Ampersand scripts and have them compiled. RAP3 will help you by giving error messages when your script contains errors. If your script complies to the Ampersand syntax and has no type errors, it will let you generate artifacts from your script. Currently these artifacts are
+
+1. A diagnosis document
+2. A functional design document
+3. An analysis site, containing an overview of concepts, relations and rules in your script.
+
+You might find it interesting to know that RAP3 has been built with Ampersand itself!
+
+### Create an Ampersand script
+
+
+
+A new script can be made by hitting the + sign in the menu and go to New Script. A new script is being made, but it doesn't have any content:
+
+
+
+In the header of the script you can see Script
+
+\_
+
+_\__
+
+_\_1491765040_
+
+_\_
+
+\_
+
+00901936, which is a
+
+\(
+
+generated
+
+\)
+
+ identifier of the instance, with which you have nothing to do. The big white space in the middle is where you will write your script. You could als choose to upload a script from your computer. It is a good habit to save your scripts at your own computer, because currently we have no functionality to retrieve your script easily. Please take care of your own precious work yourself.
+
+Each time you modify your script, you have to send it to Ampersand by pressing the big blue button below the white space. Only then Ampersand will be notified about your changes.
+
+
+
+After you pressed the blue button, you can check the compile checkbox. Ampersand is launched and it will validate your script. If any error is found, it will notify you, as shown above.
+
+If your script is OK however, it will also tell you, by letting you know that processing has come to an end:
+
+
+
+Every time compilation is succesful, a new version of your script will be made. You will see the most recent version. Now you can ask for the artifacts, by checking an appropriate checkbox. This will take some time, and a link will appear at the right of the checkbox. If you follow that link, the result will be shown.
+
+
+## Tutor
+
+## Account Manager
+
+## Graduate Student
+
diff --git a/docs/the-tools-we-use/git.md b/docs/the-tools-we-use/git.md
new file mode 100644
index 0000000000..667c90a3e6
--- /dev/null
+++ b/docs/the-tools-we-use/git.md
@@ -0,0 +1,101 @@
+---
+description: >-
+ We use Git for version control, with the shared Ampersand repository located
+ at Github. This chapter provides the information to get to the repository and
+ clone it for having your own local copy.
+---
+
+# Version control with Git
+
+We use Git for the following purposes:
+
+1. to have a shared repository that contains our source code;
+2. to work on different features in parallel without interference and without having to wait for each other;
+3. to prevent loss of code because multiple copies exist on multiple sites;
+4. to have an accurate registration of changes, their authors, and the time each change has occurred.
+
+We maintain and use the following repositories at Github:
+
+| Repo | purpose |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Ampersand](https://github.com/AmpersandTarski/Ampersand) | contains the source code of the Ampersand compiler up to the point that all the regular docker images can be generated from this repository. |
+| [ampersand-models](https://github.com/AmpersandTarski/ampersand-models) | contains a collection of Ampersand models, which are meant for reuse by the public at large. |
+| [Ampersand-Language-Support](https://github.com/AmpersandTarski/Ampersand-Language-Support) | contains language support for VS-code, such as syntax coloring, code snippets, and the like. |
+| \*\*\*\*[Publications](https://github.com/AmpersandTarski/Publications) | This repo is meant for collaborative writing of journal and conference papers about Ampersand. |
+| [Prototype](https://github.com/AmpersandTarski/Prototype) | contains JavaScript source code of the prototype front-end and back-end generators and runtime code. |
+| [documentation](https://github.com/AmpersandTarski/documentation) | contains the source code of the documentation of Ampersand on GitBook. |
+| [TheToolsWeUse](https://github.com/AmpersandTarski/TheToolsWeUse) | contains the source code of the documentation on GitBook of tools used to create Ampersand. |
+| [RAP](https://github.com/AmpersandTarski/RAP) | contains the source code of RAP, a tool that lets you analyse Ampersand models, generate functional specifications and make prototypes of information systems. It is the primary tool for students of the Open University of the Netherlands in the course Rule Based Design. |
+| [MirrorMe](https://github.com/AmpersandTarski/MirrorMe) | contains the source code for an argument assistance system. It is based on defeasible reasoning along the lines of Toulmin and Hohfeld. |
+| [sentinel](https://github.com/AmpersandTarski/sentinel) | (obsolete) Software for automated testing the Ampersand software. Today, most of our testing is done by means of Travis-ci. Before that we heavily used our own sentinel to warn about bugs. Today, Sentinel is only used for issues with known bugs. Things that are known to break, and we didn't find time to solve them. |
+| [webFiles](https://github.com/AmpersandTarski/webFiles) | contains all kind of consolidated documents that are related to Ampersand in some way. They are stored here to ensure that we have stable URLs to these documents, so we can hyperlink to them wherever appropriate |
+
+## Getting started with Git
+
+Understanding the basics of Git is essential for anyone working on Ampersand. Fortunately, there is good help available:
+
+1. [The help at GitHub](https://help.github.com/articles/)
+
+- If you want write access to the Ampersand repo, create yourself an account at [GitHub](https://www.github.com), if you don't have one already. You don't need that if you just want to read.
+ - Ask one of the administrators of Ampersand to add you as member to the team, stating that you want/need write access to the Ampersand repo or any other repo in the project.
+- If you need a local copy on your own computer, install [Git for Windows](http://msysgit.github.io/) or [Git for MacOS](https://nl.atlassian.com/git/tutorials/install-git#mac-os-x) to stay abreast with the latest version.
+- When installing for Windows:
+ - Accept all defaults, except:
+ - 4th screen check "Windows Explorer integration" / "Simple context menu" / "Git Bash here"
+ - 6th screen "Use Git from the Windows Command Prompt"
+
+## Tools for Git
+
+Git works from the command prompt. There are however some tools that make life easier when you work with Git. Not necessary, but very much appreciated.
+
+- Install [TortoiseGit](https://tortoisegit.org/) to use Git in your Windows Explorer.
+ - Accept all defaults
+- Install [SourceTree](http://www.sourcetreeapp.com) to visualize the history in the most popular Git client.
+
+ - No global ignore, further everything default
+ - When at _Add an account_, select _GitHub_ and supply your credentials.
+
+ Note: there are many other git clients too, many of which are free, e.g. [Github Desktop](https://desktop.github.com/) or [GitKraken](https://www.gitkraken.com/).
+
+- Install [KDiff3](http://sourceforge.net/projects/kdiff3/files/kdiff3/) to get help in merging conflicts. To avoid KDiff3, you can merge conflicts from your editor or IDE as well.
+ - To select KDiff3 in SourceTree, go to SourceTree / Tools / Options / Diff and select KDiff3 for External Diff Tool and Merge Tool.
+- Pin Git Bash to Start menu to use Git from a command line interface.
+- When you use excel-files (\*.xlsx and \*.xls), you can extend git to handle these files properly with [ExcelCompare](https://gist.github.com/PrabhatKJena/0884644ae01a49a9819aebd883e54003). This works for command-line git on Mac. Similar extensions exist for Windows (TBD: which?)
+
+## Configuring Security
+
+To avoid typing a GitHub password for every commit you make, [install an SSH-key](https://help.github.com/articles/connecting-to-github-with-ssh/). Here is the short version:
+
+- **Generate a SSH Key**
+ - Start / All programs / Git / Git GUI: Help / Show SSH Key
+ - Press Generate Key. You can supply a pass phrase, but that's optional. You should of course keep it for yourself. (it is in _$home/.ssh/id_rsa_). When you use a pass phrase, you will have to supply it now and then.
+- **Access to repositories of AmpersandTarski** (GitHub).
+ - Go to your [personal settings](https://github.com/settings/profile)
+ - press _Add SSH Key_
+ - Title: add a description of the machine you currently work on (eg. "Windows Laptop Stef")
+ - Key: past your generated key
+ - Press "Add Key"
+
+## Checking out Ampersand source code
+
+Checking out means to create your own local copy of the repository. By default, the Git directory in your home directory will be used for all local repositories. You have various options to do this
+
+- Use your git client (e.g. [Github Desktop](https://desktop.github.com/), [SourceTree](https://www.sourcetreeapp.com/), or [GitKraken](https://www.gitkraken.com/)) if you want to click instead of typing commands.
+- Use your command-line interface:
+
+ - go to your working directory
+
+ `cd git`
+
+ - clone the repo with this command:
+
+ `git clone git@github.com:AmpersandTarski/Ampersand.git`
+
+- Use TortoiseGit for integration with your file system
+ - First time, you have to configure ssh:
+ - Start / All Programs / TortoiseGit / Network:
+ - At "SSH Client" fill in: C:\Program Files (x86)\Git\bin\ssh.exe
+
+## Done?
+
+You are done with this page once you have your local copy of the Ampersand source code on your own computer, under Git. Do this only if you want to change the Ampersand software; not if you only want to use Ampersand.
diff --git a/docs/the-tools-we-use/gitbook/README.md b/docs/the-tools-we-use/gitbook/README.md
new file mode 100644
index 0000000000..44cc22e96b
--- /dev/null
+++ b/docs/the-tools-we-use/gitbook/README.md
@@ -0,0 +1,26 @@
+---
+description: >-
+ Gitbook is used to maintain Ampersand documentation in a collaborative way.
+ This page is the work instruction for all those who help to document Ampersand
+ in Gitbook.
+---
+
+# Documenting with GitBook
+
+We use [Gitbook](https://github.com/ampersandtarski/the-tools-we-use-for-ampersand/tree/a690f2c93b3d3ecc88047fcec3a63a82eb93e2a9/www.gitbook.com) for the following purposes:
+
+1. to maintain documentation that changes continuously as a team, without having too much work on the coordination of this collaboration;
+2. to get good looking documentation with little effort;
+3. to maintain the documentation on the internet, so we can hyperlink to it from anywhere.
+
+The documentation you are reading at this very moment is created using GitBook. It allows to write the documentation in [Markdown](https://www.gitbook.com/book/gitbookio/markdown/details), which is an easy to use document-format.
+
+The documentation can be changed by the [gitbook-editors of Ampersand](https://app.gitbook.com/@ampersandtarski/teams). For helping to document Ampersand, please request an authorization for Gitbook with [an administrator or owner](https://app.gitbook.com/@ampersandtarski/teams).
+
+The documentation is organized as a book. We prefer this over a traditional wiki, because a book contains a content part, which helps both author as well as the reader to think about structure, so everything can easily be found. Each book can be served as a \(part of a\) website, as well be downloaded in several forms, like pdf or e-book. We use a fully automated toolchain to build the book for each commit to the master branch of a book.
+
+At AmpersandTarski, we currently have two repositories, each dedicated to the documentation for a specific audience:
+
+1. The repository [AmpersandTarski/TheToolsWeUse](https://github.com/AmpersandTarski/TheToolsWeUse) contains the contents of the book you are currently reading. You probably found it [here](https://www.gitbook.com/book/ampersandtarski/the-tools-we-use-for-ampersand/details). This document is not about Ampersand, but about the way Ampersand is being developed
+2. The repository [AmpersandTarski/documentation](https://github.com/AmpersandTarski/documentation) is going to contain the documentation about Ampersand itself.
+
diff --git a/docs/the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation.md b/docs/the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation.md
new file mode 100644
index 0000000000..48c8a84ec8
--- /dev/null
+++ b/docs/the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation.md
@@ -0,0 +1,16 @@
+# Do's and Dont's in Ampersand documentation
+
+## Do's and don'ts
+
+## Every commit in the origin/master branch is built.
+
+If you prefer the web editor, know that each time the master branch is committed, the book is generated. While we are in draft, it is recommended to use a separate branch to do the writing. This prevents too many commits in the github repo master, as each time you save your work in the editor, a commit is done. If you use the [desktop client](https://www.gitbook.com/editor/), this is far less a problem, because you only synchronize when you made some more changes.
+
+## A reference can only be made to an article.
+
+As far as I know, a reference can only be made to something written down in an article, i.e. a separate file. Therefore, it is a good habit to focus on exactly one thing you want to explain/write about in every file.
+
+## Referencing is done to relative locations.
+
+If you want to refer to another article, that can be done by using a relative path. Like I have done with this link to [Getting started with gitbook.](getting-started-with-gitbook.md) It is probably a good habit to check that the links work, by checking the book as it is generated.
+
diff --git a/docs/the-tools-we-use/gitbook/getting-started-with-gitbook.md b/docs/the-tools-we-use/gitbook/getting-started-with-gitbook.md
new file mode 100644
index 0000000000..e26f21e259
--- /dev/null
+++ b/docs/the-tools-we-use/gitbook/getting-started-with-gitbook.md
@@ -0,0 +1,18 @@
+# Getting started with GitBook
+
+## Getting started with GitBook
+
+If you want to add to the documentation, it is possible to update the repository with any tool you like. However, we strongly advise to use the GitBook editor. A lot of cumbersome work is automated for you. Here are the steps to get on your way:
+
+* Create an account at [Gitbook](https://github.com/ampersandtarski/the-tools-we-use-for-ampersand/tree/a690f2c93b3d3ecc88047fcec3a63a82eb93e2a9/gitbook/www.gitbook.com).
+* Once you have an account get in touch with [Han Joosten](mailto://han.joosten.han@gmail.com) so he can grant you access to the book\(s\) you want to contribute to.
+* You will automatically find the books at your [Gitbook dashboard](https://www.gitbook.com/@ampersandtarski/dashboard), where you will find a button to start editing the book.
+
+## The GitBook Web Editor
+
+The editor explains itself. At GitBook, they eat their own dogfood to write [GitBook Documentation](http://help.gitbook.com/) .
+
+## The GitBook desktop client
+
+Recently, Gitbook also has a desktop client. It can be found [here.](https://www.gitbook.com/editor/) When you install this desktop client, GitBook will make a local clone of the book. You will find it at `~home/Gitbook`. As far as I know, this is not configurable, so you'll just have to deal with it. You can synchronize from within gitbook. However, if it gets a little bit complicated, I prefer sourcetree to give the correct git commands.
+
diff --git a/docs/the-tools-we-use/group-1/development-using-vs-code.md b/docs/the-tools-we-use/group-1/development-using-vs-code.md
new file mode 100644
index 0000000000..02093f1f82
--- /dev/null
+++ b/docs/the-tools-we-use/group-1/development-using-vs-code.md
@@ -0,0 +1,83 @@
+---
+description: >-
+ Most of us use VS Code as a code editor. This page is about some handy
+ configuration tips.
+---
+
+# Haskell development using VS Code
+
+This section is about being able to hack around in the ampersand generator. It is written in Haskell, so if you want to contribute, you need to have a development environment set up. You also need to know some of our way of working.
+
+## Agreements about the development of code
+
+### Working with feature branches
+
+All changes that are made to the code is done in feature branches. Such a branch should have a specific goal. Normally, this is documented in a single github issue. While the work can take some time, eventually a pull request is made in order to merge it into main. There are several requirements that must be met before a pull request can be merged.
+
+### Releasenotes
+
+Every feature must be briefly documented in the releasenotes. A github action is in place that will notify if the releasenotes are not changed.
+
+### Code formatting
+
+All code must be formatted in a consistent way. We use [ormolu](https://hackage.haskell.org/package/ormolu), a standard code formatting tool for Haskell. We only accept Haskell files that are properly formatted. This is enforced by a new [github action](https://github.com/mrkkrp/ormolu-action#ormolu-action).
+
+In order to use ormolu, you have to make sure it is available. Hopefully, some time in future, this will be installed automatically. Until then, you have to install it yourself:
+
+```
+stack install ormolu
+```
+
+:::tip
+
+If you use the devcontainer functionality (available in vscode), your code is auto-formatted by default. In other cases, you can best let vscode take care of it automatically. To do so, in the settings of vscode, enable format-on-save.
+
+Alternatively, in case you do not like to enable the autoformat on save, you can do it manually every time before you commit:
+
+```bash
+stack exec ormolu -- --mode inplace $(git ls-files '*.hs')
+```
+
+:::
+
+### Devcontainer
+
+We provide a standard developer container to the developers of Ampersand. Documentation about this awesome VScode feature can be found [here](https://code.visualstudio.com/docs/remote/containers).
+
+#### How to get started using the .devcontainer stuff
+
+Setting up a Haskell environment with awesome tooling has never been as easy as today.
+
+- Make sure you have vscode installed.
+- Install the [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) extension pack.
+- Make sure Docker is running.
+- Go to the directory where your Ampersand stuff resides, and type \`code .\`
+- In the lower right corner, you will see a message:
+
+
+
+- Push the button \`Reopen in Container\` and watch the show.
+
+:::info
+The first time, opening the development container will take quite some time. It will build some docker images and finally spin up the container. Fortunately, this is one time only, for it is stored in the build cache of Docker.
+:::
+
+- While you are waiting, you can watch the progress by inspecting the log. There will be a message containing a link to the log file.
+
+<details>
+
+<summary>What if `Reopen in Container` doesn't appear?</summary>
+
+This behavior can happen when you clicked 'Don't Show Again...' in the past.
+
+In this case, you can click on the status bar at the place where the 'remote container' plugin shows the machine you are currently using:
+
+.png>)
+
+After you clicked, choose the menu-item \`Reopen in container\`
+
+</details>
+
+- After everything is set up, open `Main.hs` . This will trigger the Haskell extension of vscode. Also here, the first time will take a while, because the project is being build. That includes all dependencies of Ampersand. If you want to see what is going on, go to the Output tab and open the dropdown called \`tasks\`. You will find the task building Ampersand:
+
+
diff --git a/docs/the-tools-we-use/installation-of-rap/README.md b/docs/the-tools-we-use/installation-of-rap/README.md
new file mode 100644
index 0000000000..79b1636680
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/README.md
@@ -0,0 +1,21 @@
+# Installation of RAP
+
+RAP is a **R**epository for **A**mpersand **P**rojects. This tool is being used by the Open University of the Netherlands in the course [Rule-Based Design](http://portal.ou.nl/web/ontwerpen-met-bedrijfsregels). It lets users analyse Ampersand models, generate functional specifications, and make prototypes of information systems. It is the primary tool for students in relation to Ampersand.
+
+Deployment means to install RAP4 on a web server or a laptop of your own. The easiest way to try Ampersand, however, is by just using the [OUNL-installation](https://rap.cs.ou.nl) and avoid the installation.
+
+## Automated deployment
+
+We use Docker for automating the deployment and making RAP portable over different platforms. The following three sections report three different installations we did:
+
+* to [deploy RAP on a laptop](deploying-to-your-own-laptop.md);
+* to [deploy RAP on an Ordina server](deploying-rap3-with-azure-on-ubuntu.md) in the Azure cloud;
+* to [deploy RAP at the Open University](deploying-ounl-rap3.md) on a server in the OUNL-datacenter.
+
+These three reports will most likely contain enough information to let you reproduce the installation on a computer or platform of your own.
+
+The last section of this chapter discusses the [making of docker images](making-docker-images.md), which you may need if the above does not work because the images are (for any reason whatsoever) unavailable on the internet.
+
+## Questions? Need help?
+
+Don't hesitate to contact Han Joosten. He'll be glad to help out.
diff --git a/docs/the-tools-we-use/installation-of-rap/deploying-ounl-rap3.md b/docs/the-tools-we-use/installation-of-rap/deploying-ounl-rap3.md
new file mode 100644
index 0000000000..3413270d81
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/deploying-ounl-rap3.md
@@ -0,0 +1,87 @@
+# Deploying OUNL RAP4
+
+If you want to deploy RAP4 on your own server, you might try to copy how I deployed RAP4 at the OUNL. This chapter tells you how.
+
+In early 2016 the need arose to replace the RAP2 implementation of Ampersand by a RAP3 implementation, because RAP2 was insufficiently maintainable. This environment is used by students for completing the course Rule Based Design (OBR, code IM0103). This implementation is hosted by ICTS, the IT-department of the university.
+
+This chapter is an account of the installation process. It serves the following purposes:
+
+1. It is an example for others who want to deploy Ampersand.\
+ We get requests now and then by people who want to deploy Ampersand, so we figured it is nice to have a documented example for them.
+2. It documents the installation we made for the Open University.\
+ We want maintenance of RAP4 to be transferable to other persons, so we need to document the choices made and the reasons for making them.
+3. It contains all information needed to make a deployment script for automated deployment.\
+ We have automated the deployment with Docker, so that RAP4 will always be up to date with the most recent stable release of Ampersand.
+
+Each step in the installation process gets a separate section in this text.
+
+## 1. Setting up the virtual machine
+
+I got a server from the Open University's IT-department.
+
+The following settings apply:
+
+| | |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| server name | lnx-hrl-202v |
+| OS | Ubuntu 18.04.5 LTS (GNU/Linux 4.15.0-153-generic x86\_64 |
+| Admin user name | sjo |
+| verification type | password (Stef Joosten knows the password) |
+| Size | 2 core, 7GB |
+| Inbound port: RAP4 (HTTP) | TCP/80 |
+| Inbound port: HTTPS | TCP/443 |
+| Inbound port: SSH | TCP/22 |
+| Public IP-adres | 145.20.188.96 |
+| domain name for calling the application | [rap.cs.ou.nl](https://rap.cs.ou.nl) |
+| internet access needed | for generating prototypes because the prototype generator draws from the Ampersand-github repository. |
+
+## Getting access to the server
+
+At the OUNL, we need VPN to gain access with SSH to a server. This requires approval from the IT department. I got a raw Ubuntu machine, meaning that the port settings (specified above) and VPN have to be requested at the IT-servicedesk.
+
+I can now access this machine through SSH (using PUTTY, which I downloaded from the Internet), but only after installing a VPN-tunnel to the server (using Pulse Secure). In the sequel, I will refer to this machine as "the server". This gave me access through a command line interface (CLI). Ubuntu gave me bash as its CLI.
+
+## Installing Docker
+
+Since this is a fresh machine, docker has to be installed. By just typing `docker`, the server advised to install Docker by means of the command `sudo apt install docker.io`. This turned out to be a bad advice, because it resulted in a too old version of docker. Instead, I followed the instructions on `https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/` for installing docker. The instructions for docker-compose are found on `https://docs.docker.com/compose/install/` .
+
+Then I checked that everything went successfully by means of the `which`-command:
+
+```
+sjo@lnx-hrl-202v:~$ which docker
+/usr/bin/docker
+sjo@lnx-hrl-202v:~$ which docker-compose
+/usr/bin/docker-compose
+```
+
+## Obtaining the files we need
+
+We need only one file: `docker-compose.yml`\
+To get it, I used the `wget` command, which gets stuff from the web:
+
+```
+sjo@lnx-hrl-202v:~$ mkdir RAP4
+sjo@lnx-hrl-202v:~$ cd RAP4
+sjo@lnx-hrl-202v:~/RAP4$ wget https://raw.githubusercontent.com/AmpersandTarski/RAP/master/docker-compose.yml
+```
+
+## Installing RAP4
+
+To install RAP4:
+
+```
+sjo@lnx-hrl-202v:~/RAP4$ docker compose up -d
+```
+
+To check whether this worked, I went to my browser and navigated to `http://145.20.188.96/RAP4`.\
+It took a while to get started, because it was building a fresh database.
+
+I checked whether the containers are running by means of the `docker ps` command.
+
+Completion of this step allowed access to RAP4 from an arbitrary computer on the internet:
+
+
+
+The database is accessible on port 8080:
+
+
diff --git a/docs/the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu.md b/docs/the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu.md
new file mode 100644
index 0000000000..09f077e8ee
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu.md
@@ -0,0 +1,110 @@
+# Deploying RAP4 in the Azure cloud
+
+In early 2017 the need arose for an Ampersand implementation in Ordina's cloud, to let young professionals get acquainted with Ampersand. We chose to implement RAP4 in Azure, because Ordina has an Azure subscription. RAP4 is the same environment that our students use at the Open Universiteit, so the maintainance of RAP4 can be reused for both target audiences.
+
+This chapter is an account of the deployment of RAP4. You can use it as an example if you want to do it yourself.
+
+Deployment has been automated using docker, because we want to make the deployment as much as possible automated. The required images are available on Docker-hub, so deployment is immediate. Automated deployment by docker means that we can quickly release updates too.
+
+## 0. Deployment approach
+
+We use Docker to simplify the deployment of RAP and make this installation portable to many different computers.
+
+We took a simple Linux machine, installed docker, and built docker images for RAP4 and created three containers: db, rap4, and phpmyadmin. The first one, db, runs MariaDB and contains the administration of RAP4 and the Ampersand scripts of users. The rap4 container contains the RAP4 application proper. It is accessed on port 80. The container phpmyadmin is present for maintainers to inspect the database through phpMyAdmin. It is accessible through port 8080.
+
+Each step in the installation process is described by a separate section in the sequel.
+
+## 1. Setting up the virtual machine
+
+I needed an Azure account to enter the Azure portal and install a server for Ampersand. I got my account from Ordina. Azure offers preconfigured installations to kick-start a virtual machine. In principle, any server that runs docker will work. I picked CoreOS, which is a minimal Linux platform and suitable for container computing with docker.
+
+The following settings were made:
+
+| | |
+| :--- | :--- |
+| subscription in Azure | Ordina TC - RT O Pega - Learning |
+| server name | Wolfram |
+| type VM-disk | SDD |
+| OS | Linux |
+| configuration | Ubuntu 18.04 |
+| Admin user name | ampersandadmin |
+| verification type | password \(Stef Joosten knows the password\) |
+| Resource group \(in Azure\) | AmpersandRAP4 |
+| location \(in Azure\) | Western Europe |
+| Size | Standard DS11 v2 \(2 cores, 14 GB memory\) |
+| Inbound port: RAP4 \(HTTP\) | TCP/80 |
+| Inbound port: HTTPS | TCP/443 |
+| Inbound port: SSH | TCP/22 |
+| Public IP-adres | 137.117.190.28 \(static\) |
+| the full name for calling the application | http://137.117.190.28/RAP4 |
+
+I verified completion of this step by checking the Azure dashboard. It shows machine `Wolfram` running.
+
+I have verified the machine was live by logging in via Putty \(a popular SSH-client\). I accessed this machine, using `ampersandadmin@137.117.190.28` and the correct password. In the sequel, I will refer to this machine as "the server".
+
+## 2. Port settings
+
+To perform this step, I didn't wait until step1 was completed. It is sufficient that the Netwerkbeveiligingsgroep `Wolfram-nsg` exists. In order to access RAP4 from the internet, we told the virtual machine to open port 80 for http and 443 for https. These settings were made in the Azure portal via `Resourcegroepen > AmpersandRAP4 > Wolfram-nsg (Netwerkbeveiligingsgroep) > inkomende beveiligingsregels`. A rules was added to make the server listen to port 80/TCP.
+
+No rule was added for the database, so the database is only open to phpMyAdmin and RAP4, or from within its container.
+
+## 3. Installing Docker
+
+This step requires a server, so you must have finished section 1 successfully. \(If `docker` and `docker-compose` are available, this step is superfluous.\) To install docker I followed the following steps in the given order:
+
+| step | Linux command |
+| :--- | :--- |
+| To work as root | sudo -i |
+| To install docker, I followed the instructions on [https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04). | |
+| To install docker-compose | apt-get install docker-compose |
+| To add the current user \(ampersandadmin\) to the docker group | usermod -aG docker $\(whoami\) |
+| To start the docker daemon | |
+| now reboot the machine | reboot |
+
+Of course, the last step \(reboot\) requires reconnecting to the machine.
+
+Then I checked that docker is running by:
+
+```text
+ sudo docker ps
+```
+
+I checked that docker-compose is available
+by:
+
+`which docker-compose`
+
+To check whether ampersandadmin is member of the docker group, use command cat /etc/group`.`
+
+## 4. Obtaining the install instruction
+
+We need only one file: `docker-compose.yml`
+To get it, I used the `wget` command, which gets stuff from the web:
+
+```text
+sjo@Wolfram:~$ mkdir docker-RAP4
+sjo@Wolfram:~$ cd docker-RAP4
+sjo@Wolfram:~/docker-RAP4$ wget https://github.com/AmpersandTarski/RAP/raw/master/docker-compose.yml
+```
+
+## 5. Installing RAP4
+
+To install RAP4:
+
+```text
+sjo@Wolfram:~$ sudo docker-compose up -d
+```
+
+To check whether this worked, I went to my browser and navigated to `http://137.117.190.28/`.
+It took a while to get started, because it was building a fresh database.
+
+I checked whether the containers are running by means of the `docker ps` command.
+
+Completion of this step allowed access to RAP4 from an arbitrary computer on the internet:
+
+
+
+The database is accessible on port 8080:
+
+
+
diff --git a/docs/the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop.md b/docs/the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop.md
new file mode 100644
index 0000000000..87011da01d
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop.md
@@ -0,0 +1,105 @@
+# Deploying to your own laptop
+
+If you want to deploy RAP4 to your laptop, this chapter tells you how.
+
+This example has worked on my Macbook. If you have a different computer, you may either change the commands below to the commands of your own computer or set up a virtual Linux machine on your laptop.
+
+## Prerequisites
+
+You need docker. Follow the instructions on`https://docs.docker.com/.`
+
+You need git. Follow the instructions on `https://github.com/git-guides/install-git`.
+
+You need to use a command-line, you need permission to install software on your laptop and you need to be connected to the Internet.
+
+Start in your command-line interface \(CLI, terminal on a macbook\) and go to \(or make\) a working directory from which you want to keep Git repositories.
+
+## Obtaining the files we need
+
+Import the required files from Github \(note: you may need to log in into Github\):
+
+```bash
+git clone https://github.com/AmpersandTarski/RAPinstall
+```
+
+Expect roughly this response:
+
+```text
+Cloning into 'RAPinstall'...
+remote: Enumerating objects: 19, done.
+remote: Counting objects: 100% (19/19), done.
+remote: Compressing objects: 100% (17/17), done.
+remote: Total 19 (delta 2), reused 14 (delta 0), pack-reused 0
+Unpacking objects: 100% (19/19), done.
+```
+
+Now go to the directory from which to install RAP:
+
+```bash
+cd RAPinstall
+```
+
+You need to create a proxy network to let RAP communicate with your browser \(no problem if it already exists; docker will tell you with an appropriate message\)
+
+```bash
+docker network create proxy
+```
+
+When docker has made the network, it tells you something like this:
+
+```text
+3f9552a7506ac5f2b5d9fcb158edae82f9f64e4e3d6b093916d624d118ba342a
+```
+
+Now spin up RAP4 \(note: in older versions of docker use `docker-compose` instead of `docker compose`. The difference is just a hyphen\):
+
+```bash
+docker compose up -d
+```
+
+The first time you spin up RAP4, docker will spontaneously download the images it needs. That generates substantial output. At the end docker will show the containers that have been started:
+
+```text
+ ⠿ Network rapinstall_db Created 3.9s
+ ⠿ Network rapinstall_default Created 3.9s
+ ⠿ Volume "rapinstall_rap4-data" Created 0.0s
+ ⠿ Volume "rapinstall_db-data" Created 0.0s
+ ⠿ Volume "rapinstall_letsencrypt" Created 0.0s
+ ⠿ Container traefik Started 7.1s
+ ⠿ Container rap4-db Started 5.2s
+ ⠿ Container rapinstall_dummy-student-prototype_1 Started 5.1s
+ ⠿ Container phpmyadmin Started 12.7s
+ ⠿ Container rap4 Started 12.9s
+ ⠿ Container enroll Started
+```
+
+Now, you need to "climb into" the rap4 container to execute one command manually:
+
+```bash
+docker exec -it rap4 bash
+```
+
+You now get a prompt like `root@bc774265c8ef:/usr/local/project#` that indicates that you are inside the rap4 container. Once inside, you need to give the following `chmod` command to enable RAP to generate prototypes.
+
+```bash
+chmod 666 /var/run/docker.sock
+```
+
+Finally, type exit to leave the rap4-container and return to the CLI of your laptop.
+
+Now you are done. Just check whether everything works:
+
+Type `localhost` in the URL-field of your browser, to see if RAP4 has started. You should see this:
+
+
+
+Note that RAP runs on the insecure `http://` instead of `https://`. This is not a problem if you keep your laptop safe from outsiders' trespassing. If you [deploy to a server](deploying-ounl-rap3.md), you need a secure setup.
+
+You will find that the database is accessible on `http://phpmyadmin.localhost`
+
+
+
+The demonstration application, Enrollment, is accessible on `http://enroll.localhost`
+
+
+
diff --git a/docs/the-tools-we-use/installation-of-rap/deployment-configuration.md b/docs/the-tools-we-use/installation-of-rap/deployment-configuration.md
new file mode 100644
index 0000000000..73e9017900
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/deployment-configuration.md
@@ -0,0 +1,14 @@
+# Deployment Configuration
+
+## Permissions for log files
+
+The docker configuration uses volumes to link to the file system of the host computer. As a result the status of RAP will survive containers \(i.e. you can start, stop, kill, restart containers without losing data\). However, you must ensure write permission for the container on runtime throughout all three subdirectories of the `volumes` directory. The pod in which RAP runs defines a volume called `log` in which the log files are written and a volume called `scripts` in which user scripts are stored. The pod in which MariaDB runs writes its `mysql`-directory to a volume called `mysql`. This means that the files are stored outside the container on the machine that hosts the docker platform.
+
+## Docker group
+
+You have a host computer in which the docker platform runs. \(In deploying RAP4 for the OUNL that would be the machine with domain name `rap.cs.ou.nl`\). To avoid permission errors \(and the use of `sudo`\), add your user to the `docker` group. [Read more](https://docs.docker.com/engine/installation/linux/linux-postinstall/).
+
+## Development vs. Production versions
+
+For developing RAP you use slightly different settings. For example you want to reset the database when developing, but this feature must be entirely impossible during production. For this purpose we have two source files: `RAP4dev.adl` and `RAP4prod.adl`. The only difference between the two is configuration settings. Follow the code to find out.
+
diff --git a/docs/the-tools-we-use/installation-of-rap/details.md b/docs/the-tools-we-use/installation-of-rap/details.md
new file mode 100644
index 0000000000..d24ee8ee6b
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/details.md
@@ -0,0 +1,61 @@
+# Details
+
+## What Docker needs to do...
+
+Docker is sheer magic. You don't have to understand it to run it. However, if you insist on knowing how it is done...
+
+Here are ten steps to install RAP4 manually, without Docker, on a freshly created server:
+
+### 1. Setting up a server
+
+You need a server that is connected to the internet, because RAP takes updates from a GitHub repository. A 2-core/8GB server is sufficient. A memory size under 3GB has shown to be insufficient. Ports for HTTP, HTTPS, SSL, and SFTP must be open.
+
+### 2. Getting MariaDB \(MySQL\) and phpMyAdmin to work
+
+You need a database and a web-server. This explains why a LAMP-server is an obvious choice if you use a preconfigured server.
+
+### 3. Uploading and running RAP4
+
+A quick way to install is to copy the source code of RAP4 on your server and compile it with Ampersand. That gives you the RAP4 webapplication. You will find the complete Ampersand source code of RAP4 on [https://github.com/AmpersandTarski/RAP](https://github.com/AmpersandTarski/RAP). The main file is `./RAP4/RAP4dev.adl` for the development version and `./RAP4/RAP4prod.adl` for the production version.
+
+### 4. Filling the Git repository with Ampersand files and Ampersand models
+
+If you don't have an Ampersand compiler, you can build one using the Haskell sources of that compiler. You will find the source code on the development branch of the Ampersand repository \([https://github.com/AmpersandTarski/Ampersand/tree/development](https://github.com/AmpersandTarski/Ampersand/tree/development)\). You can verify success by asking the Ampersand for its version:
+
+```text
+> ampersand --version
+Ampersand-v3.17.4 [master:fd90ea3f1], build time: 15-Nov-19 18:02:19 CET
+```
+
+If you don't have an Ampersand compiler, but docker runs on your machine, you can simply use the most recent ampersand compiler by
+
+```text
+> docker run -it ampersandtarski/ampersand
+```
+
+Use Git to create a local clone of these repositories. Git is preferred over copying the files, because you can repeatedly use it to ensure you get the right version.
+
+### 5. Avoiding to install Haskell
+
+To build an Ampersand compiler, you need Haskell. However, you can also use the latest executable Ampersand-compiler, which is published periodically on [http://ampersandtarski.github.io/](http://ampersandtarski.github.io/). This way, you don't need to build Ampersand and you can avoid installing Haskell.
+
+### 6. Creating an Ampersand compiler
+
+If you want, create your own Ampersand compiler. This way, you can pick a version by which to generate RAP4.
+
+### 7. Installing LaTeX and GraphViz
+
+LaTeX and GraphViz are called by RAP4 to generate documentation. Therefore, both must be installed on the server.
+
+### 8. Generating the RAP4 application
+
+You need to generate RAP4 to facilitate regular updates to the system.
+
+### 9. Local Settings
+
+Some local settings may apply, which are brought together in one file. Use this to administer things like database account\(s\) and PHP time limit, logging, etcetera.
+
+### 10. Last minute changes before going to production
+
+Things that are necessary for testing and development, such as logging, can be changed in the production version. These things are usually adapted shortly before going to production.
+
diff --git a/docs/the-tools-we-use/installation-of-rap/making-docker-images.md b/docs/the-tools-we-use/installation-of-rap/making-docker-images.md
new file mode 100644
index 0000000000..5b8e75aa5f
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/making-docker-images.md
@@ -0,0 +1,152 @@
+# Making Docker images
+
+## Docker images
+
+This chapter discusses the process of baking \(i.e. creating\) images for docker hub. It also gives a recipe for creating docker images. If you are interested only in installing RAP4, you do not need this chapter.
+
+Docker images are baked when the Ampersand source code for RAP4 is ready to be deployed. This results in three files, to be stored on Docker hub:
+
+
+
+## The release train
+
+RAP4 is deployed as shown in this picture
+
+
+
+## A recipe for creating images
+
+Knowing what needs to be done allows you to understand how we make Ampersand's docker images. If you just want to do it, follow the steps below. We assume that you are working on an Ubuntu machine with `bash` as its command line interface.
+
+### Check your Docker installation
+
+First I checked that docker and docker-compose are installed on my computer:
+
+```text
+sjo@lnx-hrl-202v:~$ which docker
+/usr/bin/docker
+sjo@lnx-hrl-202v:~$ which docker-compose
+/usr/bin/docker-compose
+```
+
+If you need to install docker, follow the instructions on [https://docs.docker.com/engine/installation](https://docs.docker.com/engine/installation) .
+
+### 4. Building an Ampersand image
+
+RAP is built on Ampersand and is compiled with Ampersand. For this reason, the RAP image builds on an Ampersand image. Run _./build.sh_ to build the initial ampersand container that serves as a base for the RAP4 application \(or any other Ampersand application\). This base images holds all required packages and the \(at that moment\) latest version of the ampersand compiler the workflow around this container can/should be improved since now the easiest way to rebuild is to remove the container \(_docker rmi ampersand:latest_\)
+
+### 4. Making a Docker image
+
+I cloned the docker files into a local directory by the following command:
+
+```bash
+sudo -i
+git clone https://github.com/AmpersandTarski/docker-ampersand/ /home/$(whoami)/docker-ampersand
+cd docker-ampersand/
+./build.sh
+```
+
+and sat back to watch an image being created. This takes over an hour. I left the session up and running, because stopping the session means that the docker build process stops. After coming back a day later, I verified that the image is present by running the same command again. That produced the following output:
+
+```text
+Wolfram docker-ampersand # docker build -t ampersand:latest ampersand
+Sending build context to Docker daemon 4.096 kB
+Step 1 : FROM php:7-apache
+ ---> 2720c02fc079
+Step 2 : ENV PATH /texlive/bin/x86_64-linux:$PATH
+ ---> Using cache
+ ---> 45d62477f5e2
+Step 3 : RUN apt-get update && apt-get install -y --no-install-recommends git graphviz wget xorriso && curl -sSL https://get.haskellstack.org/ | /bin/sh && rm -rf /var/lib/apt/lists/*
+ ---> Using cache
+ ---> e37542ec9301
+Step 4 : ENV TL_VERSION 2016-20160523
+ ---> Using cache
+ ---> f95346ded414
+Step 5 : ADD texlive.profile /tmp
+ ---> Using cache
+ ---> add9fd911c38
+Step 6 : RUN cd ~ && wget -q http://mirrors.ctan.org/systems/texlive/Images/texlive$TL_VERSION.iso && wget -qO- http://mirrors.ctan.org/systems/texlive/Images/texlive$TL_VERSION.iso.sha512 | sha512sum -c && osirrox -report_about NOTE -indev texlive$TL_VERSION.iso -extract / /usr/src/texlive && rm texlive$TL_VERSION.iso && /usr/src/texlive/install-tl -profile /tmp/texlive.profile && rm -rf /usr/src/texlive && rm /tmp/texlive.profile
+ ---> Using cache
+ ---> f0ebcd4cf50c
+Step 7 : RUN mkdir ~/git && cd ~/git && git clone --branch development https://github.com/AmpersandTarski/Ampersand
+ ---> Using cache
+ ---> 08643d5cce73
+Step 8 : RUN cd ~/git/Ampersand && stack setup && stack install --local-bin-path /usr/local/bin
+ ---> Using cache
+ ---> 636036e98214
+Step 9 : RUN php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php --install-dir=/usr/local/bin --filename=composer && php -r "unlink('composer-setup.php');"
+ ---> Using cache
+ ---> e8648c6657f6
+Successfully built e8648c6657f6
+```
+
+When you build an image where nothing changes \(as shown above\), this takes virtually no time at all. However, if you run a fresh image from scratch, it takes a while. Should you want to close your SSH-session in which docker is running, that docker process will be killed. If you want to leave docker running in the background, `https://www.tecmint.com/keep-remote-ssh-sessions-running-after-disconnection/` will help. Best thing is to anticipate on it. However, if you didn't anticipate this, you can still send docker to the background by `^Z` and give the `disown -h` command. \(The latter is however the least elegant way.\)
+
+I checked whether all images are built by the `docker images` command:
+
+```text
+sjo@lnx-hrl-202v:~/ampersand-models/RAP4$ docker images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+ampersandtarski/ampersand-rap latest 636643166a78 2 hours ago 3.62GB
+ampersandtarski/ampersand-prototype-db latest d267da36fb90 4 hours ago 395MB
+ampersandtarski/ampersand-prototype texlive efd0dccd6b4b 6 hours ago 3.11GB
+phpmyadmin/phpmyadmin latest 200931982ab6 6 days ago 110MB
+```
+
+### 5. Publishing to docker-hub
+
+For this step, you need an account on docker-hub. Then Docker will simply push the generated images to docker hub by means of the push-command:
+
+```text
+docker push ampersandtarski/ampersand-rap
+docker push ampersandtarski/ampersand-prototype-db
+docker push ampersandtarski/ampersand-prototype
+```
+
+At this point the images are published and this chapter is done. However, it is good to discuss a few collateral issues: deployment, maintenance and security.
+
+### 6. Deploying directly on this server
+
+We are making three containers: one for the database, one for the RAP4 application, and one for PhpMyAdmin. Containers are built from images by the command `docker-compose`:
+
+```text
+cd /home/ampersandadmin/docker-ampersand
+docker-compose up -d
+```
+
+This command brings all three containers up and runs them in the background. For this to happen, the file `docker-compose.yml` must be in the current directory.
+
+I checked whether the containers are running by means of the `docker ps` command.
+
+Completion of this step allowed access to RAP4 from an arbitrary computer on the internet:
+
+
+
+The database is accessible on port 8080:
+
+
+
+### 7. Maintenance
+
+The `docker-compose up` command aggregates the output of each container. When the command exits, all containers are stopped. Running `docker-compose up -d` starts the containers in the background and leaves them running.
+
+To interfere with RAP4 as it is running, you need to get into the Rap4 container. It is not enough just being on the server, because all the data is in the container \(rather than directly on the server\). To go into the Rap4 container, use the command
+
+```text
+docker exec -ti dockerampersand_rap4_1 /bin/bash
+```
+
+### 10. Local Settings
+
+To inspect and change the local settings, you need the file `localsettings.php` on directory `~/git/Ampersand-models/RAP4/include`. This step requires section 5 to be finished successfully. This file contains comments that guide you to use the correct settings in a development situation and in a production situation. Read the file and follow the instructions it contains, especially when making the transition from development to production.
+
+### 11. Last minute changes before going to production
+
+1. In the source code of RAP4, in the file SIAM\_importer.adl:
+ 1. disable "RAP4\_LoginForDevelopment.ifc", to prevent users from seeing
+ 2. enable "RAP4\_LoginForProduction.ifc"
+ 3. disable "../SIAM/SIAM\_AutoLoginAccount.adl"
+2. Is there anything we must alter in localsettings.php before going live?
+
+ This is decribed in the file `docker-compose.yml`
+
diff --git a/docs/the-tools-we-use/installation-of-rap/redeploying-rap3.md b/docs/the-tools-we-use/installation-of-rap/redeploying-rap3.md
new file mode 100644
index 0000000000..27efaaa391
--- /dev/null
+++ b/docs/the-tools-we-use/installation-of-rap/redeploying-rap3.md
@@ -0,0 +1,196 @@
+---
+description: >-
+ Once RAP4 is running, there are maintenance tasks you might want to do. The
+ most frequently used tasks are described here for RAP-3 maintainers to refer
+ to.
+---
+
+# Maintaining RAP4
+
+The purpose of maintaining software is to guarantee continuous operation for all users. In this chapter we use the RAP4 server at OUNL as an example, trusting that you will figure out what to do for servers of your own.
+
+## Tasks
+
+Here is an overview of all tasks described on this page. Refer to the related section below for details on each specific task
+
+1. Connect\
+ Before doing any maintenance, you need credentials to gain access to your server. Then you can connect to the server. We assume you gain access to a command-line interface (CLI) of your server. In this text that CLI is `/bin/bash` on a linux machine.
+2. Check the configuration\
+ When you start a maintenance session, you may want to check on the system. RAP4 runs in containers on a docker-platform, so you can check whether the containers are running and you can check the configuration in which they should be running.
+3. Upgrade to a new version of RAP
+4. Upgrade to a new version of Ubuntu
+5. Refresh the configuration\
+ Refreshing the RAP4 configuration is something you need to do only when developers tell you to do that.
+
+## Connecting to the RAP4 server
+
+The RAP-server has been configured to communicate via `ssh`. The Open Universiteit allows ssh-connections only through VPN. So I made sure my VPN-connection is active.
+
+I entered the server using command `ssh rap.cs.ou.nl` and the right user/password combination, upon which I gained access to the CLI.
+
+The RAP4-instance is installed from directory `~\RAP4`, which is the working directory from which maintenance is done.
+
+This is what you can expect to see:
+
+```
+stefjoosten$ ssh sjo@rap.cs.ou.nl
+sjo@rap.cs.ou.nl's password:
+Permission denied, please try again.
+sjo@rap.cs.ou.nl's password:
+Welcome to Ubuntu 16.04.3 LTS (GNU/Linux 4.4.0-124-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com
+ * Management: https://landscape.canonical.com
+ * Support: https://ubuntu.com/advantage
+
+170 packages can be updated.
+12 updates are security updates.
+
+New release '18.04.2 LTS' available.
+Run 'do-release-upgrade' to upgrade to it.
+
+
+Last login: Wed May 29 12:03:17 2019 from 145.20.142.195
+sjo@lnx-hrl-202v:~$cd RAP4
+sjo@lnx-hrl-202v:~/RAP4$
+```
+
+## Checking which containers are running
+
+The server should show at least two containers, a database container called `rap4_db` and a RAP-container called `rap4`. There may be a third container called `phpmyadmin`, which is there to gain access to the database (for maintainers only). To verify, give the command `docker ps`. This is what you may expect to see:
+
+```
+sjo@lnx-hrl-202v:~/RAP4$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+40e5e97c1b26 phpmyadmin/phpmyadmin "/run.sh superviso..." 4 months ago Up 36 seconds 9000/tcp, 0.0.0.0:8080->80/tcp rap3_phptools_1
+bff782b2da89 ampersandtarski/rap4-db "docker-entrypoint..." 4 months ago Up 2 weeks 3306/tcp rap3_db_1
+773f7ad86527 dockerampersand_rap3 "docker-php-entryp..." 18 months ago Up 2 weeks 0.0.0.0:80->80/tcp dockerampersand_rap3_1
+7525eb7ea95f dockerampersand_db "docker-entrypoint..." 18 months ago Up 2 weeks 3306/tcp dockerampersand_db_1
+sjo@lnx-hrl-202v:~/RAP4$
+```
+
+In this case it appears that a fourth container is running. This poses no problem, because other processes may run concurrently without interfering with RAP4.
+
+The configuration file that specifies this configuration is the only file in the working directory:
+
+```
+sjo@lnx-hrl-202v:~/RAP4$ ls -al
+total 20
+drwxrwxr-x 3 sjo sjo 4096 Oct 25 2018 .
+drwxr-xr-x 18 sjo sjo 4096 Jan 9 2018 ..
+-rw-rw-r-- 1 sjo sjo 472 Oct 25 2018 docker-compose.yml
+drwxr-xr-x 5 root root 4096 Dec 15 2017 volumes
+sjo@lnx-hrl-202v:~/RAP4$
+```
+
+By inspecting the contents you can see whether the configuration matches what you see in `docker`. This is what you can expect in `docker-compose.yml`:
+
+```
+sjo@lnx-hrl-202v:~/RAP4$ cat docker-compose.yml
+version: '3'
+
+services:
+ rap4:
+ restart: always
+ image: ampersandtarski/ampersand-rap:latest
+ ports:
+ - "80:80"
+ links:
+ - db
+ volumes:
+ - ./volumes/log:/var/www/html/RAP4/log
+ - ./volumes/scripts:/var/www/html/RAP4/scripts
+
+ db:
+ restart: always
+ image: ampersandtarski/rap4-db
+ volumes:
+ - ./volumes/mysql:/var/lib/mysql
+
+ phptools:
+ image: phpmyadmin/phpmyadmin
+ ports:
+ - "8080:80"
+ links:
+ - db
+sjo@lnx-hrl-202v:~/RAP4$
+```
+
+The directory `volumes` contains the Ampersand data, which is kept outside the containers so the data persists if containers get killed or if you restart the software.
+
+```
+sjo@lnx-hrl-202v:~/RAP4$ ls -al volumes/
+total 40
+drwxr-xr-x 5 root root 4096 Dec 15 2017 .
+drwxrwxr-x 3 sjo sjo 4096 Oct 25 2018 ..
+drwxr-xr-x 2 www-data www-data 4096 Dec 28 11:16 log
+drwxr-xr-x 229 999 999 20480 May 13 07:48 mysql
+drwxr-xr-x 75 www-data www-data 4096 Oct 25 2018 scripts
+sjo@lnx-hrl-202v:~/RAP4$
+```
+
+There are three data sets. The directory `log` contains logging information of the RAP4-server. The directory `mysql` contains the data from MariaDB. The directory `scripts` contains the student scripts and the files they generated when working in RAP4.
+
+## Upgrade to a new version of RAP
+
+If you need to upgrade RAP4 to the latest release run this command:
+
+```
+sjo@lnx-hrl-202v:~/RAP4$ docker-compose up -d
+```
+
+As you can see in the configuration (`docker-compose.yml`)
+
+## Upgrade to a new version of Ubuntu
+
+When you connect to the server, you get hints about the state your Ubuntu server is in. E.g.
+
+```
+% ssh sjo@rap.cs.ou.nl
+Welcome to Ubuntu 18.04.5 LTS (GNU/Linux 4.15.0-151-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com
+ * Management: https://landscape.canonical.com
+ * Support: https://ubuntu.com/advantage
+
+ System information as of Wed Aug 11 10:26:22 CEST 2021
+
+ System load: 0.08
+ Usage of /: 68.3% of 48.83GB
+ Memory usage: 17%
+ Swap usage: 0%
+ Processes: 264
+ Users logged in: 0
+ IP address for ens160: 145.20.188.96
+ IP address for br-0b19c7bfdba3: 172.20.0.1
+ IP address for br-0f95c427718c: 172.26.0.1
+ IP address for docker0: 172.17.0.1
+
+ * Canonical Livepatch is enabled.
+ - All available patches applied.
+
+84 packages can be updated.
+1 update is a security update.
+
+
+*** System restart required ***
+Last login: Mon Aug 2 11:14:56 2021 from 145.20.142.176
+sjo@lnx-hrl-202v:~$
+```
+
+In such cases you can update by giving two commands:
+
+```
+sjo@lnx-hrl-202v:~$ sudo apt update
+sjo@lnx-hrl-202v:~$ sudo apt upgrade
+```
+
+Sometimes a package is kept back because there is a problem with dependencies. You will have to upgrade such packages by hand.
+
+## Refreshing the code
+
+In the rare event that the configuration of RAP4 has changed (to be announced by the developers), you must update the file `docker-compose.yml`by hand, using the command:
+
+```
+wget https://raw.githubusercontent.com/AmpersandTarski/RAP/master/docker-compose.yml
+```
diff --git a/docs/the-tools-we-use/klad.md b/docs/the-tools-we-use/klad.md
new file mode 100644
index 0000000000..e873505333
--- /dev/null
+++ b/docs/the-tools-we-use/klad.md
@@ -0,0 +1,169 @@
+# Ampersand at the Open University of the Netherlands \(OUNL\)
+
+In early 2016 the need arose to replace the RAP2 implementation of Ampersand by a RAP3 implementation, because RAP2 was insufficiently maintainable. This environment is used by students for completing the course Rule Based Design \(OBR, code ...\). This implementation is hosted by ICTS, the IT-department of the university. We chose to implement RAP3 as a maintainable environment.
+
+This chapter is an account of the installation process. It serves the following purposes:
+
+1. It is an example for others who want to deploy Ampersand.
+ We get requests now and then by people who want to deploy Ampersand, so we figured it is nice to have a documented example for them.
+
+2. It documents the installation we made for the Open University.
+ We want maintenance of RAP3 to be transferrable to other persons, so we need to document the choices made and the reasons for making them.
+
+3. It contains all information needed to make a deployment script for automated deployment.
+ We want to automate deployment, so that RAP3 will always be up to date with the most recent stable release of Ampersand.
+
+Each step in the installation process gets a separate section in this text. It is not necessary to do them in the given order.dir
+
+## 1. Setting up a machine
+
+I got a server from the Open University's IT-department.
+
+The following settings apply:
+
+| | |
+| :--- | :--- |
+| server name | lnx-hrl-148v |
+| OS | SUSE Linux Enterprise Server 12 SP2, vs. 12.2 |
+| Admin user name | lru |
+| verification type | password \(Lloyd Rutledge knows the password\) |
+| Inbound port: HTTP | TCP/80 |
+| Inbound port: HTTPS | TCP/443 |
+| Inbound port: SSH | TCP/22 \(only via a VPN-tunnel\) |
+| Inbound port: SFTP | TCP/22 |
+| Public IP-adres | 145.20.188.148 |
+| PHP version \(RAP3 requires PHP version 5.6 or higher\) | 7.0.7 |
+
+| `{APPDIR}`= the directory into which RAP3 files will be deployed | /srv/www/htdocs |
+| :--- | :--- |
+| `{APPACC}`= the account under which the RAP3 application will run \(the apache account, i.e. ${APACHE\_RUN\_USER} c.q. ${APACHE\_RUN\_GROUP} as defined in apache2.conf\) | |
+| `{APPHOST}` = the URI of the machine that hosts the [RAP3 ](https://spreg.mydomain.org%29\)application \(e.g. 'mydomain.org', or 'rap3.mydomain.org'\) | |
+| `{APPPORT}` = the port at which the Apache server will be listening | 80 |
+| `{APPURI}` = the URI at which the RAP3 application will be accessible for browsers \(e.g. 'mydomain.org/[RAP3](https://spreg.mydomain.org%29\)', or '[RAP3](https://spreg.mydomain.org%29\).mydomain.org'\) | |
+| `{APPURL}` = the full name for calling the application \(e.g. [https://mydomain.org:8080/R](https://mydomain.org:8080/spreg)AP3', or [https://RAP3.mydomain.org\](https://spreg.mydomain.org%29\) | |
+
+I have checked that the server works by browsing to "[http://145.20.188.148/test.php](http://145.20.188.148/test.php)". I have been able to access this machine through SSH, using the Admin user name and password. I If have been able to access this machine through SSH \(using PUTTY\), but only after installing a VPN-tunnel to the server \(using Pulse Secure\). In the sequel, I will refer to this machine as "the server".
+
+## 2. Getting MariaDB \(MySQL\) and phpMyAdmin to work
+
+To run RAP3 requires Apache and MySQL. On a preinstalled MySQL-server you will need the database administrator password to set it up for Ampersand. This step requires hardware, so you must have finished section 1 successfully.
+
+On this server, there is no MySQL, so I had to install it. I followed the instructions on `https://en.opensuse.org/SDB:LAMP_setup#Setting_up_MariaDB`.
+
+First I installed `mariadb`and `mariadb-tools`:
+
+`sudo zypper in mariadb mariadb-tools`
+
+Then I started MariaDB:
+
+`lru@lnx-hrl-148v:~> sudo systemctl start mysql`
+
+To make sure the server will start at every boot:
+
+`lru@lnx-hrl-148v:~> sudo systemctl enable mysql`
+
+To set up MariaDB, I ran:
+
+`sudo mysql_secure_installation`
+
+By carefully following the instructions, I set up the MariaDB and chose root password `RAP3root`.
+
+However, here the procedure failed:
+
+`/usr/bin/mysql_secure_installation: line 234: .my.cnf.14336: No space left on device`
+
+After logging into phpMyAdmin, create a user called 'ampersand' with password 'ampersand' and host 'localhost', in compliance with the defaults used in the Ampersand compiler. RAP3 requires at least the following authorizations:
+
+
+
+As a consequence of these settings, users of RAP3 will not be able to reinstall RAP3, if we accidentally leave the "reinstall database" option alive.
+
+## 3. Uploading and running RAP3
+
+To run RAP3, the web-application must be installed on /srv/www/htdocs. This step requires sections 1 and 2 to be finished successfully. It also requires you to have a complete RAP3 web-application available for uploading to the server. If you don't have that web-application, you need to build it. Upon completion of step 9 you will have built that web-application by yourself.
+
+To upload RAP3, I followed the instructions on [https://docs.bitnami.com/azure/faq/\#how-to-upload-files-to-the-server-with-sftp](https://docs.bitnami.com/azure/faq/#how-to-upload-files-to-the-server-with-sftp) to upload the RAP3 web-application from my laptop onto the server. I put it on /srv/www/htdocs, which is the location of web-applications on this particular configuration. \(On vanilla Linux this would be on /var/www, I guess\). You must change the authorization of the 'log' directory \(.../htdocs/RAP3/log/\) to 757 \(public write access\) or else the application won't work. This screenshot should show the situation after the transfer \(TODO: update the screenshot\):
+
+You can test whether this is successful by browsing to `145.20.188.148/RAP3/`
+
+It should show \(TODO: update the screenshot\):
+
+
+
+If you need to restart the apache server for whatever reason, here is the command:
+
+`sudo rcapache2 restart`
+
+## 3. Installing Haskell
+
+In order to build an Ampersand-compiler, we need a Haskell installation. We only need a working machine, so this step merely requires section 1 to be finished successfully.
+
+You need Haskell stack for installing Haskell. I found stack already on this machine. It is installed as`/usr/local/bin/stack`.
+
+I did not get Haskell running.
+
+## 4. Filling the Git repository with Ampersand files and Ampersand models
+
+To build an Ampersand-compiler, we need the Ampersand source files, which reside in a GitHub repository. We can download these source files on a fresh server, so this step merely requires section 1 to be finished successfully. The RAP3 source files reside in a GitHub repository as well, so we'll just clone both repositories into the server.
+
+Git comes preconfigured in Bitnami's LAMP configuration. I have used Git on the command line to get the Ampersand source code and the Ampersand model repository cloned onto the server.
+
+I have created `/home/ampersandadmin/git` for storing the local clones. Here is what I did:
+
+`mkdir ~/git`
+
+`cd ~/git`
+
+`git clone https://github.com/AmpersandTarski/Ampersand`
+
+`git clone https://github.com/AmpersandTarski/Ampersand-models`
+
+This failed. The system says
+
+`Cloning into 'Ampersand'...`
+
+`error: copy-fd: write returned: No space left on device`
+
+`fatal: cannot copy '/usr/share/git-core/templates/description' to '/home/lru/git/Ampersand/.git/description': No space left on device`
+
+Upon success, the directory `/home/ampersandadmin/git/Ampersand` should contain the source code of the Ampersand compiler. The directory `/home/ampersandadmin/git/Ampersand-models` should contain the source code of the Ampersand models.
+
+## 5. Creating an Ampersand-compiler
+
+To generate RAP3 we need an Ampersand-compiler. The RAP3 user will also use that compiler. For both reasons, we need a working Ampersand compiler on the server. This step requires sections 3 and 4 to be finished successfully.
+
+With the source code of the Ampersand-compiler on the system, I tried to create an executable by running `stack install`. Here is what I did:
+
+`cd ~/git/Ampersand`
+
+`stack setup`
+
+`stack install`
+
+Something is still wrong, because this doesn't work.
+
+## 6. Installing LaTeX and GraphViz
+
+When the RAP3-user generates documentation, RAP3 will call on pdflatex, neato and dot. I found pdflatex already working. So I only had to install GraphViz. This can be done on a fresh server, so this step only requires section 1 to be finished successfully.
+
+For generating pictures, Ampersand needs the commands `dot` and `neato`. For that purpose I installed:
+
+```
+lru@lnx-hrl-148v:~> sudo zypper install graphviz
+```
+
+That too worked.
+
+##
+
+## 9. Generating the RAP3 application
+
+This step requires sections 4 and 5 to be finished successfully.
+
+## 10. Last minute changes before going to production
+
+1. In the source code of RAP3, in the file SIAM\_importer.adl, the interface RAP3\_LoginForDevelopment.ifc must be disabled and the interface RAP3\_LoginForProduction.ifc must be enabled.
+2. Is there anything we must alter in localsettings.php before going live?
+
+
+
diff --git a/docs/the-tools-we-use/making-images.md b/docs/the-tools-we-use/making-images.md
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/the-tools-we-use/onboarding/onboarding.md b/docs/the-tools-we-use/onboarding/onboarding.md
new file mode 100644
index 0000000000..422b412fb8
--- /dev/null
+++ b/docs/the-tools-we-use/onboarding/onboarding.md
@@ -0,0 +1,312 @@
+# Ampersand
+
+## Introductie
+Ampersand is een project van de Open Universiteit, ondersteund door Ordina en TNO. Het is een project dat niet financieel wordt ondersteund.
+
+Het onderzoek van Ampersand is gericht op het generen van informatiesystemen, rechtstreeks uit business rules, door middel van relatie-algebra. De Ampersand compiler is in staat om van een set business rules een database, back-end en front-end te genereren.
+
+- [Documentatie](https://ampersandtarski.github.io/)
+- [Documentatie (gitbook version)](https://ampersandtarski.gitbook.io/documentation/)
+- [Github project](https://github.com/AmpersandTarski)
+- [Docker hub](https://hub.docker.com/u/ampersandtarski)
+- [Wiki](https://github.com/AmpersandTarski/Ampersand/wiki)
+
+## RAP
+RAP is een speciale applicatie binnen het Ampersand project, daarom wordt deze los toegelicht.
+
+RAP is een Repository voor Ampersand-projecten, waarin studenten prototypes kunnen maken voor informatiesystemen die ze specificeren in Ampersand. Studenten en professionals gebruiken RAP om hun Ampersand-script in te dienen en te bewerken, te compileren, een prototype te genereren en te implementeren. Ze kunnen ook documentatie genereren vanuit hetzelfde Ampersand-script.
+
+RAP is in wezen een applicatie gegenereerd door Ampersand, met een aantal add-ons. De belangrijkste is dat aan RAP de Ampersand compiler is toegevoegd, waardoor nieuwe Ampersand applicaties gegenereerd kunnen worden.
+
+Gebruikers van RAP zijn vooral studenten van de Open Universiteit en geïnteresseerde professionals. De meeste gebruikers zijn nieuwelingen, die gemakkelijk de weg kwijtraken door relatief kleine belemmeringen.
+
+- [RAP4 applicatie Open Universiteit](https://rap.cs.ou.nl/#/page/home)
+
+## Aan de slag
+In de [documentatie](https://ampersandtarski.github.io/) vind je alle informatie nodig om het Ampersand project te leren kennen. De RAP applicatie van de Open Universiteit kan gebruikt worden om de applicatie te leren kennen.
+
+Als developer binnen het Ampersand project zul je de applicatie ook lokaal willen draaien.
+1. [The Tools We Use documentation](https://ampersandtarski.github.io/the-tools-we-use)
+
+De verschillende projecten binnen Ampersand hebben een eigen onboarding.
+
+## A-team
+Ampersand valt onder de paraplu van het A-team. Een team developers van de area MTech. Veelal Young Professionals en nieuwe Ordina collega's die beschikbaar zijn.
+
+Andere projecten die onder de paraplu van het A-team vallen:
+- NUTwente: platform die huisvesting van Oekrainse vluchtelingen in de omgeving Twente ondersteund. Looptijd: februari 2022 tot juli 2022, daarna onderhoudt.
+- Boswachter: ontwikkelen van een [website](https://www.ordina.com/who-we-are/social-responsibility/co2-neutral-by-2030/) die bezoekers informeert over de CO2-reductie ambitie van Ordina. Looptijd: december 2022 tot april 2023.
+
+## A-team projecten
+De projecten die door het A-team zijn opgepakt:
+
+### Front-end
+Het updaten van de Angular library die Ampersand gebruikt om de front-end te genereren. Deze werkt op basis van Angular-JS en wordt geupdate naar Angular versie 14.
+
+- [Repository](https://github.com/AmpersandTarski/prototype-frontend)
+- [Project](https://github.com/orgs/AmpersandTarski/projects/5)
+- [Onboarding](https://github.com/AmpersandTarski/prototype-frontend/tree/dev/docs)
+
+### Front-end testing
+Testen van de front-end met het Robot framework.
+
+- [Repository](https://github.com/AmpersandTarski/prototype-frontend)
+- [Project](https://github.com/orgs/AmpersandTarski/projects/8)
+- Onboarding
+
+### RAP testing
+Testen van de back-end met Gatling framework.
+
+- [Repository](https://github.com/AmpersandTarski/RAP)
+- [Project](https://github.com/orgs/AmpersandTarski/projects/4)
+- Onboarding
+
+
+### RAP deployment
+Het deployen van de RAP applicatie op een public cloud, bijvoorbeeld AWS of Azure. In kaart brengen welke opties er zijn (Docker en/of Kubernetes), architectuur schetsen en deployment werken krijgen.
+
+- [Repository](https://github.com/AmpersandTarski/RAP)
+- [Project](https://github.com/orgs/AmpersandTarski/projects/6)
+- [Onboarding](https://github.com/AmpersandTarski/RAP)
+
+
+# HPT / Scrum
+Het team in dit project werkt als een High Performance Team. Een klein multidisciplinair team die de Agile/Scrum methode hanteert.
+
+Zie de scrum gids voor achtergrondinformatie: [Nederlandse versie scrum gids](https://scrumguides.org/docs/scrumguide/v2020/2020-Scrum-Guide-Dutch.pdf)
+
+## Sprint
+De sprints zijn 2 weken waarbij op werkdagen altijd een daily stand-up plaatsvind van maximaal een half uur.
+
+Al het noodzakelijke werk wat nodig is om het Product Doel te bereiken, inclusief Sprint Planning, Daily Scrums, Sprint Review en Sprint Retrospective, vindt plaats binnen Sprints. Tijdens de Sprint:
+- Worden geen veranderingen aangebracht die het Sprint Doel in gevaar kunnen brengen;
+- Neemt de kwaliteit niet af;
+- Wordt de Product Backlog naar behoefte verder uitgewerkt;
+- Mag de scope worden verduidelijkt en heronderhandeld met de Product Owner naarmate meer
+wordt geleerd.
+
+## Sprint overzicht
+
+| | 1-Ma | 2-Di | 3-Wo | 4-Do | 5-Vr | 6-Ma | 7-Di | 8-Wo | 9-Do | 10-Vr |
+| ----- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ----- |
+| 9:00 | Zelfstudie | | | | | | | | Zelfstudy | Sprint review |
+| 10:00 | Zelfstudie | | | | | | | | Zelfstudy | Planning voorb. |
+| 11:00 | Zelfstudie | | | | | | | | Zelfstudy | Sprint planning |
+| 11:30 | Wekelijks overleg | Daily | Daily | Daily | Daily | Wekelijks overleg | Daily | Daily | Daily | Daily |
+| 13:00 | Zelfstudie | Scrum Poker | | | | | | | Zelfstudy | Sprint retro
+
+Een nieuwe sprint begint bij de sprint planning, de vaste activiteiten in chronologisch volgorde:
+
+### Daily
+Het doel van de Daily Scrum is om voortgang richting het Sprint doel te inspecteren en de Sprint Backlog als nodig aan te passen, waarbij het aankomend gepland werk wordt bijgesteld. De Daily Scrum is een gebeurtenis van 15 minuten voor de Developers van het Scrum Team.
+
+### Wekelijks overleg
+Tijdens de daily van maandag zijn de product owners aanwezig ter ondersteuning van het proces en voor inhoudelijke vragen.
+
+### Scrum poker
+Tijdens scrum poker worden gewicht gehangen aan (nieuwe) backlog items. Gaat alleen door als er backlog items zijn om mee te pokeren.
+
+| Poker | Duur |
+| ----- | ---- |
+| 1 | ? uur |
+| 2 | ? uur |
+| 3 | ? uur |
+| 5 | ? uur |
+| 8 | ? uur |
+| 13 | ? uur |
+| 21 | ? uur |
+
+### Sprint review
+Het doel van de Sprint Review is om de uitkomst van de Sprint te inspecteren en toekomstige aanpassingen te bepalen. Het Scrum Team presenteert de resultaten van hun werk aan de belangrijkste belanghebbenden en de voortgang richting het Product Doel wordt besproken.
+
+Een wordt een korte powerpoint presentatie voorbereidt, een kopie wordt opgeslagen in Teams *Project A & NUT-Vluchtelingen opensource*. Hier is ook een template te vinden.
+
+Tijdens de sprint review zijn Joost, Han en Michiel aanwezig in de rol van belanghebbende.
+
+### Sprint planning voorbereiding
+Het uur voorafgaand van de sprint planning. Naar aanleiding van de sprint review wordt het backlog aangepast en het sprint board voorbereidt. Dit voorkomt dat we tijdens de sprint planning te veel bezig zijn met het backlog / sprint board.
+
+### Sprint planning
+Sprint Planning start de Sprint door het uit te voeren werk voor de Sprint uit te stippelen. Het resulterende plan wordt gemaakt door het gezamenlijke werk van het gehele Scrum Team.
+
+Sprint Planning behandelt de volgende onderwerpen:
+1. Waarom is deze sprint waardevol?
+2. Wat kan deze Sprint worden afgerond?
+3. Hoe zal het gekozen werk gedaan worden?
+
+Het Sprint Doel, de Product Backlog items die geselecteerd zijn voor de Sprint, plus het plan hoe ze worden opgeleverd, worden gezamenlijk de Sprint Backlog genoemd.
+
+Tijdens de sprint review zijn Joost, Han en Michiel aanwezig in de rol van Product Owner.
+
+### Sprint retrospective
+Het doel van de Sprint Retrospective is om manieren te bedenken om kwaliteit en effectiviteit te verhogen en in te plannen.
+
+Voor de retrospective wordt in de Teams chat *NUTwente ontwikkelteam* een nieuw Whiteboard aangemaakt, met sjabloon *Terugblik zeilboot*. Achtereenvolgend worden sterke punten, successen, obstakels, ankers en doelen/visie ingevuld en gereflecteerd.
+
+Een copy van het Whiteboard wordt opgeslagen in Teams *Project A & NUT-Vluchtelingen opensource*.
+
+### Zelfstudie
+Dit project is bedoeld ter ondersteuning van Young professionals en (nieuwe) werknemers van Ordina die beschikbaar zijn. Van Young professionals wordt verwacht dat ze tijd besteden aan zelfstudie.
+
+Elke deelnemer aan het project geeft (per sprint) aan hoeveel tijd hij/zij beschikbaar heeft. Om zelfstudie zo goed mogelijk te faciliteren, zijn er standaard 2 zelfstudiedagen ingepland.
+
+# Scrum team
+De fundamentele eenheid van Scrum is een klein team van mensen; een Scrum Team. Normaliter bestaat het Scrum Team uit één Scrum Master, één Product Owner en Developers. Door de aard van het Ampersand project heeft eht project niet één, maar drie Product Owners. Daarnaast zijn de Developers vaak kortdurend (2-6 maanden) aan het project verbonden.
+
+## Developers
+De specifieke vaardigheden die nodig zijn voor de Developers, zijn vaak breed en variëren met het domein van het werk. Developers zijn altijd verantwoordelijk voor:
+- Het creëren van een plan voor de Sprint; de Sprint Backlog;
+- Het garanderen van kwaliteit door vast te houden aan een Definition of Done;
+- Het dagelijks aanpassen van hun plan richting het Sprint Doel;
+- Het elkaar verantwoordelijk houden als professionals.
+
+Developers die aan Ampersand werken of hebben gewerkt:
+
+| Naam | Project(en) | Start | Eind |
+| ---- | ------- | ----- | ---- |
+| **Andre de Nijs** | Coach | 01/09/2022 | - |
+| Bas Plijnaer | RAP deployment | 01/09/2022 | 31/10/2022 |
+| Dirk Suelmann | Front-end | 07/11/2022 | 16/12/2022 |
+| **Emre Gul** | Testen Front-end | 16/12/2022 | - |
+| **Frank Teusink** | RAP deployment | 17/02/2023 | - |
+| **Freek Rodenburg** | RAP deployment | 07/11/2022 | - |
+| Jesse Zwitserlood | RAP deployment | 01/09/2022 | 10/11/2022 |
+| Kemal Yildiz | Testen RAP | 07/11/2022 | 30/12/2022 |
+| **Li-Wei Yeh** | Front-end | 01/09/2022 | - |
+| Mark van der Hart | Front-end | 01/09/2022 | 30/11/2022 |
+| **Martijn van Andel** | Front-end | 17/01/2023 | - |
+| Naomi Prins | Front-end | 07/11/2022 | 16/12/2022 |
+| Patrick Ramge | Front-end, RAP | 01/09/2022 | 30/12/2022 |
+| **Sheriff Balunywa** | Front-end | 16/12/2022 | - |
+| Sharvin Ramdat | Testen RAP, Testen front-end | 01/10/2022 | 13/01/2023 |
+
+## Product owner(s)
+De Product Owner is verantwoordelijk voor het maximaliseren van de waarde van het product, dat het resultaat is van het werk van het Scrum Team. Hoe dit wordt gedaan, kan sterk uiteenlopen tussen organisaties, Scrum Teams en individuen.
+
+De Product Owner is ook verantwoordelijk voor effectief Product Backlog management, wat het volgende omvat:
+- Het ontwikkelen en duidelijk overbrengen van het Product Doel;
+- Het creëren en helder overbrengen van Product Backlog items;
+- Het ordenen van Product Backlog items;
+- Het ervoor zorgen dat de Product Backlog transparant en zichtbaar is en begrepen wordt.
+
+In het Ampersand project wordt echter ook van de developers verwacht zich actief bezig te houden met de inhoud van het backlog.
+
+Product owners Ampersand project:
+- [Stef Joosten](mailto:stef.joosten@ordina.nl)
+- [Han Joosten](mailto:han.joosten@ordina.nl)
+- [Michiel Stornebrink](mailto:michiel.stornebrink@tno.nl)
+
+## Scrum master
+De Scrum Master is verantwoordelijk voor het opzetten van Scrum, zoals staat beschreven in de Scrum Gids. Scrum Masters doen dit door iedereen te helpen om Scrum theorie en praktijk te begrijpen, zowel binnen het Scrum Team als binnen de organisatie.
+
+De Scrum Master is verantwoordelijk voor de effectiviteit van het Scrum Team. Scrum Masters doen dit door het Scrum Team in staat te stellen zijn werkwijzen te verbeteren binnen het Scrum raamwerk.
+
+In het Ampersand project is geen vast scrum master, deze wisselt daarom per sprint. Van de developer die de rol scrum master wordt toebedeeld, wordt verwacht dat deze hier tijd voor inpland en dit als een leerdoel ziet.
+
+| Sprint | Start | Eind | Scrum master |
+| ---- | ------- | ----- | ---- |
+| 8 | 21/11/2022 | 02/12/2022 | Li-Wei Yeh |
+| 9 | 05/12/2022 | 16/12/2022 | Freek Rodenburg |
+| 10a | 19/12/2022 | 30/12/2022 | Patrick Ramge |
+| 10b | 02/01/2023 | 15/01/2023 | Li-Wei Yeh |
+| 11 | 15/01/2023 | 29/02/2023 | Sherrif Balunywa |
+
+## Business Analyst
+De Business Analyst heeft als taak systemen en processen te verbeteren. Zij doet dit door de brug te zijn tussen de product owners en developers. Taken af te stemmen en het backlog te beheren.
+
+Business analisten die aan Ampersand werken of hebben gewerkt:
+
+| Naam | Start | Eind | Uren /week |
+| ---- | ----- | ---- | ---------- |
+| Manon de Willigen | 12/12/2022 | - | 4 |
+
+## Belanghebbenden / stakeholders
+Elk project heeft belanghebbenden, bijvoorbeeld de opdrachtgever en/of gebruikers.
+
+Belanghebbenden van het Ampersand project:
+- Open Universiteit: vertegenwoordigd door [Stef Joosten](mailto:stef.joosten@ordina.nl)
+- TNO: vertegenwoordig door [Michiel Stornebrink](mailto:michiel.stornebrink@tno.nl)
+
+# Backlog / Scrum board / issues
+
+Taken worden bijgehouden op de bijbehorende [project pagina](https://github.com/orgs/AmpersandTarski/projects). Elke taak die aangemaakt wordt op het backlog is direct ook een issue in de repository dat hoort bij het project.
+
+Issues en backlog items, moeten aan bepaalde voorwaarden voldoen. Een issue moet self-explaining zijn, daarvoor zijn een aantal templates gemaakt.
+
+## Backlog: epic
+```
+# What is purpose: why do we need it?
+
+# List of user stories / tasks
+
+# What is the result?
+```
+
+## Backlog: user story / task
+```
+# What is the purpose: why do we need it?
+
+# How to acclompish the task
+
+# List of subtasks
+
+# What is the result?
+```
+
+## Issue: Bug report
+```
+<!-- Thanks for contributing to this project! Please pick a clear title and proceed.-->
+<!-- Please note: If your issue is about RAP3, please report it over there:-->
+<!-- https://github.com/AmpersandTarski/RAP/issues -->
+
+# What happened
+
+# What I expected
+
+# Version of ampersand that was used
+
+# Steps to reproduce
+
+1.
+2.
+3.
+4.
+
+# Screenshot / Video
+
+# Context / Source of ampersand script
+<!-- Optional: share your script if possible. It helps us reproduce the problem. Please try to keep the scripts tiny-->
+
+<!-- We'd also love to know how you found the bug: #dogfooding, #manual-testing, #automated-testing, or #user-report if applicable.-->
+
+<!-- If requesting a new feature, explain why you'd like to see it added.-->asdf
+```
+
+## Issue: Comment / error /typo in the documentation
+```
+<!-- Thanks for contributing to this project! We are happy with your comments on the documentation. Please pick a clear title and proceed.-->
+
+# What is the page that your suggestion is about?
+
+# What Is your comment?
+<!-- You can provide sceenshots, or whatever you think is helpful to us to do better --!>
+```
+
+## Issue: Feature request
+```
+**Is your feature request related to a problem? Please describe.**
+
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+**Describe the solution you'd like**
+
+<!-- A clear and concise description of what you want to happen. -->
+
+**Describe alternatives you've considered**
+
+<!-- A clear and concise description of any alternative solutions or features you've considered. -->
+
+**Additional context**
+
+<!-- Add any other context or screenshots about the feature request here. -->
+```
\ No newline at end of file
diff --git a/docs/the-tools-we-use/prototype-framework.md b/docs/the-tools-we-use/prototype-framework.md
new file mode 100644
index 0000000000..90f3954581
--- /dev/null
+++ b/docs/the-tools-we-use/prototype-framework.md
@@ -0,0 +1,32 @@
+# Prototype framework
+
+## Backend implementation \(PHP\)
+
+### Structure of project folder
+
+```text
+|-
+|-
+|-
+```
+
+### Errors and exceptions
+
+* In the code of the prototype framework \(php\), around 250 places exist where an exception is thrown. Exceptions are thrown with a message and code. For the code we reuse the [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes), to have clear semantics and to determine which error is returned to the user.
+* Codes 4xx are bad request by the user, and result in an error which is always shown in full details to the user. E.g.
+ * "404 Resource not found" when a user requests an atom which does not exist.
+ * "403 You do not have access to this page" when a user doesn't have the required ROLE
+ * "400 Data entry too long"
+* Codes 5xx are server side errors, and indicate a programming error which is \(in most cases\) not caused by user input. These exceptions can give away how the code is structured, which is why depending on the `debugMode` settings, the error message is shown to the user or not. In case `debugMode` is off, a generic message is shown: 'An error occured \(debug information in server log files\)'. When debugMode is on, the user can click on the error message and see the stack trace.
+* The log files always contain details about the exception.
+* All exceptions are caught by the API framework we use, and transformed into a json structure for the frontend.
+* As php code is compiled at runtime, the prototype framework can contain errors that can't be caught and/or handled by the API framework. This especially holds for errors early in the execution, when initializing the API framework or AmpersandApp object.
+* We use a [static analyzer](https://github.com/phan/phan) to check the code during development. This prevents us from introducing bugs that can be detected by such an analyzer \(which is actually a lot\).
+ * At most class methods we specify input and return type definitions. This improves the static analyses.
+
+## Frontend implementation \(AngularJS\)
+
+### Building and packaging the application
+
+TODO explain: Bower, NPM, Gulp
+
diff --git a/docs/the-tools-we-use/rap3-student.md b/docs/the-tools-we-use/rap3-student.md
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/the-tools-we-use/rap3-tutor.md b/docs/the-tools-we-use/rap3-tutor.md
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/the-tools-we-use/releasing-ampersand-and-workflow-details.md b/docs/the-tools-we-use/releasing-ampersand-and-workflow-details.md
new file mode 100644
index 0000000000..874d30bb89
--- /dev/null
+++ b/docs/the-tools-we-use/releasing-ampersand-and-workflow-details.md
@@ -0,0 +1,44 @@
+---
+description: >-
+ This page is a work instruction for whoever does the periodic release. We use
+ github actions to do a release. The aim is to do a release every 4 weeks, but
+ it depends on the need to do so.
+---
+
+# How to release an Ampersand upgrade
+
+## Branching strategy
+
+- Use your own feature branch to experiment. You will typically spawn it from the main branch. Commit your branch frequently, so other team members can see what you are doing and help out if needed.
+- If you intend to merge your results somewhere in the future, describe your intentions now in the file `ReleaseNotes.md` in the root of the repository (in your own branch, of course). This ensures that these release notes will be merged into the main branch when the time is there.
+- Use a pull request to announce that you want to merge your branch into the main branch.
+- Take ownership of your branch(es). Ask for help to ensure progress and direction.
+- The main branch is used only for code that is ready for release. @hanjoosten is currently the primary guardian of the release process.
+- The [Ampersand repository at Github](https://github.com/AmpersandTarski/Ampersand/) contains the authoritative source code of Ampersand.
+
+## Releasing at Github
+
+We release Ampersand in arbitrary time intervals. This is done by attaching a release label to the appropriate commit in the main branch.
+
+## Pre-release steps (what to do)
+
+1. In `development` branch, modify the following files[1](releasing-ampersand-and-workflow-details.md#myfootnote1):
+ - `package.yaml` :
+ - Change the version number to the next release number.
+ - `ReleaseNotes.md` :
+ - Rename the "unreleased changes" section to the new version
+ - Add a new "unreleased changes" section for the next release.
+2. Push your modifications to GitHub. This will trigger automated testing.
+3. Ensure that the build is succesfully:
+ - [Check the build](https://github.com/AmpersandTarski/Ampersand/actions) (this could take up to an hour)
+4. Create a pull request to the [master from the compare with development](https://github.com/AmpersandTarski/Ampersand/compare/master...development)
+
+[2](releasing-ampersand-and-workflow-details.md#myfootnote2)
+
+
+
+Press the green button to create the pull request. We create a pull request so the release leaves a proper administrative trail in GitHub, and it triggers the actual release.
+
+Notes, tips and tricks:
+
+[1](releasing-ampersand-and-workflow-details.md): Looking for `package.yaml` and `ReleaseNotes.md`? Want to know where they are located? Look in Github for the commit of the previous release. It shows changes were made to these files. From there, open their current (!) version. Please make sure your Git is working in the development branch. [2](releasing-ampersand-and-workflow-details.md): This and most of the following actions are done from within the ampersand repository at github. [3](releasing-ampersand-and-workflow-details.md): At the bottom of the page in GitHub, you will find the buttons to merge this release. Please drop a note to describe new features.
diff --git a/docs/the-tools-we-use/tools-used-in-the-ampersand-project.md b/docs/the-tools-we-use/tools-used-in-the-ampersand-project.md
new file mode 100644
index 0000000000..52aa8f7e12
--- /dev/null
+++ b/docs/the-tools-we-use/tools-used-in-the-ampersand-project.md
@@ -0,0 +1,41 @@
+---
+description: >-
+ This page lists the tools that are used and for which purpose they are used.
+ This list is intended for reference, so it is full of hyperlinks that can
+ point you to the right location.
+---
+
+# Tools used in the Ampersand project
+
+## Specific tools used in the Ampersand project
+
+| Tool | Purpose |
+|-----------------------|-----------------------------|
+| [Ampersand image](https://hub.docker.com/r/ampersandtarski/ampersand-prototype/) | A docker-image in which we keep the latest version of the Ampersand compiler in executable form. It resides in [docker-hub](https://hub.docker.com/r/ampersandtarski/ampersand/).
+| Ampersand compiler | An executable that is used to generate software, documentation, and analyses from Ampersand-scripts. It is embedded into the Ampersand image and into RAP3. There exist multiple instances, so we cannot hyperlink to it.
+| [Ampersand repository](https://github.com/AmpersandTarski/Ampersand/) | A repositoryin which we keep Ampersand source codeand manage the issues wrt Ampersand.
+| [Docker Hub](https://hub.docker.com/u/ampersandtarski/) | A repository in which we keep [Ampersand images](installation-of-rap/making-docker-images.md)
+| [Rule Based Design](https://www.ou.nl/-/IM0403_Rule-Based-Design) | A course at the Open Universiteit.
+| [GitHub](https://github.com/AmpersandTarski/) | An organisation in which we keep all Ampersand git-repos.
+| [RAP3](http://ampersand.tarski.nl/RAP3/) | A [web-based application, generated with Ampersand](functionality-of-rap3/) for the public at large to use Ampersand. This instance is also used as acceptation environment for [the RAP instance for students](http://rap.cs.ou.nl/RAP3) in the course [Rule Based Design](https://www.ou.nl/-/IM0403_Rule-Based-Design).
+| [RAP](http://rap.cs.ou.nl) | A [web-based application, generated with Ampersand](functionality-of-rap3/) that is used as production environment for students in the course [Rule Based Design](https://www.ou.nl/-/IM0403_Rule-Based-Design).
+
+
+## Generic tools used in the Ampersand project
+
+| Tool | Purpose
+|-----------------------|----------------------|
+| [ACE](https://ace.c9.io/) | A web-editor that is used within RAP. It has been integrated in the RAP-application code.
+| [Docker](https://www.docker.com/) | The platform for technology agnostic, fully automated deployment of services, which we use to deploy the Ampersand compiler and applications developed in Ampersand.
+| [Docker-compose](https://docs.docker.com/compose/) | A platform for configuring services in a full-fledged application such as RAP.
+| [Git](https://git-scm.com/community) | The versioning system in which all source code is kept. It enables us to work collaboratively on multiple features in parallel, without interfering each other\'s work.
+| [Graphviz](https://www.graphviz.org/) | A system for generating diagrams, which is used to generate conceptual models and data models as part of the documentation generator.
+| [Haskell](https://www.haskell.org/) | The programming language in which the Ampersand compiler is built and maintained.
+| [Kubernetes](https://kubernetes.io/) | A platform for configuring and managing deployed services (such as RAP) in an operational environment. Kubernetes is not being used yet in production instances of Ampersand.
+| [MariaDB](https://mariadb.org/) | The database that is used by Ampersand for persistency. This used to be MySQL, until MariaDB took over in the Open Source community.
+| [Markdown](https://www.markdownguide.org/) | The language in which Ampersand documentation is written. We use it for maximal portability of text over different platforms.
+| [Node.js](https://nodejs.org/) | The JavaScript framework in which an Ampersand Prototype is generated.
+| [Pandoc](https://pandoc.org/) | A system for document translation and markup, which we use to create a host of different document formats.
+| [Stack](https://www.haskellstack.org/) | A build automation environment for Haskell that we use to build the Ampersand compiler with. It guarantees consistency of module dependencies within the Haskell world.
+| [VS-code](https://code.visualstudio.com/) | An editor for development of the Ampersand compiler and Ampersand-projects. A VScode extension for Ampersand exists that offers syntax coloring and other language specific features.
+
diff --git a/docs/tutorial-rap4.md b/docs/tutorial-rap4.md
index 245465f3b3..5f7b957492 100644
--- a/docs/tutorial-rap4.md
+++ b/docs/tutorial-rap4.md
@@ -1,21 +1,19 @@
# Tutorial
-* Ampersand is meant to develop information systems.
-* This tutorial will get you going with Ampersand. Consult your tutor with questions.
-* You have a [tool](#your-tool-rap4) to experiment with, supplemented by this video (in Dutch) to make your start even easier:
+- Ampersand is meant to develop information systems.
+- This tutorial will get you going with Ampersand. Consult your tutor with questions.
+- You have a [tool](#your-tool-rap4) to experiment with, supplemented by this video (in Dutch) to make your start even easier:
<iframe width="100%" height="444" src="https://www.youtube.com/embed/ZISLjxJqkqw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
-
This tutorial is meant for Business- or IT professionals who want to learn about [information systems](https://player.ou.nl/wowzaportlets/#!production/BDAXK2L) development. Knowledge about Ampersand is not presumed. The text offers pointers for you to find out many things on your own. This tutorial is intended for individual study, but you can always ask your tutor if things are unclear. The required theory is also available in Learning Unit 3 of the coursebook of the course [IM0403, Rule-Based Design](https://www.ou.nl/-/IM0403_Rule-Based-Design), taught at the Open University of the Netherlands.
-
## Overview
1. You will start by [looking at an information system called "Enrollment"](#example-system-enrollment) and learn the basics of its specification. By looking at a small information system you can discuss the purpose of the course with your tutor and peers.
2. Then you will be introduced to the web-based version of Ampersand, [RAP 4](#your-tool-rap4), in which you can specify an information system and create a working web-based prototype. With this tool, you can make information systems of your own, enabling you to complete the course.
-3. Next, we will have a look at [the conceptual model](#conceptual-model-enrollment) behind the Enrollment system. You will learn to interpret a rule based on the given concepts and relations. You will see some basics of relational algebra.
-4. You will [learn how to analyse a "spreadsheet information system"](/ampersand/reference-material/syntax-of-ampersand#population-in-spreadsheets) and turn it into a well defined information system. This technique allows you to help organizations with organizing and structuring data.
+3. Next, we will have a look at [the conceptual model](#conceptual-model-enrollment) behind the Enrollment system. You will learn to interpret a rule based on the given concepts and relations. You will see some basics of relational algebra.
+4. You will [learn how to analyse a "spreadsheet information system"](./reference-material/syntax-of-ampersand#population-in-spreadsheets) and turn it into a well defined information system. This technique allows you to help organizations with organizing and structuring data.
5. You will learn how to add rules to your data. This will allow you to add meaning to your information system, because you can assure your user community that these rules will remain satisfied.
## Example system: Enrollment
@@ -28,26 +26,26 @@ Try it out on an Ampersand implementation. Copy this example code, make a new sc
### Assignment
-* Who are the three students and what are the courses they take?
-* Is there a module `HRM`?
- * Add, in the tab Course, the module HRM to the Management course. The system sees that the subject is unknown, and provides a green plus-sign to add it.
- * Each change will be saved automatically.
- * Note that this change is also visible in the tab Modules.
-* Now enroll student `John` for the module `Business Rules`. You can do this either in the tab Students or the tab Modules. We will later see why this is the case.
-* Now enroll student `Peter` for the module `Business Rules`.
- * This will trigger a message because this student does not take the course Business IT.
- * Click on the message to see details.
- * Look-up in the code below where this message is defined. It is the line that starts with `RULE`. You don't have to understand the syntax at this point.
- * Click cancel.
-* Use the trash can icon to remove the course `Business IT` from`Susan` in the tab Students.
- * This also will trigger an error message because each student can only enroll for a module in courses he has registered in. Get rid of the message by going to the "List all interfaces" in the menu bar and navigate back to the overview.
- * Look up in the code the definition of the `RELATION takes`. The keyword `[TOT]` is responsible for this message.
-* Note the four icons on the top-right of the screen and click on the second icon (nine dots).
- * Click on 'Reinstall database'
- * The Installer screen comes up. Click on the big red button and wait for it to turn green.
- * Click on 'overview' and the initial data is back.
- * Have a look at the code below, to find where the initial data is defined.
-* Have a look at the code-part at the end called INTERFACE and compare it with the screen. Note which parts you recognize. The syntax of the code is discussed in the documentation.
+- Who are the three students and what are the courses they take?
+- Is there a module `HRM`?
+ - Add, in the tab Course, the module HRM to the Management course. The system sees that the subject is unknown, and provides a green plus-sign to add it.
+ - Each change will be saved automatically.
+ - Note that this change is also visible in the tab Modules.
+- Now enroll student `John` for the module `Business Rules`. You can do this either in the tab Students or the tab Modules. We will later see why this is the case.
+- Now enroll student `Peter` for the module `Business Rules`.
+ - This will trigger a message because this student does not take the course Business IT.
+ - Click on the message to see details.
+ - Look-up in the code below where this message is defined. It is the line that starts with `RULE`. You don't have to understand the syntax at this point.
+ - Click cancel.
+- Use the trash can icon to remove the course `Business IT` from`Susan` in the tab Students.
+ - This also will trigger an error message because each student can only enroll for a module in courses he has registered in. Get rid of the message by going to the "List all interfaces" in the menu bar and navigate back to the overview.
+ - Look up in the code the definition of the `RELATION takes`. The keyword `[TOT]` is responsible for this message.
+- Note the four icons on the top-right of the screen and click on the second icon (nine dots).
+ - Click on 'Reinstall database'
+ - The Installer screen comes up. Click on the big red button and wait for it to turn green.
+ - Click on 'overview' and the initial data is back.
+ - Have a look at the code below, to find where the initial data is defined.
+- Have a look at the code-part at the end called INTERFACE and compare it with the screen. Note which parts you recognize. The syntax of the code is discussed in the documentation.
This information system was built by the following code:
@@ -61,13 +59,13 @@ Students of a course can enroll for any module that is part of the course.
PATTERN Courses
-- The concepts
CONCEPT Student "Someone who wants to study at this institute"
-PURPOSE CONCEPT Student
+PURPOSE CONCEPT Student
{+We have to know what person studies at this institute, so the system needs to keep track of them.+}
CONCEPT Course "A complete course that prepares for a diploma"
-PURPOSE CONCEPT Course
+PURPOSE CONCEPT Course
{+We have to know what courses there are, so the system needs to keep track of them.+}
CONCEPT Module "An educational entity with a single exam"
-PURPOSE CONCEPT Module
+PURPOSE CONCEPT Module
{+We have to know what modules exist, so the system needs to keep track of them.+}
-- The relations and the initial population
@@ -127,7 +125,7 @@ ENDCONTEXT
## Your tool: RAP4
-This section introduces the tool you will use during the course: RAP4. This tool stores Ampersand-scripts in which you can specify, analyze and build information systems. It runs on the internet, so all you need is a browser. [Click here if you are a student of the Open University](https://rap.cs.ou.nl) or [here if you are not](https://rap.cs.ou.nl) to start using it.
+This section introduces the tool you will use during the course: RAP4. This tool stores Ampersand-scripts in which you can specify, analyze and build information systems. It runs on the internet, so all you need is a browser. [Click here if you are a student of the Open University](https://rap.cs.ou.nl) or [here if you are not](https://rap.tarski.nl) to start using it.
RAP4 is under development. New releases can be done daily. If you find problems with the software, please notify your tutor. If the software is to blame, we will ask you to [make an issue in RAP's issue registration system](https://github.com/AmpersandTarski/RAP/issues). This way you can help improve Ampersand's tooling, for which the Ampersand team is very grateful.
@@ -145,11 +143,12 @@ Register with your own student number and e-mail. Create a password. Your studen
Notes:
-* About the user interface: Each time you change fields (e.g. using Tab), the form is updated. But you will not see what is the next active field. You may have to click again to ensure that your cursor is in the right field.
-* This application has no connection with the OU database, so be careful to fill in the right number on this and future occasions.
+- About the user interface: Each time you change fields (e.g. using Tab), the form is updated. But you will not see what is the next active field. You may have to click again to ensure that your cursor is in the right field.
+- This application has no connection with the OU database, so be careful to fill in the right number on this and future occasions.
- This login-screen is also the screen to logout later.
-* When RAP4 is updated, probably your account will be reset. You need to register again. We will inform you in the unlikely event that this happens during a course.
+ This login-screen is also the screen to logout later.
+
+- When RAP4 is updated, probably your account will be reset. You need to register again. We will inform you in the unlikely event that this happens during a course.
@@ -161,14 +160,14 @@ After logging in, you will see your login name or student number in the RAP4 win
In the menu bar you will find:
-* A horn symbol. Just ignore that for now, because it contains debug settings.
-* a 3x3 grid, which contains some Ampersand extensions.
-* a plus (+) symbol. That is important, because it lets you create a new Ampersand script.
-* a person-like symbol. It lets you switch on/off some role dependent functionalities. If you have more than one role, just try it out and watch functionalities appear and disappear from the menu bar. As a student you typically have just one role (User) so this button is not very relevant for you.
+- A horn symbol. Just ignore that for now, because it contains debug settings.
+- a 3x3 grid, which contains some Ampersand extensions.
+- a plus (+) symbol. That is important, because it lets you create a new Ampersand script.
+- a person-like symbol. It lets you switch on/off some role dependent functionalities. If you have more than one role, just try it out and watch functionalities appear and disappear from the menu bar. As a student you typically have just one role (User) so this button is not very relevant for you.
Notes:
-* After a period of not using RAP4, you will be logged out automatically. In the current system, you may get errors or weird behaviour. Please navigate back to the login screen to check whether you are still logged in.
+- After a period of not using RAP4, you will be logged out automatically. In the current system, you may get errors or weird behaviour. Please navigate back to the login screen to check whether you are still logged in.
## Conceptual Model: Enrollment
@@ -180,16 +179,16 @@ You have seen the web application Enrollment in action. You have seen the code t
We have three ingredients:
-* CONCEPT
-* RELATION
-* RULE
+- CONCEPT
+- RELATION
+- RULE
Before we discuss these three main ingredients, we will discuss the other keywords you see in the code.
-* INTERFACE is not crucial for the conceptual model, but still crucial for the web application. It uses the conceptual model to define the tabs and fields displayed. We will come back to this later.
-* The text after MEANING and PURPOSE is printed in the documentation that RAP4 can generate.
-* MESSAGE and VIOLATION are used to display messages on screen to the user about rule violations.
-* POPULATION provides the web application with actual data to test the rules with. Adding data to the system can also be done with an excel sheet. The data specifies elements that populate the concepts and whether or not these elements are connected to each other in a specific relation.
+- INTERFACE is not crucial for the conceptual model, but still crucial for the web application. It uses the conceptual model to define the tabs and fields displayed. We will come back to this later.
+- The text after MEANING and PURPOSE is printed in the documentation that RAP4 can generate.
+- MESSAGE and VIOLATION are used to display messages on screen to the user about rule violations.
+- POPULATION provides the web application with actual data to test the rules with. Adding data to the system can also be done with an excel sheet. The data specifies elements that populate the concepts and whether or not these elements are connected to each other in a specific relation.
### The core of the model
@@ -241,14 +240,12 @@ Try to reason about the answers to the following questions based on the conceptu
### What have you learned?
-* an information system may be seen as a system of relations and rules that governs data, supplemented by user interfaces that give access to that data.
-* a rule engine executes the rules on all data regularly
+- an information system may be seen as a system of relations and rules that governs data, supplemented by user interfaces that give access to that data.
+- a rule engine executes the rules on all data regularly
### What's next?
-This concludes your first steps to get acquainted with Ampersand script en RAP4. The Open University Coursebook contains all theoretical background you need to start understanding and creating your own model. This Gitbook offers more practical and up to date information about the lang uage Ampersand script. For the syntax and meaning of Ampersand constructs, consult chapter [The language Ampersand](./reference-material/the-language-ampersand/README.md). For more in depth information about modeling in Ampersand [click here](./modeling/README.md). For the rest...have a look around and feel free to ask questions.
-
-
+This concludes your first steps to get acquainted with Ampersand script en RAP4. The Open University Coursebook contains all theoretical background you need to start understanding and creating your own model. This Gitbook offers more practical and up to date information about the lang uage Ampersand script. For the syntax and meaning of Ampersand constructs, consult the reference-material. For more in depth information about modeling in Ampersand [click here](./modeling/README.md). For the rest...have a look around and feel free to ask questions.
## Making your first Ampersand script
@@ -260,53 +257,51 @@ When you click on the blue plus-sign on the top-right side in the menu bar in yo
### Assignment
-* Copy the code for the system enrollment from [this page](#example-system-enrollment) or take it from the OU course-site. The code starts with `CONTEXT` and ends with `ENDCONTEXT`. Paste the script in the RAP4 editor (On rap.cs.ou.nl only: you now have to click on the big blue button "beware to save your work before leaving the editer field!"). The script is now saved in RAP4.
-* Next, click on the blue Compile button. When RAP4 is finished compiling your script, the compiler message should read "The script of Enrollment contains no type errors" and two blue buttons should be visible below that. Please make it a habit to read the Compiler message carefully each time you compile a script
+- Copy the code for the system enrollment from [this page](#example-system-enrollment) or take it from the OU course-site. The code starts with `CONTEXT` and ends with `ENDCONTEXT`. Paste the script in the RAP4 editor (On rap.cs.ou.nl only: you now have to click on the big blue button "beware to save your work before leaving the editer field!"). The script is now saved in RAP4.
+- Next, click on the blue Compile button. When RAP4 is finished compiling your script, the compiler message should read "The script of Enrollment contains no type errors" and two blue buttons should be visible below that. Please make it a habit to read the Compiler message carefully each time you compile a script
-* Generate a Prototype: Click the blue button "Prototype" and when RAP4 has finished loading you will see a new link "Launch Prototype". Click the link.
-* Now you see the information system you have just compiled from the code. You are already familiar with the look and feel. Click the Overview button in the top-left of the screen and have a look around.
-* Try to generate documentation: Click on the button Diagnosis. When RAP4 is done, a link will be added below the button. Click on the button Func. spec + pictures and again a link will be added. These two functions create pdf-files with information about the code that has been compiled. During the course you can have a better look there.
+- Generate a Prototype: Click the blue button "Prototype" and when RAP4 has finished loading you will see a new link "Launch Prototype". Click the link.
+- Now you see the information system you have just compiled from the code. You are already familiar with the look and feel. Click the Overview button in the top-left of the screen and have a look around.
+- Try to generate documentation: Click on the button Diagnosis. When RAP4 is done, a link will be added below the button. Click on the button Func. spec + pictures and again a link will be added. These two functions create pdf-files with information about the code that has been compiled. During the course you can have a better look there.
During the remainder of this course you will compile and run your own scripts in this way, so it pays to familiarize yourself with it.
You are now going to change some code and view the results in RAP4. Navigate back to your script editor (wherever you are, you can always go back to it via "MyScripts" in the menu bar).
-* If you want to save the original script, go to MyScripts, create a new script and copy the same code in there.
-* Let's add the possibility to register teachers in this system:
- * Define a new concept with the keyword CONCEPT: `CONCEPT Teacher`with a short description. Note that concept names start with an Uppercase and that all quotes need to be double quotes.
- * Define the relation between Module and Teacher with the keyword RELATION: `RELATION providedBy[Module*Teacher]` `MEANING "A module is provided by a teacher"` Note that relation names start with lowercase.
- * You can define an initial set of teachers and relate them to a module following the examples already available in the script. But you can also add the data later using the prototype. (Adding initial data in the script is a lot of work. There is another method, using spreadsheets. This is another topic in this tutorial.)
- * Add a service for the teachers in the third tab, the one for Modules. Below the codelines for "Modules" and above the line for "Course": `, "Teacher" : providedBy CRUD`
- * Save, compile, create protype, launch prototype, reinstall database and see the result in the third tab called "Modules". Note that you need to reinstall the database because the old database is still there, but the database structure has changed in the application.
- * Note that we have not defined any rules about teachers, so anything you fill in, is OK for this system.
-* Try to understand what you see in the script by making other changes, compile and inspect the changes; learn by doing. Try for instance to create a new course with modules and teachers. Demonstrate your changes to your peers and discuss the results.
+- If you want to save the original script, go to MyScripts, create a new script and copy the same code in there.
+- Let's add the possibility to register teachers in this system:
+ - Define a new concept with the keyword CONCEPT: `CONCEPT Teacher`with a short description. Note that concept names start with an Uppercase and that all quotes need to be double quotes.
+ - Define the relation between Module and Teacher with the keyword RELATION: `RELATION providedBy[Module*Teacher]` `MEANING "A module is provided by a teacher"` Note that relation names start with lowercase.
+ - You can define an initial set of teachers and relate them to a module following the examples already available in the script. But you can also add the data later using the prototype. (Adding initial data in the script is a lot of work. There is another method, using spreadsheets. This is another topic in this tutorial.)
+ - Add an interface for the teachers in the third tab, the one for Modules. Below the codelines for "Modules" and above the line for "Course": `, "Teacher" : providedBy CRUD`
+ - Save, compile, create protype, launch prototype, reinstall database and see the result in the third tab called "Modules". Note that you need to reinstall the database because the old database is still there, but the database structure has changed in the application.
+ - Note that we have not defined any rules about teachers, so anything you fill in, is OK for this system.
+- Try to understand what you see in the script by making other changes, compile and inspect the changes; learn by doing. Try for instance to create a new course with modules and teachers. Demonstrate your changes to your peers and discuss the results.
### What have you learned?
After finishing your assignment, you have learned:
-* how to use RAP4 to write, save and compile code.
-* the first basic keywords of Ampersand script and their effect on the prototype.
+- how to use RAP4 to write, save and compile code.
+- the first basic keywords of Ampersand script and their effect on the prototype.
### Want to learn more?
1. How to describe functionality in a [conceptual model](#conceptual-model-enrollment)?
-2. How can I upload [bulk data](/ampersand/reference-material/syntax-of-ampersand#population-in-spreadsheets) from spreadsheets into my application?
-
-
+2. How can I upload [bulk data](./reference-material/syntax-of-ampersand#population-in-spreadsheets) from spreadsheets into my application?
### Want to learn more?
-* how can I [make and run my first Ampersand script](#making-your-first-ampersand-script).
-* How can I describe functionality in a [conceptual model](#conceptual-model-enrollment)?
-* How can I upload [bulk data](/ampersand/reference-material/syntax-of-ampersand#population-in-spreadsheets) from spreadsheets into my application?
+- how can I [make and run my first Ampersand script](#making-your-first-ampersand-script).
+- How can I describe functionality in a [conceptual model](#conceptual-model-enrollment)?
+- How can I upload [bulk data](./reference-material/syntax-of-ampersand#population-in-spreadsheets) from spreadsheets into my application?
### What have you learned?
-* where to find the Repository for Ampersand Projects (RAP4)
-* to register yourself in RAP4
+- where to find the Repository for Ampersand Projects (RAP4)
+- to register yourself in RAP4
### Disclaimer
@@ -316,24 +311,18 @@ RAP4 is under development. You can expect to find teething problems (kinderziekt
After finishing your assignment, you have learned:
-* to recognize details in the source code of your information system and relate them to the information system "Enrollment" that you have been playing with;
-* that a rule of the business, such as "A student can only enroll for a module that is in the course the student takes" can be formalized in Ampersand.
-* that such a business rule can be used to constrain data in a database.
+- to recognize details in the source code of your information system and relate them to the information system "Enrollment" that you have been playing with;
+- that a rule of the business, such as "A student can only enroll for a module that is in the course the student takes" can be formalized in Ampersand.
+- that such a business rule can be used to constrain data in a database.
### Want to learn more?
1. How can I create my own information system in RAP4? Go to [Your tool: RAP4](#your-tool-rap4).
2. What is the conceptual model behind an Ampersand model? Go to [Conceptual Model: Enrollment.](#conceptual-model-enrollment)
-3. How can I upload [bulk data](/ampersand/reference-material/syntax-of-ampersand#population-in-spreadsheets) from spreadsheets into my application?
-
-
-
-
-
+3. How can I upload [bulk data](./reference-material/syntax-of-ampersand#population-in-spreadsheets) from spreadsheets into my application?
## What have you learned so far?
-* Ampersand is meant to develop information systems.
-* This tutorial will get you going with Ampersand. Consult your tutor with questions.
-* You have a tool to experiment with.
-
+- Ampersand is meant to develop information systems.
+- This tutorial will get you going with Ampersand. Consult your tutor with questions.
+- You have a tool to experiment with.
diff --git a/docs/tutorial/interface.md b/docs/tutorial/interface.md
deleted file mode 100644
index d3b48b9c13..0000000000
--- a/docs/tutorial/interface.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-draft: true
----
-
-# Interfaces
-You can work with data in your information system only through a service. Interfaces are the spectacles you need for viewing, changing, creating and deleting data.
-
-```
-INTERFACE Overview : "_SESSION" cRud
-BOX <TABS>
- [ Students : V[SESSION*Student] cRuD
- BOX <TABLE>
- [ "Student" : I[Student] cRud
- , "Enrolled for" : isEnrolledFor cRUD
- , "Course" : takes CRUD
- ]
- , Course : V[SESSION*Course] cRuD
- BOX <TABLE>
- [ "Course" : I cRud
- , "Modules" : isPartOf~ CRUD
- ]
- , Modules : V[SESSION*Module] cRud
- BOX <TABLE>
- [ "Modules" : I cRuD
- , "Course" : isPartOf cRUd
- , "Students" : isEnrolledFor~ CRUD
- ]
- ]
-```
-
-
diff --git a/docs/tutorial/interfaces.md b/docs/tutorial/interfaces.md
new file mode 100644
index 0000000000..71f3a82da5
--- /dev/null
+++ b/docs/tutorial/interfaces.md
@@ -0,0 +1,134 @@
+# Interfaces
+
+<!-- This file is a tutorial about interfaces. -->
+
+Interfaces are meant to expose functionality and data from a [context](../reference-material/syntax-of-ampersand#the-context-statement), to let users or information systems interact with the system by creating, reading, updating, and deleting data.
+
+Note: The interface definition must be outside a pattern
+
+## Example
+
+The following figure is an example of a user interface, which shows the name, status, e-mail and co-workers of a person called "J. Lovell".
+
+
+
+The specification of this user interface is given in the following interface definition:
+
+```
+INTERFACE Person : I[Person]
+BOX
+ [ "Name" : personName
+ , "Status" : personStatus
+ , "Email" : personEmail
+ , "Works with" : workswith
+ ]
+```
+
+To understand this fragment, take notice of:
+
+1. The name of this interface is `Person`. This name immediately follows the keyword `INTERFACE`.
+2. The term following the colon, `I[Person]`, is the interface term of this interface.
+3. The interface can be applied to any atom from the _domain of the interface term_. So this particular interface is applicable to any atom of type `Person`. In the screenshot, it applies to `"J. Lovell"`.
+4. The labels "Name", "Status", "Email", and "Works with" correspond to field names in the user interface.
+5. Each term at the right of a field name specifies which data is presented in the field. For this reason it is called the _field term_ for that field. Field name and field term are separated by a colon.
+6. Of all pairs `<"J. Lovell", x>` from the field term, the field displays the right atom `x`. A field term always works on one specific atom on the left, which is `"J. Lovell"` in this example.
+7. Field terms are subject to type checking. The following relations provide an example for getting a type-correct interface:
+
+ ```
+ RELATION personName :: Person * PersonName [UNI]
+ RELATION personStatus :: Person * PersonStatus [UNI]
+ RELATION personEmail :: Person * Email [UNI,TOT]
+ RELATION workswith :: Person * Person
+ ```
+
+ The source concepts of a field term must match the target concept of the interface term.
+
+8. Looking at the screenshot, we can tell that `"J. Lovell"` has one personName (which is `"J. Lovell"`), it has no personStatus, one personEmail and three persons to work with in `RELATION workswith`.
+
+## Nesting
+
+You can create structure in an interface by nesting. Here is an example:
+
+
+
+The specification of this interface is given in the following code fragment.
+
+```
+INTERFACE "Project" : I[Project] BOX
+ [ "Project" : I[Project]
+ , "Name" : projectName
+ , "Current PL" : pl
+ , "Administration" : I[Project] BOX
+ [ "Project leaders" : project~;assignee/\pl BOX
+ [ "Name" : personName
+ , "Status" : personStatus
+ , "Email" : personEmail
+ ]
+ , "Project members" : project~;assignee/\member BOX
+ [ "Name" : personName
+ , "Status" : personStatus
+ , "Email" : personEmail
+ ]
+ ]
+ ]
+```
+
+Notice the following features:\
+1\. The structure of an interface is hierarchical. It consists of boxes within a box. This is because a field term may be followed by a `BOX` with a list of subinterfaces. Without it, it is just a field term. 2. When a field term is followed by a `BOX`, every atom in the _codomain of the field term_ is displayed in a box of its own on the screen. That box behaves like an interface with the field term serving as interface term of that subinterface. 3. By this mechanism, the hierarchical structure of the entire interface translates directly to the hierarchical structure of the web-page in which it is displayed. 4. The source concept of a field term must match with the target concept of the field term outside the box. 5. The target concept of a field term that has a box, must match with the source concepts of each field inside that box.
+
+## Formatting
+
+Especially in more complicated interfaces, you will find it nice to adapt the layout of the fields in the user interface. For this purpose, you can refine the word `BOX` with `<FORM>`, `<TABLE>`, or `<TABS>`, as in the following code fragment. Note that these annotation have no meaning other than to change what the user interface looks like.
+
+```
+INTERFACE "Project" : V[SESSION*Project]
+BOX<TABLE>
+ [ "Project" : I[Project]
+ , "Name" : projectName
+ , "Current PL" : pl
+ , "Administration" : I[Project]
+ BOX <TABS>
+ [ "Project leaders" : project~;assignee/\pl
+ BOX <TABLE>
+ [ "Name" : personName
+ , "Status" : personStatus
+ , "Email" : personEmail
+ ]
+ , "Project members" : project~;assignee/\member
+ BOX <TABLE>
+ [ "Name" : personName
+ , "Status" : personStatus
+ , "Email" : personEmail
+ ]
+ ]
+ ]
+```
+
+Notice the effect that these changes have on the user interface.
+
+
+
+Notice the following features:\
+1\. The keyword `BOX <TABS>` turns the box into a layout with tabs.\
+2\. The keyword `BOX <TABLE>` turns the layout 90 degrees into columns.\
+3\. The keyword `BOX <FORM>` is default for any box. It does not change the effect of `BOX`.
+
+## Layout and Widgets
+
+TODO
+
+## Assignment
+
+Compile and run the script [Project Administration Example](https://github.com/AmpersandTarski/ampersand-models/tree/master/Examples/ProjectAdministration). Start by reproducing everything that is shown above. It is quite likely that you will be trying out your own ideas before you get to the end... Have fun!
+
+## What have you learned?
+
+After finishing your assignment, you have learned:
+
+- to explain how an interface definition is displayed on the screen of a user.
+- to predict which data items an interface applies to, if you know which pairs are in an interface term.
+- to predict which data items are displayed, if you know which pairs are in a field term.
+- to explain which atoms are used in a sub-interface.
+- to understand what the keywords `TABS`, `COLS`, and `ROWS` do to your display.
+
+ More than one interface may apply to the same atom. That gives you a choice on runtime to which interface you want to navigate. If no interface applies, that atom is not navigable.
diff --git a/docs/tutorial/vog-in-dutch.md b/docs/tutorial/vog-in-dutch.md
deleted file mode 100644
index 4140a05712..0000000000
--- a/docs/tutorial/vog-in-dutch.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-draft: true
----
\ No newline at end of file
diff --git a/src/Ampersand/Classes/ViewPoint.hs b/src/Ampersand/Classes/ViewPoint.hs
index 42132543e9..ce8e764ce9 100644
--- a/src/Ampersand/Classes/ViewPoint.hs
+++ b/src/Ampersand/Classes/ViewPoint.hs
@@ -33,7 +33,7 @@ class Language a where
[rulefromProp p d | d <- Set.elems $ relsDefdIn x, p <- Set.elems (properties d)]
identityRules :: a -> Rules -- all identity rules that are maintained within this viewpoint.
identityRules x = Set.fromList . map ruleFromIdentity $ identities x
- enforceRules :: a -> Rules -- all enforce rules that are maintained within this viewpoint.
+ enforceRules :: a -> Rules -- all enforcement rules that are maintained within this viewpoint.
enforceRules x = Set.fromList . concatMap enfRules . enforces $ x
allRules :: a -> Rules
allRules x = udefrules x `Set.union` proprules x `Set.union` identityRules x `Set.union` enforceRules x