Improve documentation of Stack root

Author: mpilgrem

doc/stack_root.md

@@ -35,8 +35,8 @@ command line.
 
     The default Stack root is `%APPDIR%\stack`.
 
-    If the `LOCALAPPDATA` environment variable exists, the default location of
-    tools is `%LOCALAPPDATA%\Programs\stack`. Otherwise, it is the `programs`
+    If the `LOCALAPPDATA` environment variable exists, then the default location
+    of tools is `%LOCALAPPDATA%\Programs\stack`. Otherwise, it is the `programs`
     directory in the Stack root.
 
     !!! warning
@@ -144,14 +144,27 @@ This is Stack's global configuration file. For further information, see the
 documentation for non-project specific
 [configuration](yaml_configuration.md#non-project-specific-configuration).
 
-If the file is deleted, and Stack needs to consult it, Stack will create a file
-with default contents.
+If the file is deleted, and Stack needs to consult it, then Stack will create a
+file with default contents.
 
 ### `stack.sqlite3`
 
 This is a 'user' database that Stack uses to cache certain information. The
 associated lock file is `stack.sqlite3.pantry-write-lock`.
 
+### `.stack-work` directory (optional)
+
+Stack can build when there is no project-level configuration file (including one
+in the `global-project` directory of the Stack root); for example, as a result
+of a [`stack script`](script_command.md) command (at the command line or in a
+[Stack interpreter options comment](scripts.md) in a Haskell script file). When
+it does so, the directory corresponding to a project directory is the Stack
+root. Stack will create its work directory, named `.stack-work` by default, in
+the Stack root.
+
+If the work directory is deleted, and Stack needs that work directory, then
+Stack will recreate it.
+
 ### `global-project` directory
 
 This contains:
@@ -162,13 +175,13 @@ This contains:
 * if created, Stack's working directory (`.stack-work`) for the global project.
 
 If the project-level configuration file is deleted, and Stack needs to consult
-it, Stack will recreate the contents of the directory.
+it, then Stack will recreate the contents of the directory.
 
 ### `pantry\hackage` directory
 
 This contains a local cache of the package index. If the contents of the
-directory are deleted, and Stack needs to consult the package index, Stack will
-seek to download the latest package index.
+directory are deleted, and Stack needs to consult the package index, then Stack
+will seek to download the latest package index.
 
 !!! info
 
@@ -185,8 +198,8 @@ This contains:
 
 * the Pantry database used by Stack (`pantry.sqlite3`) and its associated lock
   file (`pantry.sqlite2.pantry-write-lock`). If the database is deleted, and
-  Stack needs to consult it, Stack will seek to create and initialise it. The
-  database is initialised with information from the package index; and
+  Stack needs to consult it, then Stack will seek to create and initialise it.
+  The database is initialised with information from the package index; and
 * a database of package versions that come with each version of GHC
   (`global-hints-cache.yaml`).
 
@@ -200,7 +213,18 @@ installed Stack-supplied tool:
 * a directory for the tool.
 
 To remove a Stack-supplied tool, delete all of the above. If Stack needs a
-Stack-supplied tool and it is unavailable, Stack will seek to obtain it.
+Stack-supplied tool and it is unavailable, then Stack will seek to obtain it.
+
+### `scripts` directory (optional)
+
+If the `--compile` or `--optimize` and `--use-root` flags are used with the
+[`stack script`](script_command.md) command, then this contains:
+
+* script-specific locations, each containing all the compilation outputs
+  (inclduing the executable) generated by the command.
+
+If the `scripts` directory, or a script-specific location within it, is deleted,
+and Stack needs that directory, then Stack will recreate it.
 
 ### `setup-exe-cache` directory
 
@@ -209,7 +233,7 @@ version of GHC (an associated version of Cabal (the library)) that Stack has
 used, an executable that Stack uses to access Cabal (the library).
 
 If the contents of the directory are deleted, and Stack needs the executable,
-Stack will seek to rebuild it.
+then Stack will seek to rebuild it.
 
 ### `setup-exe-src` directory
 
@@ -219,7 +243,7 @@ contains the two source files (`setup-<hash>.hs` and `setup-shim-<hash>.hs`)
 that Stack uses to build the executable.
 
 If the contents of the directory are deleted, and Stack needs the executable,
-Stack will recreate them.
+then Stack will recreate them.
 
 The hash in the names of the source files is a hash of arguments passed to GHC
 when building the executable and the contents of the two source files.
@@ -243,7 +267,7 @@ This contains a directory for each snapshot that Stack creates when building
 immutable dependencies of projects.
 
 If the contents of the directory are deleted, and the snapshot is not available
-to Stack when it builds, Stack will recreate the snapshot.
+to Stack when it builds, then Stack will recreate the snapshot.
 
 ### `templates` directory
 
@@ -252,7 +276,7 @@ further information, see the [`stack templates`](templates_command.md) command
 documentation.
 
 If the contents of the directory are deleted, an Stack needs a project template,
-Stack will seek to download the template.
+then Stack will seek to download the template.
 
 ### `upload` directory