Re commercialhaskell#6603 Improve online docs as related to configuration files

Author: mpilgrem

doc/script_command.md

@@ -13,14 +13,23 @@ The `stack script` command either runs a specified Haskell source file (using
 GHC's `runghc`) or, optionally, compiles such a file (using GHC) and, by
 default, runs it.
 
-Unlike `stack ghc` and `stack runghc`, the command ignores all Stack YAML
-configuration files (global and project-level). A snapshot must be specified on
-the command line (with the `--snapshot` option). For example:
+Unlike [`stack ghc`](ghc_command.md) and [`stack runghc`](runghc_command.md),
+the command ignores any project-level configuration file (`stack.yaml`, by
+default) (including in the `global-project` directory in the Stack root). A
+snapshot must be specified on the command line (with the `--snapshot` option).
+For example:
 
 ~~~text
 stack script --snapshot lts-22.21 MyScript.hs
 ~~~
 
+!!! info
+
+    Non-project level configuration options in global configuration files
+    (`config.yaml`), are not ignored. Such options may be useful if
+    [`allow-newer`](yaml_configuration.md#allow-newer) and/or
+    [`allow-newer-deps`](yaml_configuration.md#allow-newer-deps) are required.
+
 The `stack script` command behaves as if the `--install-ghc` flag had been
 passed at the command line.
 

doc/scripts.md

@@ -10,9 +10,9 @@ that.
 You can use `stack <file_name>` to execute a Haskell source file. Usually, the
 Stack command to be applied is specified using a special Haskell comment (the
 Stack interpreter options comment) at the start of the source file. That command
-is most often `stack script` but it can be, for example, `stack runghc`. If
-there is no Stack interpreter options comment, Stack will warn that one was
-expected.
+is most often [`stack script`](script_command.md) but it can be, for example,
+[`stack runghc`](runghc_command.md). If there is no Stack interpreter options
+comment, Stack will warn that one was expected.
 
 An example will be easiest to understand. Consider the Haskell source file
 `turtle-example.hs` with contents:
@@ -77,11 +77,11 @@ dependencies are built) and subsequent times more promptly (as the runs are
 able to reuse everything already built).
 
 The second line of the source code is the Stack interpreter options comment. In
-this example, it specifies the `stack script` command with the options of a
-LTS Haskell 22.21 snapshot (`--snapshot lts-22.21`) and ensuring the
-[`turtle` package](https://hackage.haskell.org/package/turtle) is available
-(`--package turtle`). The version of the package will be that in the specified
-snapshot (`lts-22.21` provides `turtle-1.6.2`).
+this example, it specifies the [`stack script`](script_command.md) command with
+the options of a LTS Haskell 22.21 snapshot (`--snapshot lts-22.21`) and
+ensuring the [`turtle` package](https://hackage.haskell.org/package/turtle) is
+available (`--package turtle`). The version of the package will be that in the
+specified snapshot (`lts-22.21` provides `turtle-1.6.2`).
 
 ## Arguments and interpreter options and arguments
 
@@ -140,12 +140,12 @@ where `+RTS -s -RTS` are some of GHC's
 
 ## Just-in-time compilation
 
-As with using `stack script` at the command line, you can pass the `--compile`
-flag to make Stack compile the script, and then run the compiled executable.
-Compilation is done quickly, without optimization. To compile with optimization,
-pass the `--optimize` flag instead. Compilation is done only if needed; if the
-executable already exists, and is newer than the script, Stack just runs the
-executable directly.
+As with using [`stack script`](script_command.md) at the command line, you can
+pass the `--compile` flag to make Stack compile the script, and then run the
+compiled executable. Compilation is done quickly, without optimization. To
+compile with optimization, pass the `--optimize` flag instead. Compilation is
+done only if needed; if the executable already exists, and is newer than the
+script, Stack just runs the executable directly.
 
 This feature can be good for speed (your script runs faster) and also for
 durability (the executable remains runnable even if the script is disturbed, eg
@@ -154,9 +154,9 @@ git bisect, etc.)
 
 ## Using multiple packages
 
-As with using `stack script` at the command line, you can also specify multiple
-packages, either with multiple `--package` options, or by providing a comma or
-space separated list. For example:
+As with using [`stack script`](script_command.md) at the command line, you can
+also specify multiple packages, either with multiple `--package` options, or by
+providing a comma or space separated list. For example:
 
 ~~~haskell
 #!/usr/bin/env stack
@@ -170,20 +170,27 @@ space separated list. For example:
 
 ## Stack configuration for scripts
 
-With the `stack script` command, all Stack YAML configuration files (global and
-project-level) are ignored.
+As with using [`stack script`](script_command.md) at the command line, any
+project-level configuration file (`stack.yaml`, by default) (including in the
+`global-project` directory in the Stack root) is ignored.
 
-With the `stack runghc` command, if the current working directory is inside a
-project then that project's Stack project-level YAML configuration is effective
-when running the script. Otherwise the script uses the global project
-configuration specified in `<Stack root>/global-project/stack.yaml`.
+!!! info
+
+    Non-project level configuration options in global configuration files
+    (`config.yaml`), are not ignored.
+
+With the [`stack runghc`](runghc_command.md) command, if the current working
+directory is inside a project then that project's Stack project-level
+configuration file is effective when running the script. Otherwise the script
+uses the project-level configuration file in the `global-project` directory of
+the Stack root.
 
 ## Testing scripts
 
 You can use the flag `--script-no-run-compile` on the command line to enable (it
-is disabled by default) the use of the `--no-run` option with `stack script`
-(and forcing the `--compile` option). The flag may help test that scripts
-compile in CI (continuous integration).
+is disabled by default) the use of the `--no-run` option with
+[`stack script`](script_command.md) (and forcing the `--compile` option). The
+flag may help test that scripts compile in CI (continuous integration).
 
 For example, consider the following simple script, in a file named `Script.hs`,
 which makes use of the joke package
@@ -208,20 +215,21 @@ executable is not run: no missiles are launched in the process!
 
 ## Writing independent and reliable scripts
 
-The `stack script` command will automatically:
+The [`stack script`](script_command.md) command will automatically:
 
-* Install GHC and libraries, if missing. `stack script` behaves as if the
-  `--install-ghc` flag had been passed at the command line.
+* Install GHC and libraries, if missing. [`stack script`](script_command.md)
+  behaves as if the `--install-ghc` flag had been passed at the command line.
 * Require that all packages used be explicitly stated on the command line.
 
 This ensures that your scripts are _independent_ of any prior deployment
 specific configuration, and are _reliable_ by using exactly the same version of
 all packages every time it runs so that the script does not break by
 accidentally using incompatible package versions.
 
-In earlier versions of Stack, the `runghc` command was used for scripts and can
-still be used in that way. In order to achieve the same effect with the `runghc`
-command, you can do the following:
+In earlier versions of Stack, the [`stack runghc`](runghc_command.md) command
+was used for scripts and can still be used in that way. In order to achieve the
+same effect with the [`stack runghc`](runghc_command.md) command, you can do the
+following:
 
 1. Use the `--install-ghc` option to install the compiler automatically
 2. Explicitly specify all packages required by the script using the `--package`
@@ -230,9 +238,10 @@ command, you can do the following:
 3. Use the `--snapshot` Stack option to ensure a specific GHC version and
    package set is used.
 
-It is possible for configuration files to affect `stack runghc`. For that
-reason, `stack script` is strongly recommended. For those curious, here is an
-example with `runghc`:
+It is possible for a project-level configuration file to affect
+[`stack runghc`](runghc_command.md). For that reason,
+[`stack script`](script_command.md) is strongly recommended. For those curious,
+here is an example with [`stack runghc`](runghc_command.md):
 
 ~~~haskell
 #!/usr/bin/env stack
@@ -247,9 +256,10 @@ example with `runghc`:
   -}
 ~~~
 
-The `runghc` command is still very useful, especially when you're working on a
-project and want to access the package databases and configurations used by that
-project. See the next section for more information on configuration files.
+The [`stack runghc`](runghc_command.md) command is still useful, especially when
+you're working on a project and want to access the package databases and
+configurations used by that project. See the next section for more information
+on configuration files.
 
 ## Loading scripts in GHCi