Re commercialhaskell#6478 Improve ghc-options documentation

Author: mpilgrem

doc/build_command.md

@@ -435,15 +435,19 @@ The effect of `--fast` can be overriden with Stack's
 
 ### `--ghc-options` option
 
+Augment and, if applicable, override any GHC command line options specified in
+Cabal files (including those created from `package.yaml` files) or in Stack's
+YAML configuration files.
+
 `stack build --ghc-options <ghc_options>` passes the specified command line
 options to GHC, depending on Stack's
 [`apply-ghc-options`](yaml_configuration.md#apply-ghc-options) YAML
 configuration option. This option can be specified multiple times.
 
-GHC's command line options are evaluated from left to right. Later options can
-override the effect of earlier ones. Stack applies the options specified at the
-command line last. Any existing GHC command line options of a package are
-applied after those specified at the command line.
+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.
 
 ### `--[no-]library-profiling` flag
 

doc/yaml_configuration.md

@@ -1003,7 +1003,10 @@ arguments include `standard`, `gmp4`, `nopie`, `tinfo6`, `tinfo6-libc6-pre232`,
 Default: `{}`
 
 Related command line (takes precedence):
-[`stack build --ghc-options`](build_command.md#ghc-options-option) option
+[`stack build --ghc-options`](build_command.md#-ghc-options-option) option
+
+Augment and, if applicable, override any GHC command line options specified in
+Cabal files (including those created from `package.yaml` files).
 
 `ghc-options` can specify GHC command line options for a named package, all
 local packages that are targets (using the `$targets` key), all local packages
@@ -1019,10 +1022,11 @@ ghc-options:
 ~~~
 
 GHC's command line options are _order-dependent_ and evaluated from left to
-right. Later options can override earlier options. Stack applies options (as
-applicable) in the order of `$everything`, `$locals`, `$targets`, and then those
-for the named package. Any existing GHC command line options of a package are
-applied after those specified in Stack's YAML configuration.
+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.
 
 Since Stack 1.6.1, setting a GHC options for a specific package will
 automatically promote it to a local package (much like setting a custom package