Clarify splitting/passing behaviour for --*-option(s) arguments

Cabal/src/Distribution/Simple/Setup/Benchmark.hs

@@ -118,7 +118,8 @@ benchmarkOptions' showOrParseArgs =
         []
         ["benchmark-options"]
         ( "give extra options to benchmark executables "
-            ++ "(name templates can use $pkgid, $compiler, "
+            ++ "(split on spaces, \"quotes\" prevent splitting; "
+            ++ "name templates can use $pkgid, $compiler, "
             ++ "$os, $arch, $benchmark)"
         )
         benchmarkOptions
@@ -132,7 +133,7 @@ benchmarkOptions' showOrParseArgs =
         []
         ["benchmark-option"]
         ( "give extra option to benchmark executables "
-            ++ "(no need to quote options containing spaces, "
+            ++ "(passed directly as a single argument; "
             ++ "name template can use $pkgid, $compiler, "
             ++ "$os, $arch, $benchmark)"
         )

Cabal/src/Distribution/Simple/Setup/Common.hs

@@ -275,7 +275,9 @@ programDbOption progDb showOrParseArgs get set =
         [prog ++ "-option"]
         ( "give an extra option to "
             ++ prog
-            ++ " (no need to quote options containing spaces)"
+            ++ " (passed directly to "
+            ++ prog
+            ++ " as a single argument)"
         )
         get
         set
@@ -312,7 +314,10 @@ programDbOptions progDb showOrParseArgs get set =
       option
         ""
         [prog ++ "-options"]
-        ("give extra options to " ++ prog)
+        ( "give extra options to "
+            ++ prog
+            ++ " (split on spaces, \"quotes\" prevent splitting)"
+        )
         get
         set
         (reqArg' "OPTS" (\args -> [(prog, splitArgs args)]) (const []))

Cabal/src/Distribution/Simple/Setup/Test.hs

@@ -245,7 +245,8 @@ testOptions' showOrParseArgs =
         []
         ["test-options"]
         ( "give extra options to test executables "
-            ++ "(name templates can use $pkgid, $compiler, "
+            ++ "(split on spaces, \"quotes\" prevent splitting; "
+            ++ "name templates can use $pkgid, $compiler, "
             ++ "$os, $arch, $test-suite)"
         )
         testOptions
@@ -259,7 +260,7 @@ testOptions' showOrParseArgs =
         []
         ["test-option"]
         ( "give extra option to test executables "
-            ++ "(no need to quote options containing spaces, "
+            ++ "(passed directly as a single argument; "
             ++ "name template can use $pkgid, $compiler, "
             ++ "$os, $arch, $test-suite)"
         )

doc/cabal-commands.rst

@@ -1060,13 +1060,17 @@ Examples:
 Configuration flags can be specified on the command line and these extend the project
 configuration from the 'cabal.project', 'cabal.project.local' and other files.
 
-.. option:: --repl-options=FLAG
+.. option:: --repl-options=OPTS
 
     To avoid ``ghci``-specific flags from triggering unneeded global rebuilds, these
-    flags are stripped from the internal configuration. As a result,
-    ``--ghc-options`` will no longer (reliably) work to pass flags to ``ghci`` (or
-    other REPLs). Instead, you should use the ``--repl-options`` flag to
-    specify these options to the invoked REPL.
+    flags are stripped from the internal configuration when using
+    ``--ghc-option`` or ``--ghc-options``. As a result, ``--ghc-options`` will
+    not (reliably) work to pass flags to ``ghci`` (or other REPLs).
+    ``--repl-options`` bypasses this and allows you to specify options to the
+    invoked REPL without influencing the build configuration for other packages.
+
+    Note: ``--repl-options`` does not accept ``"quotes"`` to pass options
+    containing spaces to the REPL.
 
 .. option:: --repl-no-load
 

doc/setup-commands.rst

@@ -210,19 +210,31 @@ files of a package:
     to Cabal can be used in place of *prog*. For example:
     ``--alex-options="--template=mytemplatedir/"``. The *options* is
     split into program options based on spaces. Any options containing
-    embedded spaced need to be quoted, for example
-    ``--foo-options='--bar="C:\Program File\Bar"'``. As an alternative
-    that takes only one option at a time but avoids the need to quote,
-    use :option:`--PROG-option` instead.
+    embedded spaces need to be quoted with "double quotes", for example
+    ``--foo-options='--bar="C:\Program Files\Bar"'``. (The ``'single'`` quotes
+    are for your shell, the ``"double"`` quotes are passed to Cabal.) As an
+    alternative that takes only one option at a time but avoids the need to
+    quote, use :option:`--PROG-option` instead.
+
+    Note: if *prog* is ``ghc``, then options that do not affect build
+    artifacts, such as warning flags, are dropped. This is because
+    ``--ghc-options`` applies to GHC for the entire build plan, not just the
+    current package, and recompiling the entire dependency tree is probably
+    unintended. If you want to apply some options to ``cabal repl`` only, pass
+    ``--repl-options`` to ``cabal repl``.
 
 .. option:: --PROG-option=OPT
 
-    Specify a single additional option to the program *prog*. For
+    Specify a single additional option to the program *prog*. The option is
+    passed to *prog* as a single argument, without any splitting. For
     passing an option that contains embedded spaces, such as a file name
     with embedded spaces, using this rather than :option:`--PROG-options`
     means you do not need an additional level of quoting. Of course if you
     are using a command shell you may still need to quote, for example
-    ``--foo-options="--bar=C:\Program File\Bar"``.
+    ``--foo-options="--bar=C:\Program Files\Bar"``.
+
+    The same note regarding dropping flags as for :option:`--PROG-options`
+    applies to ``--PROG-option`` as well.
 
 All of the options passed with either :option:`--PROG-options`
 or :option:`--PROG-option` are passed in the order they were
@@ -1443,11 +1455,11 @@ Flags for repl:
 
 .. option:: --PROG-option=OPT
 
-    Give an extra option to PROG (no need to quote options containing spaces).
+    Give an extra option to PROG (passed directly to PROG as a single argument).
 
 .. option:: --PROG-options=OPTS
 
-    Give extra options to PROG.
+    Give extra options to PROG (split on spaces, "quotes" prevent splitting).
 
 .. option:: --repl-no-load