Simplify references to configuration files.

mpilgrem · mpilgrem · commit 8baa9eb405f4 · 2024-07-26T20:28:01.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -548,7 +548,7 @@ The `pedantic` job runs on `ubuntu` only and builds Stack with the
 `--pedantic` flag.
 
 The `unit-tests` job runs on a matrix of operating systems and Stack
-project-level YAML configuration files (`stack.yaml`, by default). It builds and
+project-level configuration files (`stack.yaml`, by default). It builds and
 tests Stack with the following flags: `--haddock --no-haddock-deps`.
 
 Its approach to creating a cache depends on the operating system. Its 'Cache
diff --git a/doc/commands/build_command.md b/doc/commands/build_command.md
@@ -647,26 +647,27 @@ The effect of `--fast` can be overriden with Stack's
     options are used during the configure step of the Cabal build process; see
     Stack's
     [`configure-options`](../configure/yaml/non-project.md#configure-options)
-    YAML configuration option.
+    non-project specific configuration option.
 
 ### `--ghc-options` option
 
 GHC command line options can be specified for a package in its Cabal file
 (including one created from a `package.yaml` file). This option augments and, if
 applicable (see below), overrides any such GHC command line options and those
-specified in Stack's YAML configuration files - see the
-[`ghc-options`](../configure/yaml/non-project.md#ghc-options) configuration
-option.
+specified in Stack's configuration files - see the
+[`ghc-options`](../configure/yaml/non-project.md#ghc-options) non-project
+specific configuration option.
 
 `stack build --ghc-options <ghc_options>` passes the specified command line
 options to GHC, depending on Stack's
-[`apply-ghc-options`](../configure/yaml/non-project.md#apply-ghc-options) YAML
-configuration option. This option can be specified multiple times.
+[`apply-ghc-options`](../configure/yaml/non-project.md#apply-ghc-options)
+non-project specific configuration option. This option can be specified multiple
+times.
 
 GHC's command line options are _order-dependent_ and evaluated from left to
 right. Later options can override the effect of earlier ones. Any GHC command
 line options for a package specified at Stack's command line are applied after
-those specified in Stack's YAML configuration files.
+those specified in Stack's configuration files.
 
 ### `--[no-]library-profiling` flag
 
@@ -880,9 +881,9 @@ package is targetted in a multi-package project (for example, using
   contents of the log files to the standard error output stream of the console
   at the end of the build, use Stack's `dump-logs` option. For further
   information about that option, see the
-  [YAML configuration](../configure/yaml/non-project.md#dump-logs)
-  documentation. The default `dump-logs` mode is to output the contents of any
-  log files that include GHC warnings.
+  [`dump-logs](../configure/yaml/non-project.md#dump-logs) non-project
+  specific configuration option documentation. The default `dump-logs` mode is
+  to output the contents of any log files that include GHC warnings.
 
 ### `--[no]-open` flag
 
@@ -936,8 +937,7 @@ All the following examples assume that:
     consequently, the project-level configuration will be determined by a
     `stack.yaml` file in the `global-project` directory in the
     [Stack root](../topics/stack_root.md) (for further information, see the
-    [YAML configuration](../configure/yaml/yaml_configuration.md)
-    documentation); and
+    [configuration](../configure/yaml/yaml_configuration.md) documentation); and
 
 *   if `stack build` is commanded in a project directory, there is a
     `stack.yaml` file in that directory.
diff --git a/doc/commands/config_command.md b/doc/commands/config_command.md
@@ -7,7 +7,7 @@ stack config COMMAND
 
 Available commands:
   env                      Print environment variables for use in a shell
-  set                      Sets a key in YAML configuration file to value
+  set                      Sets a key in configuration file to value
 ~~~
 
 The `stack config` commands provide assistance with accessing or modifying
@@ -55,8 +55,8 @@ Available commands:
                            installation or not.
 ~~~
 
-The `stack config set` commands allow the values of keys in YAML configuration
-files to be set. See `stack config set` for the available keys.
+The `stack config set` commands allow the values of keys in configuration files
+to be set. See `stack config set` for the available keys.
 
 !!! note
 
@@ -69,10 +69,12 @@ files to be set. See `stack config set` for the available keys.
 stack config set install-ghc [--global] true|false
 ~~~
 
-`stack config set install-ghc true` or `false` sets the `install-ghc` key in a
-YAML configuration file, accordingly. By default, the project-level
-configuration file (`stack.yaml`, by default) is altered. The `--global` flag
-specifies the user-specific global configuration file (`config.yaml`).
+`stack config set install-ghc true` or `false` sets the
+[`install-ghc`](../configure/yaml/non-project.md#install-ghc) non-project
+specific configuration option in a configuration file, accordingly. By default,
+the project-level configuration file (`stack.yaml`, by default) is altered. The
+`--global` flag specifies the user-specific global configuration file
+(`config.yaml`).
 
 ## The `stack config set package-index download-prefix` command
 
@@ -83,10 +85,12 @@ stack config set package-index download-prefix [--global] [URL]
 ~~~
 
 `stack config set package-index download-prefix <url>` sets the
-`download-prefix` key of the `package-index` key in a YAML configuration file,
-accordingly. By default, the project-level configuration file (`stack.yaml`, by
-default) is altered. The `--global` flag specifies the user-specific global
-configuration file (`config.yaml`).
+`download-prefix` key of the
+[`package-index`](../configure/yaml/non-project.md#package-index) non-project
+specific configuration option in a configuration file, accordingly. By default,
+the project-level configuration file (`stack.yaml`, by default) is  altered. The
+`--global` flag specifies the user-specific global configuration  file
+(`config.yaml`).
 
 ## The `stack config set resolver` command
 
@@ -130,7 +134,9 @@ Known bug:
 stack config set system-ghc [--global] true|false
 ~~~
 
-`stack config set system-ghc true` or `false` sets the `system-ghc` key in a
-YAML configuration file, accordingly. By default, the project-level
-configuration file (`stack.yaml`, by default) is altered. The `--global` flag
-specifies the user-specific global configuration file (`config.yaml`).
+`stack config set system-ghc true` or `false` sets the
+[`system-ghc`](../configure/yaml/non-project.md#system-ghc) non-project
+specific configuration option in a configuration file, accordingly. By default,
+the project-level configuration file (`stack.yaml`, by default) is altered. The
+`--global` flag specifies the user-specific global configuration file
+(`config.yaml`).
diff --git a/doc/commands/init_command.md b/doc/commands/init_command.md
@@ -6,7 +6,7 @@
 stack init [DIR(S)] [--omit-packages] [--force] [--ignore-subdirs]
 ~~~
 
-`stack init` initialises Stack's default project-level YAML configuration file
+`stack init` initialises Stack's default project-level configuration file
 (`stack.yaml`) for an existing project, based on the Cabal file or
 `package.yaml` file for each of its packages.
 
diff --git a/doc/commands/ls_command.md b/doc/commands/ls_command.md
@@ -211,8 +211,9 @@ example of the applied style. The latter can be disabled with flags `--no-sgr`
 and `--no-example`.
 
 The flag `--basic` specifies a more basic report, in the format that is accepted
-by Stack's command line option `--stack-colors` and the YAML configuration key
-`stack-colors`.
+by Stack's command line option `--stack-colors` and the
+[`stack-colors`](../configure/yaml/non-project.md#stack-colors) non-project
+specific configuration option.
 
 ## The `stack ls tools` command
 
diff --git a/doc/commands/path_command.md b/doc/commands/path_command.md
@@ -22,12 +22,12 @@ Pass the following flags for information about specific files or locations:
 |--compiler-bin         |The directory containing the GHC executable.          |
 |--compiler-exe         |The GHC executable.                                   |
 |--compiler-tools-bin   |The directory containing binaries specific to a particular compiler.|
-|--config-location      |Stack's project-level YAML configuration file (`stack.yaml`, by default).|
+|--config-location      |Stack's project-level configuration file (`stack.yaml`, by default).|
 |--dist-dir             |The dist work directory, relative to the package directory.|
 |--extra-include-dirs   |Extra include directories.                            |
 |--extra-library-dirs   |Extra library directories.                            |
 |--ghc-package-path     |The `GHC_PACKAGE_PATH` environment variable.          |
-|--global-config        |Stack's user-specific global YAML configuration file (`config.yaml`).|
+|--global-config        |Stack's user-specific global configuration file (`config.yaml`).|
 |--global-pkg-db        |The global package database.                          |
 |--local-bin            |The directory in which Stack installs executables.    |
 |--local-doc-root       |The root directory for local project documentation.   |
diff --git a/doc/commands/sdist_command.md b/doc/commands/sdist_command.md
@@ -27,7 +27,8 @@ available modes for use with Cabal file revisions are `lower-revision`,
 `upper-revision` and `both-revision`.
 
 For futher information, see the
-[YAML configuration](../configure/yaml/non-project.md#pvp-bounds) documentation.
+[`pvp-bounds`](../configure/yaml/non-project.md#pvp-bounds) non-project specific
+configuration option documentation.
 
 ## `--tar-dir` option
 
diff --git a/doc/commands/setup_command.md b/doc/commands/setup_command.md
@@ -23,9 +23,9 @@ By default:
 Pass the option `--ghc-bindist <url>` to specify the URL of the GHC to be
 downloaded and installed. This option requires the use of the `--ghc-variant`
 option specifying a custom GHC variant. For further information about the
-`--ghc-variant` option, see the see the
-[YAML configuration](../configure/yaml/non-project.md#ghc-variant)
-documentation.
+`--ghc-variant` option, see the
+[`ghc-variant`](../configure/yaml/non-project.md#ghc-variant) non-project
+specific configuration option documentation.
 
 If Stack is configured not to install GHC (`install-ghc: false` or passing the
 `--no-install-ghc` flag) then `stack setup` will warn that the flag and the
diff --git a/doc/commands/upload_command.md b/doc/commands/upload_command.md
@@ -54,7 +54,8 @@ available modes for use with Cabal file revisions are `lower-revision`,
 `upper-revision` and `both-revision`.
 
 For futher information, see the
-[YAML configuration](../configure/yaml/non-project.md#pvp-bounds) documentation.
+[`pvp-bounds`](../configure/yaml/non-project.md#pvp-bounds) non-project
+specific configuration option documentation.
 
 The `--tar-dir <path_to_directory>` option determines whether the package
 archive should be copied to the specified directory.
diff --git a/doc/configure/environment_variables.md b/doc/configure/environment_variables.md
@@ -88,24 +88,24 @@ sequences for color to its output.
 ## `STACK_CONFIG`
 
 Related command: all commands that make use of Stack's
-[global YAML configuration files](yaml/yaml_configuration.md) (`config.yaml`).
+[global configuration](yaml/yaml_configuration.md) files (`config.yaml`).
 
 The environment variable `STACK_CONFIG` can be used to specify an absolute path
-to the user-specific global YAML configuration file, overriding the default.
+to the user-specific global configuration file, overriding the default.
 
 ## `STACK_GLOBAL_CONFIG`
 
 Related command: all commands that make use of Stack's
-[global YAML configuration files](yaml/yaml_configuration.md) (`config.yaml`).
+[global configuration](yaml/yaml_configuration.md) files (`config.yaml`).
 
 The environment variable `STACK_GLOBAL_CONFIG` can be used to specify an
-absolute path to the system-wide global YAML configuration file, overriding the
+absolute path to the system-wide global configuration file, overriding the
 default.
 
 ## `STACK_ROOT`
 
 Related command: all commands that make use of Stack's
-[user-specific global YAML configuration file](yaml/yaml_configuration.md)
+[user-specific global configuration](yaml/yaml_configuration.md) file
 (`config.yaml`).
 
 Overridden by: Stack's global
@@ -131,7 +131,7 @@ the root directory of the project or package. The relative path cannot include a
 ## `STACK_XDG`
 
 Related command: all commands that make use of Stack's
-[user-specific global YAML configuration file](yaml/yaml_configuration.md)
+[user-specific global configuration](yaml/yaml_configuration.md) file
 (`config.yaml`).
 
 Overridden by: the use of Stack's `STACK_ROOT` environment variable, or the use
@@ -145,10 +145,10 @@ set to any non-empty value.
 ## `STACK_YAML`
 
 Related command: all commands that make use of Stack's
-[project-level YAML configuration file](yaml/yaml_configuration.md).
+[project-level configuration](yaml/yaml_configuration.md).
 
 Overridden by: Stack's global
 [`--stack-yaml`](global_flags.md#-stack-yaml-option) option.
 
 The environment variable `STACK_YAML` can be used to specify Stack's
-project-level YAML configuration file.
+project-level configuration file.
diff --git a/doc/configure/global_flags.md b/doc/configure/global_flags.md
@@ -34,8 +34,8 @@ specific configuration [option](yaml/non-project.md#color).
 ## `--compiler` option
 
 Pass the option `--compiler <compiler>` to specify the compiler. For further
-information, see the [YAML configuration](yaml/non-project.md#compiler)
-documentation.
+information, see the [`compiler`](yaml/non-project.md#compiler) non-project
+specific configuration option documentation.
 
 ## `--custom-preprocessor-extensions` option
 
@@ -130,8 +130,8 @@ specific configuration [option](yaml/non-project.md#local-bin-path).
 
 ## `--lock-file` option
 
-Default: `read-write`, if snapshot specified in YAML configuration file;
-`read-only`, if a different snapshot is specified on the command line.
+Default: `read-write`, if snapshot specified in the project-level configuration
+file; `read-only`, if a different snapshot is specified on the command line.
 
 Pass the option `--lock-file <mode>` to specify how Stack interacts with lock
 files. Valid modes are:
@@ -223,8 +223,8 @@ corresponding non-project specific configuration
 [:octicons-tag-24: 2.15.1](https://github.com/commercialhaskell/stack/releases/tag/v2.15.1)
 
 Pass the option `--snapshot <snapshot>` to specify the snapshot. For further
-information, see the [YAML configuration](yaml/project.md#snapshot)
-documentation.
+information, see the [`snapshot`](yaml/project.md#snapshot) project-specific
+configuration option documentation.
 
 At the command line (only):
 
diff --git a/doc/configure/index.md b/doc/configure/index.md
@@ -20,13 +20,13 @@ The existence or content of certain environment variables can affect how Stack
 behaves. For further information, see the
 [environment variables](environment_variables.md) documentation.
 
-## YAML configuration files
+## Configuration files
 
-Stack is configured by the content of YAML files. A global YAML configuration
-file contains non-project specific options. A project-level YAML configuration
-file contains project-specific options and may contain non-project specific
-options. For further information, see the
-[YAML configuration](yaml/yaml_configuration.md) documentation.
+Stack is configured by the content of files in the YAML formal. A global
+configuration file contains non-project specific options. A project-level
+configuration file contains project-specific options and may contain non-project
+specific options. For further information, see the
+[configuration](yaml/yaml_configuration.md) documentation.
 
 ## Global flags and options
 
diff --git a/doc/configure/yaml/non-project.md b/doc/configure/yaml/non-project.md
@@ -271,8 +271,8 @@ This option specifies when to use color in output. The option is used as
 versions before Windows 10, for terminals that do not support color codes, the
 default is 'never'; color may work on terminals that support color codes.
 
-(The British English spelling (colour) is also accepted. In yaml configuration
-files, the American spelling is the alternative that has priority.)
+(The British English spelling (colour) is also accepted. In configuration files,
+the American spelling is the alternative that has priority.)
 
 ## compiler
 
@@ -683,7 +683,7 @@ right. Later options can override the effect of earlier ones. Stack applies
 options (as applicable) in the order of `$everything`, `$locals`, `$targets`,
 and then those for the named package. Any GHC command line options for a package
 specified at Stack's command line are applied after those specified in Stack's
-YAML configuration files.
+configuration files.
 
 Since Stack 1.6.1, setting a GHC options for a specific package will
 automatically promote it to a project package (much like setting a custom
@@ -1146,10 +1146,10 @@ By default, Stack obtains the dictionary from
 
 The `setup-info` dictionary is constructed in the following order:
 
-1. `setup-info` in the YAML configuration - inline configuration
+1. `setup-info` in the configuration - inline configuration
 2. `--setup-info-yaml` command line arguments - URLs or paths. Multiple
    locations may be specified.
-3. `setup-info-locations` in the YAML configuration - URLs or paths. See further
+3. `setup-info-locations` in the configuration - URLs or paths. See further
    below.
 
 The format of this key is the same as in the default
@@ -1387,8 +1387,8 @@ stack-colors: error=31:good=32:shell=35:dir=34:recommendation=32:target=95:modul
 In respect of styles used in verbose output, some of that output occurs before
 the configuration file is processed.
 
-(The British English spelling (colour) is also accepted. In YAML configuration
-files, the American spelling is the alternative that has priority.)
+(The British English spelling (colour) is also accepted. In configuration files,
+the American spelling is the alternative that has priority.)
 
 ## stack-developer-mode
 
diff --git a/doc/configure/yaml/yaml_configuration.md b/doc/configure/yaml/yaml_configuration.md
@@ -2,7 +2,8 @@
 
 # Configuration
 
-Stack is configured by the content of [YAML](https://yaml.org/) files.
+Stack is configured by the content of files in the [YAML](https://yaml.org/)
+format.
 
 ## Project-specific and non-project specific options
 
diff --git a/doc/faq.md b/doc/faq.md
@@ -97,7 +97,7 @@
     `global-project` directory in the [Stack root](topics/stack_root.md).
 
     For further information, see the
-    [YAML configuration](configure/yaml/yaml_configuration.md) documentation.
+    [configuration](configure/yaml/yaml_configuration.md) documentation.
 
 ??? question "How does Stack determine what GHC to use?"
 
diff --git a/doc/maintainers/haskellstack.org.md b/doc/maintainers/haskellstack.org.md
@@ -40,9 +40,9 @@ page using the flyout.
 Stack moved from MkDocs 0.17.3 to MkDocs 1.3.1 after publishing the
 documentation for Stack 2.7.5.
 
-A YAML configuration file, `.readthedocs.yaml` is included in the repository
-root directory. See https://docs.readthedocs.io/en/stable/config-file/v2.html.
-It specifies a Python requirements file in `doc/requirements.txt`.
+A configuration file, `.readthedocs.yaml` is included in the repository root
+directory. See https://docs.readthedocs.io/en/stable/config-file/v2.html. It
+specifies a Python requirements file in `doc/requirements.txt`.
 
 ## MkDocs
 
@@ -51,8 +51,8 @@ The `doc/requirements.txt` file pins the version of MkDocs. As at
 
     mkdocs==1.3.1
 
-A YAML configuration file, `mkdocs.yml` is included in the repository root
-directory. See https://www.mkdocs.org/user-guide/configuration/.
+A configuration file, `mkdocs.yml` is included in the repository root directory.
+See https://www.mkdocs.org/user-guide/configuration/.
 
 `site_dir: _site` specifies the directory where the output HTML and other files
 are created. This directory is added to the `.gitignore` file.
diff --git a/doc/topics/Stack_and_VS_Code.md b/doc/topics/Stack_and_VS_Code.md
diff --git a/doc/topics/debugging.md b/doc/topics/debugging.md
diff --git a/doc/topics/nix_integration.md b/doc/topics/nix_integration.md
diff --git a/doc/topics/stack_root.md b/doc/topics/stack_root.md
diff --git a/doc/tutorial/locations_used_by_stack.md b/doc/tutorial/locations_used_by_stack.md
