Re #6014 Improve STACK_WORK documentation.

Author: mpilgrem

doc/environment_variables.md

@@ -73,28 +73,34 @@ sequences for color to its output.
 Related command: all commands that make use of Stack's global YAML configuration
 file (`config.yaml`).
 
-Overridden by: Stack's global `--stack-root` option.
+Overridden by: Stack's global
+[`--stack-root`](global_flags.md#the---stack-root-option) option.
 
 The environment variable `STACK_ROOT` can be used to specify the Stack root
 directory.
 
 ## `STACK_WORK`
 
-Related command: all commands that make use of Stack's working directory.
+Related command: all commands that make use of Stack's work directories.
 
-Overridden by: Stack's global `--work-dir` option.
+Overridden by: Stack's [`work-dir`](yaml_configuration.md#work-dir) non-project
+specific configuration option, or global
+[`--work-dir`](global_flags.md#the---work-dir-option) option.
 
-The environment variable `STACK_YAML` can be used to specify Stack's
-working directory in a project. The path must be a relative one, relative to the
-root directory of the project.
+The environment variable `STACK_WORK` can be used to specify the path of Stack's
+work directory, within a local project or package directory, and override
+Stack's default of `.stack-work`. The path must be a relative one, relative to
+the root directory of the project or package. The relative path cannot include a
+`..` (parent directory) component.
 
 ## `STACK_XDG`
 
 Related command: all commands that make use of Stack's user-specific general
 YAML configuration file (`config.yaml`).
 
 Overridden by: the use of Stack's `STACK_ROOT` environment variable, or the use
-of Stack's global `--stack-root` option.
+of Stack's global
+[`--stack-root`](global_flags.md#the---stack-root-option) option.
 
 On Unix-like operating systems and Windows, Stack can be configured to follow
 the XDG Base Directory Specification if the environment variable `STACK_XDG` is
@@ -105,7 +111,8 @@ set to any non-empty value.
 Related command: all commands that make use of Stack's project-level YAML
 configuration file.
 
-Overridden by: Stack's global `--stack-yaml` option.
+Overridden by: Stack's global
+[`--stack-yaml`](global_flags.md#the---stack-yaml-option) option.
 
 The environment variable `STACK_YAML` can be used to specify Stack's
 project-level YAML configuration file.

doc/global_flags.md

@@ -268,13 +268,15 @@ non-project specific configuration [option](yaml_configuration.md#with-hpack).
 
 Default: `.stack-work`
 
-Overrides: `STACK_WORK` environment variable
+Overrides: [`STACK_WORK`](environment_variables.md#stack_work) environment
+variable, and [`work-dir`](yaml_configuration.md) non-project specific
+configuration option.
 
 Pass the option `--work-dir <relative_path_to_the_Stack_root>` to specify the
-path to Stack's work directory for the project. The path must be a relative one,
-relative to the project's root directory. For further information, see the
-documentation for the corresponding non-project specific configuration
-[option](yaml_configuration.md#work-dir).
+path to Stack's work directory, within a local project or package directory. The
+path must be a relative one, relative to the the root directory of the project
+or package. The relative path cannot include a `..` (parent directory)
+component.
 
 ## The `--setup-info-yaml` command option
 

doc/glossary.md

@@ -47,6 +47,7 @@ The following terms are used in Stack's documentation.
 |`stack.yaml`       |A project-level configuration file used by Stack, which may also contain non-project-specific options.|
 |Stackage           |A [distribution](https://www.stackage.org/) of compatible Haskell packages.|
 |Stack root         |A directory in which Stack stores important files. See `stack path --stack-root`. On Windows, or if Stack is configured to use the XDG Base Directory Specification, Stack also stores important files outside of the Stack root.|
+|Stack work directory|A directory within a local project or package directory in which Stack stores files created during the build process. Named `.stack-work`, by default.|
 |Unix-like operating systems|Linux, FreeBSD and macOS.                         |
 |VS Code            |[Visual Studio Code](https://code.visualstudio.com/), a source code editor.|
 |Windows            |A group of operating systems developed by Microsoft.      |

doc/yaml_configuration.md

@@ -1565,12 +1565,16 @@ with-hpack: /usr/local/bin/hpack
 
 Default: `.stack-work`
 
-Command line equivalent (takes precedence): `--work-dir` option
+Command line equivalent (takes precedence):
+[`--work-dir`](global_flags.md#the---work-dir-option) option
 
-Environment variable alternative (lowest precedence): `STACK_WORK`
+Environment variable alternative (lowest precedence):
+[`STACK_WORK`](environment_variables.md#stack_work)
 
-`work-dir` (or the contents of `STACK_WORK`) specifies the relative path of
-Stack's 'work' directory.
+`work-dir` specifies the path of Stack's work directory, within a local project
+or package directory. The path must be a relative one, relative to the
+root directory of the project or package. The relative path cannot include a
+`..` (parent directory) component.
 
 ## Customisation scripts