diff --git a/Cabal/src/Distribution/Simple/Setup/Benchmark.hs b/Cabal/src/Distribution/Simple/Setup/Benchmark.hs
index f33e374c15d28540bfc7654bccde3cb65be568df..79dfe88e79f86882de94378caf835bbff6c22331 100644
--- a/Cabal/src/Distribution/Simple/Setup/Benchmark.hs
+++ b/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, use \"\" to 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)"
         )
diff --git a/Cabal/src/Distribution/Simple/Setup/Common.hs b/Cabal/src/Distribution/Simple/Setup/Common.hs
index 8b700841ad11758eca09b2db9f34072bd6a1ad7c..1a7e6691bab01554c1ea00a5698c41210eb0a30d 100644
--- a/Cabal/src/Distribution/Simple/Setup/Common.hs
+++ b/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, use \"\" to prevent splitting)"
+        )
         get
         set
         (reqArg' "OPTS" (\args -> [(prog, splitArgs args)]) (const []))
diff --git a/Cabal/src/Distribution/Simple/Setup/Test.hs b/Cabal/src/Distribution/Simple/Setup/Test.hs
index 6e5da7d7643744984e047cae055d640b7ae6c718..9c65097c3546d0fa46f484416bba8c0f0164fd9f 100644
--- a/Cabal/src/Distribution/Simple/Setup/Test.hs
+++ b/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, use \"\" to 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)"
         )
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 7f0b37ac48f3564ccad33bd499d40b49fcf2f97b..22f1a9089a6a2a9ab865f9f28e5bd942cdb99232 100644
--- a/doc/cabal-commands.rst
+++ b/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 double quotes (``""``) to pass options
+    containing spaces to the REPL.
 
 .. option:: --repl-no-load
 
diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst
index 0807ddf2aa47f02745db036dc49549a98f0465d6..970439e748de7c1edd31b06113a4f518f1cfa5de 100644
--- a/doc/setup-commands.rst
+++ b/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.)
+    For 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, use "" to prevent splitting).
 
 .. option:: --repl-no-load