Re #6691 Improve documentation re Stack options

Author: mpilgrem

doc/configure/yaml/index.md

@@ -16,7 +16,7 @@ Stack's configuration options are each of one of two types:
 
 -   :material-account:{ .lg .middle } __Project-specific__
 
-    Configured at the project level
+    Configured only at the project level
 
     ---
 
@@ -32,6 +32,8 @@ Stack's configuration options are each of one of two types:
 
 </div>
 
+Most of Stack's configuration options are non-project specific.
+
 ## Project-level and global configuration files
 
 Stack's configuration files are each of one of two types:

doc/configure/yaml/non-project.md

@@ -2,11 +2,18 @@
 
 # Non-project-specific configuration
 
-Non-project configuration options can be included in a project-level
-configuration file (`stack.yaml`, by default) or in global configuration files
-(`config.yaml`). However, non-project-specific options in the project-level
-configuration file in the `global-project` directory are ignored by Stack. The
-options below are listed in alphabetic order.
+Non-project configuration options can be included in:
+
+* a [project-level configuration file](../yaml/index.md#project-level-and-global-configuration-files)
+  (`stack.yaml`, by default), like [project-specific](project.md) ones; or
+
+* [global configuration files](../yaml/index.md#project-level-and-global-configuration-files)
+  (`config.yaml`).
+
+However, non-project-specific options in the project-level configuration file in
+the `global-project` directory are ignored by Stack.
+
+The options below are listed in alphabetic order.
 
 ## allow-different-user
 

doc/configure/yaml/project.md

@@ -3,7 +3,8 @@
 # Project-specific configuration
 
 Project-specific configuration options are valid only in a project-level
-configuration file (`stack.yaml`, by default).
+configuration file (`stack.yaml`, by default). Most of Stack's configuration
+options are [non-project specific](non-project.md).
 
 Each of the Haskell packages to which a Stack project relates is either a
 **project package** that is part of the project and located locally or a package

doc/tutorial/cabal_flags_and_ghc_options.md

@@ -15,20 +15,27 @@ command:
 stack build --flag yackage:-upload
 ~~~
 
-This means: when compiling the `yackage` package, turn off the `upload` flag
-(thus the `-` in `-upload`). Unlike other tools, Stack is explicit about which
-package's flag you want to change. It does this for two reasons:
+This means: when compiling the `yackage` package, turn off the `upload` Cabal
+flag (thus the `-` in `-upload`). Unlike other tools, Stack is explicit about
+which package's flag you want to change. It does this for two reasons:
 
 1. There's no global meaning for Cabal flags, and therefore two packages can
    use the same flag name for completely different things.
+
 2. By following this approach, we can avoid unnecessarily recompiling snapshot
-   packages that happen to use a flag that we're using.
+   packages that happen to use a Cabal flag that we're using.
 
-You can also change flag values on the command line for extra-dep and snapshot
-packages. If you do this, that package will automatically be promoted to an
-extra-dep, since the build plan is different than what the plan snapshot
+You can also change Cabal flag values on the command line for extra-dep and
+snapshot packages. If you do this, that package will automatically be promoted
+to an extra-dep, since the build plan is different than what the plan snapshot
 definition would entail.
 
+If you have Cabal flags that you will be setting regularly when building your
+packages, you can add them to your Stack project-level configuration file
+(`stack.yaml`). For more information, see the
+[flags](../configure/yaml/project.md#flags) project-specific configuration
+option documentation.
+
 ## GHC options
 
 GHC options follow a similar logic as in managing Cabal flags, with a few
@@ -90,10 +97,13 @@ While this specific corner case does catch people by surprise, the overall goal
 of reproducible builds is - in the Stack maintainers' views - worth the
 confusion.
 
-Final point: if you have GHC options that you'll be regularly passing to your
-packages, you can add them to your `stack.yaml` file. For more information, see
-the [ghc-options](../configure/yaml/non-project.md#ghc-options) non-project
-specific configuration option documentation.
+If you have GHC options that you will be applying regularly when building your
+packages, you can add them to your Stack project-level configuration file
+(`stack.yaml`) or (if applicable) to a
+[global Stack configuration file](../configure/yaml/index.md#project-level-and-global-configuration-files).
+For more information, see the
+[ghc-options](../configure/yaml/non-project.md#ghc-options) non-project specific
+configuration option documentation.
 
 !!! note
 

doc/tutorial/project_configuration.md

@@ -25,11 +25,13 @@ is the `stack.yaml` file.
 ## `stack.yaml`
 
 Stack requires a Stack project-level configuration file for every project.
-`stack.yaml` is that file. The contents of the file define project-specific
-options and non-project-specific options that apply to the project.
+`stack.yaml` is that file. The contents of the file set project-specific and
+non-project-specific options that apply to the project. (Non-project
+specific options that affect the project may also be set in a
+[global Stack configuration file](../configure/yaml/index.md#project-level-and-global-configuration-files).)
 
-The contents of the file include comments beginning `#`. Ignoring those
-comments, the contents will look something like this:
+The contents of the `stack.yaml` file include comments beginning `#`. Ignoring
+those comments, the contents will look something like this:
 
 ~~~yaml
 snapshot: