documentation for URI rewrite rules

Readme.md

@@ -39,19 +39,44 @@ walint --config-file config.json --repository path \
    optional. Keys given here will override whatever values are set in the 
    configuration file.
 
-### Configuation
+## Configuation
 Take a look at `config.json` for an example. Most keys are required, and do not
-have default values.
+have default values. In `config.json`, all possible keys are given.
 
-For the schema, take a look at the definition of the `LintConfig` type in
-`lib/LintConfig.hs`; I'll attempt to remember documenting options there (if you
-are unfamiliar with Haskell: key names come first, though there are all prepended
-with `config` here. Types come after the `::`; ignore the `HKD f` bit and look
-at whatever comes after that. Most types should be self-explanatory; Note that
-you may leave out keys whose type includes `Maybe`)
+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`.
 
+### Uri Schemas
 
-### Output
+`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` takes a very reductive view or URIs: `schema://domain/tail`
+
+#### Rewrite Rules
+
+For now there are three 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], "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 there is no applicable `domain`,
+   reject the URI
+
+For now there are two (useful) scopes: `map` applies to tiled map links 
+(i.e. `exitUrl`), and `website` applies to weblinks (i.e. `openWebsite`).
+
+
+## Output
 By default `walint` prints lints in a hopefully human-readable manner. 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