Clarify which project option can only be passed from the command line

changelog.d/pr-8949

@@ -0,0 +1,11 @@
+synopsis: Warn when project configuration options are going to be ignored.
+packages: cabal-install
+prs: #8949
+
+description: {
+
+Some project configuration options can only be specified from the command line.
+If the user specified those options from a project file, cabal-install would
+silently ignore them. Now cabal-install will emit a warning.
+
+}

doc/cabal-project.rst

@@ -297,9 +297,9 @@ package, and thus apply globally:
     :ref:`project-file<cmdoption-project-file>` path is also specified,
     it will be resolved relative to this directory.
 
-    The project directory need not contain a ``cabal.project`` file.
+    The project directory does not need to contain a ``cabal.project`` file.
 
-    This option cannot be specified via a ``cabal.project`` file.
+    This option can only be specified from the command line.
 
 .. _cmdoption-project-file:
 .. option:: --project-file=FILE
@@ -318,7 +318,7 @@ package, and thus apply globally:
     and then for the parent directory, until the project file is
     found or we have hit the top of the user's home directory.
 
-    This option cannot be specified via a ``cabal.project`` file.
+    This option can only be specified from the command line.
 
 .. option:: --ignore-project
 
@@ -880,21 +880,7 @@ feature was added.
     The command line variant of this flag is ``--enable-benchmarks`` and
     ``--disable-benchmarks``.
 
-.. cfg-field:: multi-repl: boolean
-               --enable-multi-repl
-               --disable-multi-repl
-    :synopsis: Enable starting a repl with multiple targets.
-
-    :default: ``False``
-
-    Allow starting GHCi with multiple targets. This requires GHC with multiple
-    home unit support (GHC-9.4+).
-
-    The closure of required components will be loaded.
-
-    The command line variant of this flag is ``--enable-multi-repl`` and
-    ``--disable-multi-repl``.
-
+.. _cmdoption-extra-prog-path:
 .. cfg-field:: extra-prog-path: paths (newline or comma separated)
                --extra-prog-path=PATH
     :synopsis: Add directories to program search path.
@@ -909,6 +895,10 @@ feature was added.
     The command line variant of this flag is ``--extra-prog-path=PATH``,
     which can be specified multiple times.
 
+    When specifying :ref:`--http-transport<cmdoption-http-transport>` from the
+    command line, only extra-prog-path from the command line are added to the
+    program search path.
+
 .. cfg-field:: run-tests: boolean
                --run-tests
     :synopsis: Run package test suite upon installation.
@@ -1587,7 +1577,7 @@ Advanced global configuration options
         The format and fields of the generated build information is currently experimental,
         in the future we might add or remove fields, depending on the needs of other tooling.
 
-
+.. _cmdoption-http-transport:
 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
                --http-transport=transport
     :synopsis: Transport to use with http(s) requests.
@@ -1598,6 +1588,12 @@ Advanced global configuration options
 
     The command line variant of this field is ``--http-transport=curl``.
 
+    If the project configuration imports remote urls, the user can only specify
+    the http-transport option from the command line.
+
+    When specifying the http-transport from the command line, the program
+    search path can only be influenced using :ref:`--extra-prog-path<cmdoption-extra-prog-path>`.
+
 .. cfg-field:: ignore-expiry: boolean
                --ignore-expiry
     :synopsis: Ignore Hackage expiration dates.