Merge pull request #9515 from cabalism/doc/project-conditional-blocks…

…-8945

Warn about project conditional blocks

doc/cabal-package-description-file.rst

@@ -2426,6 +2426,8 @@ Configuration Flags
     negated value. However, if the flag is manual, then the default
     value (which can be overridden by commandline flags) will be used.
 
+.. _conditional-blocks:
+
 Conditional Blocks
 ^^^^^^^^^^^^^^^^^^
 

doc/cabal-project-description-file.rst

@@ -40,13 +40,28 @@ directories when there is none in the current directory.
 Conditionals and imports
 ------------------------
 
-As of ``cabal-install`` version 3.8, cabal supports conditional logic
-and imports in ``cabal.project`` files. :ref:`conditions` in cabal
-may case on operating system, architecture, and
-compiler (i.e. there is no support for a notion of custom flags in
-project files). Imports may specify local filepaths or remote urls,
-and may reference either cabal.project files or v1-style cabal.config
-freeze files. As a usage example:
+As of ``cabal-install`` version 3.8, cabal supports conditional logic and
+imports in ``cabal.project`` files.
+
+    .. warning::
+
+      While :ref:`conditional blocks<conditional-blocks>` can appear anywhere
+      within component or common sections of a package, their placement within a
+      project is restricted.  Conditions may only be introduced at the top level
+      of a project.
+
+      Of the :ref:`condition tests<conditions>`, only packages can test for
+      flags. Projects can test for operating system, architecture, compiler and
+      the boolean constants.
+
+      - :samp:`os({name})`
+      - :samp:`arch({name})`
+      - :samp:`impl({compiler})`
+      - ``true``
+      - ``false``
+
+Imports may specify local filepaths or remote urls, and may reference either
+cabal.project files or v1-style cabal.config freeze files. As a usage example:
 
 ::