Re commercialhaskell#6564 Improve --flag documentation

The added warning is based on commercialhaskell#6565.

Author: mpilgrem

doc/build_command.md

@@ -236,21 +236,44 @@ Set the flag to build nothing and output information about the build plan.
 
 ### `--flag` option
 
+The option can be specified multiple times. It has two forms:
+
+* `--flag <package_name>:[-]<flag_name>`; and
+
+* `--flag *:[-]<flag_name>`.
+
 `stack build --flag <package_name>:[-]<flag_name>` sets (or unsets) the
-specified Cabal flag for the specified package.
+specified Cabal flag for the specified package. Stack will report an error if:
 
-This option can be specified multiple times to set (or unset) multiple Cabal
-flags.
+* a package of that name is not known to Stack; or
 
-The same Cabal flag name can be set (or unset) for multiple packages (at the
-command line only) with:
+* a flag of that name is not a flag of that package.
 
-~~~text
-stack build --flag *:[-]<flag_name>
-~~~
+This overrides:
+
+* any Cabal flag specifications for the package in Stack's project-level
+  configuration file (`stack.yaml`); and
+
+* any use of `--flag *` (see below).
+
+`stack build --flag *:[-]<flag_name>` sets (or unsets) the specified Cabal flag
+for all packages (project packages and dependencies) (whether or not a flag of
+that name is a flag of the package).
+
+This overrides any Cabal flag specifications for packages in Stack's
+project-level configuration file (`stack.yaml`).
+
+!!! note
+
+    In order to set a Cabal flag for a GHC boot package, the package must be
+    specified as an [extra-dep](yaml_configuration.md#extra-deps).
+
+!!! warning
 
-In order to set a Cabal flag for a GHC boot package, the package must be
-specified as an extra-dep.
+    Stack creates snapshots when building immutable dependencies of projects.
+    The names of Cabal flags that have been manually set as disabled distinguish
+    one such snapshot from another. However, the names of Cabal flags that have
+    been set as enabled do not do so.
 
 ### `--[no-]force-dirty` flag
 

doc/yaml_configuration.md

@@ -311,8 +311,17 @@ If a specified Cabal flag for a package included directly in a snapshot is
 different to the Cabal flag specified for that package in the snapshot, then the
 package will automatically be promoted to be an [extra-dep](#extra-deps).
 
-In order to set a Cabal flag for a GHC boot package, the package must be
-specified as an [extra-dep](#extra-deps).
+!!! note
+
+    In order to set a Cabal flag for a GHC boot package, the package must be
+    specified as an [extra-dep](#extra-deps).
+
+!!! warning
+
+    Stack creates snapshots when building immutable dependencies of projects.
+    The names of Cabal flags that have been manually set as disabled distinguish
+    one such snapshot from another. However, the names of Cabal flags that have
+    been set as enabled do not do so.
 
 ### drop-packages