Merge pull request #9905 from haskell/fix8141

Fix #8141 Don't refer to 'custom-setup' as 'optional'

Author: mergify[bot]

doc/cabal-package-description-file.rst

@@ -2869,9 +2869,10 @@ Declaring a ``custom-setup`` stanza also enables the generation of
    :synopsis: Build information for ``Custom`` and ``Hooks`` build types
    :since: 1.24
 
-   The :pkg-section:`custom-setup` stanza contains information needed
-   for the compilation of custom ``Setup.hs`` scripts as well as for
-   ``SetupHooks.hs`` hooks modules.
+   A :pkg-section:`custom-setup` stanza is required for
+   :pkg-field:`build-type` ``Custom`` and will be ignored (with a warning) for
+   other build types. The stanza contains information needed for the compilation
+   of custom ``Setup.hs`` scripts or ``SetupHooks.hs`` hooks modules. For example:
 
 ::
 
@@ -2904,7 +2905,7 @@ Backward compatibility and ``custom-setup``
 
 Versions prior to Cabal 1.24 don't recognise ``custom-setup`` stanzas,
 and will behave agnostic to them (except for warning about an unknown
-section). Consequently, versions prior to Cabal 1.24 can't ensure the
+'section'). Consequently, versions prior to Cabal 1.24 can't ensure the
 declared dependencies ``setup-depends`` are in scope, and instead
 whatever is registered in the current package database environment
 will become eligible (and resolved by the compiler) for the
@@ -2914,8 +2915,9 @@ The availability of the
 ``MIN_VERSION_package_(A,B,C)`` CPP macros
 inside ``Setup.hs`` scripts depends on the condition that either
 
-- a ``custom-setup`` section has been declared (or ``cabal build`` is being
-  used which injects an implicit hard-coded ``custom-setup`` stanza if it's missing), or
+- a ``custom-setup`` stanza has been declared (or ``cabal build`` is being used
+  which injects an implicit hard-coded ``custom-setup`` stanza if it's missing),
+  or
 - GHC 8.0 or later is used (which natively injects package version CPP macros)
 
 Consequently, if you need to write backward compatible ``Setup.hs``