update readme

1 files changed, 42 insertions, 38 deletions

diff --git a/Readme.md b/Readme.md
index e7295c5..1960b51 100644
--- a/Readme.md
+++ b/Readme.md
@@ -7,15 +7,15 @@ errors (such as non-existent map entrypoints or missing asset files) and makes
 suggestions to improve accessability.
 
 It can also *adjust* maps — e.g. to automatically insert property values or help
-enforce an event's map policies (among other things, this is used to resolve 
-special inter-assembly `world://` links).
+enforce an event's map policies (among other things, this was used to resolve 
+special inter-assembly `world://` links at rc3).
 
 `walint-mapserver` is a minimal implementation of a server that periodically
 fetches, lints, and adjusts maps from a set of git repositories, writing them
-to a path that can then be served by a webserver. It can be used as a (very
-simple) replacement for rc3's hub and mapservice at smaller events — to get
-started, manually list all map repositories in `config.toml`, then visit 
-`localhost:8080/admin/overview`.
+to a path that can then be served as static map files for a workadventure
+deployment. It can be used as a (very simple) replacement for rc3's hub and
+mapservice at smaller events — to get started, manually list all map
+repositories in `config.toml`, then visit `localhost:8080/admin/overview`.
 
 
 ## Installing
@@ -23,26 +23,28 @@ started, manually list all map repositories in `config.toml`, then visit
 ### From the CI pipeline
 
 Gitlab [automatically builds a version](https://git.cccv.de/hub/walint/-/jobs)
-of `walint` each time something is pushed to this repository. The resulting
-binary should work fine on most linux systems, especially if they're vaguely
-debian-like.
+of `walint` each time something is pushed to the version of this repository
+kept at the CCCV infra. The resulting binary should work fine on most linux 
+systems, especially if they're vaguely debian-like.
 
 In case you get an incomprehensible or confusing error when executing it, try 
-running `ldd walint` and see if anything is marked as not found, then install it.
+running `ldd walint` and see if anything is marked as not found, then install 
+it.
 
 ### Build using stack
 
-This uses a lockfile to pin versions of dependencies (as well as `ghc`, the haskell
-compiler). You will need [the haskell stack](https://docs.haskellstack.org/en/stable/README/).
+This uses a lockfile to pin versions of dependencies (as well as `ghc`, the 
+haskell compiler). You will need 
+[the haskell stack](https://docs.haskellstack.org/en/stable/README/).
 
-Then just run
+Run
 
 ```
 stack build
 ```
 
-If you lack `ghc` in the correct version and don't know how to install it, you can
-pass it `--install-ghc` to take care of that for you (note that on NixOS, `stack` may
+If you lack `ghc` and don't know how to install it, you can add  `--install-ghc`,
+and `stack` will take care of that for you (note that on NixOS, `stack` may
 use a fitting `ghc` derivation if it finds one, even without `--install-ghc`).
 
 To install into your `$PATH`, use
@@ -57,9 +59,6 @@ Alternatively, run `walint` via stack:
 stack run -- walint [options as normal]
 ```
 
-However, in this case stack will re-check files every time to ensure your build
-is up to date with the sources, increasing startup time.
-
 ### Build using cabal
 
 You can, but probably should not. Beware of older Aeson versions!
@@ -78,8 +77,8 @@ walint --config-file config.json --repository path \
    defaults to `main.json`
  - `--lintLevel`: limit output only to messages that have at most the given
    level. Valid levels are `Info`, `Suggestion`, `Warning`, `Forbidden`, `Error`,
-   `Fatal`. Defaults to `Suggestion` if not given.
- - `--json`: print output as json instead of the normal more human-friendly format
+   `Fatal`. Defaults to `Suggestion`.
+ - `--json`: print output as json instead of the default human-friendly format
  - `--pretty`: if used with `--json`, insert line breaks and indentation to make
    the output more readable. Otherwise no effect.
  - `--out path`: write the linted & adjusted repository to the given path. Any
@@ -102,40 +101,45 @@ have default values. In `config.json`, all possible keys are given.
 Most options should be reasonably self-explanatory. Note that `MaxLintLevel`
 differs from the option `--lintLevel`: the latter merely determines what is
 *printed* (in case json output is not enabled), the former determines the 
-maximum lint level allowed before the linter rejects the map and does not
-copy it to the path given to `--out`.
+maximum lint level allowed before the linter rejects the map and will refuse to
+copy it to the path given as `--out`.
 
 ### Uri Schemas
 
-`walint` supports (limited) rewriting of URIs contained in the map json via
-the `UriSchemas` option, which takes a map from uri schemas to a rule describing
-what to do with such links, depending on the scope in which they appear.
+`walint` supports (basic) rewriting of URIs contained in the map json via the
+`UriSchemas` option, which maps schemas to rules describing what to do with such
+links, depending on the scope in which they appear.
 
 `walint` takes a very reductive view or URIs: `schema://domain/tail`
 
 #### Rewrite Rules
 
-For now there are three types of such rules:
+For now there are four types of such rules:
  - `schema: {"scope":[scopes]}`: if in a scope listed in `scopes`, allow any
    links of the given `schema`
+ - `schema: {"scope":[scopes], "allowed":[allowed]}`: if in a scope listed in
+   `scopes`, only allow URIs whose domain occurs in `allowed`.
  - `schema: {"scope":[scopes], "allowed":[allowed], "blocked":[blocked], "prefix":prefix}`: 
-   if in a scope listed in `scopes`, prefix any URIs of the given `schema` with
-   the given `prefix`, unless the URI's domain occurs in `allowed` (in which case
-   leave it untouched), or it occurs in `blocked`, in which
-   case it will be rejected as a lint error.
- - `schema: {"scope":[scopes], "subst":{domain: prefix, ...}}`: if in a scope
-   listed in `scopes` and given a URI with the domain `domain`, concatenate 
-   `prefix` with the tail of this URI.
+   if in a scope listed in `scopes`, allow URIs whose domain occurs in `allowed`,
+   disallow all whose domain occurs in `blocked`, and for all others, prefix
+   with the string given as `prefix`
+ - `schema: {"scope":[scopes], "substs":{domain: prefix, ...}}`: if in a 
+   scope listed in `scopes` and given a URI with the domain `domain`,
+   concatenate `prefix` with the tail of this URI.
 
-In case an URI is encountered and there is no applicable rule, it will be rejected
-(note that this means you'll have to explicitly allow `https://` for links!)
+In case an URI is encountered and there is no applicable rule, it will be 
+rejected (note that this means you'll have to explicitly allow `https://` for
+links!)
 
-There are currently three possible scopes: `map` applies to tiled map links 
-(i.e. `exitUrl`), `website` to `openWebsite`, `audio` to `playAudio`.
+There are currently four scopes:
+ - `map` applies to tiled map links (i.e. `exitUrl`)
+ - `website` to `openWebsite`
+ - `audio` to `playAudio`
+ - `script` to scripts
 
 
 ## Output
-By default `walint` prints lints in a hopefully human-readable manner. Its exit
+By default `walint` prints lints in a (hopefully) human-readable format. Its exit
 code will be 1 if the maximum lint level set in its config was exceeded, and 0
 otherwise. Only in the latter case will it write out an adjusted map respository
 to the path passed to `--out`. If the path given to `--out` already exists,