draft uenv config docs

Author: bcumming

docs/software/uenv/configure.md

@@ -1,2 +1,56 @@
 [](){#ref-uenv-configure}
 # Configuring uenv
+
+Uenv is designed to work out of the box, with zero configuration for most users.
+
+## User configuration
+
+Uenv is configured using a text configuration file.
+
+### Location of the configuration file
+
+The location of the configuration file follows the [XDG base directory specification](https://specifications.freedesktop.org/basedir-spec/latest/).
+* If the `XDG_CONFIG_HOME` environment variable is set, the `$XDG_CONFIG_HOME/uenv/config`.
+* Otherwise it defaults to `$HOME/.config/uenv/config`.
+
+### Syntax
+
+A custom, but simple `key = value` syntax with comments marked with `#`
+
+```
+# this is a comment
+
+# the following are equivalent
+color = true
+color=true
+```
+
+Notes on the syntax:
+
+* keys are case-sensitive: `color` and `Color` are not equivalent.
+* all keys are lower case
+* white space is trimmed from keys and values, e.g.: `color = true` will be parsed as key=`color` and value=`true`.
+
+### Options
+
+| key       | description | default     | values  |
+| ---       | ----------- | --------    | ------  |
+| `color`   | Use color output  | automatically chosen according to TTY | `true`, `false` |
+| `repo`    | The default repo location for downloaded uenv images  | `$SCRATCH/.uenv-images`  | An absolute path |
+
+#### `color`
+
+By default, uenv will generate color output according to the following:
+* if `--no-color` is passed, color output is disabled
+* else if `color` is set in the config file, use that setting
+* else if the `NO_COLOR` environment variable is defined color output is disabled
+* else if the terminal is not TTY disable color
+* else enable color output
+
+#### `repo`
+
+The location of
+
+* if the `--repo` CLI arguement overrides 
+* else if `color` is set in the config file, use that setting
+* else use the default value of `$SCRATCH/.uenv-images`