add docs and changelog entry

Author: bacchanalia

changelog.d/pr-7851

@@ -1,7 +1,7 @@
 synopsis:  Better support for scripts
 packages: cabal-install
-prs: #7851 #7925 #7938 #7990
-issues: #7842 #7073 #6354 #6149 #5508
+prs: #7851 #7925 #7938 #7990 #7997
+issues: #7842 #7073 #6354 #6149 #5508 #5698
 
 description: {
 
@@ -15,5 +15,7 @@ description: {
 - The name of the generated script executable has been changed from "script" to
   "cabal-script-<your-sanitized-script-name>" for easier process management.
 - Reduce the default verbosity of scripts, so that the build output doesn't interfere with the script output.
+- Scripts now support a project metadata block that allows them to use options
+  that would normally be set in a cabal.project file.
 
 }

doc/cabal-commands.rst

@@ -465,14 +465,21 @@ a script that looks like:
 
     #!/usr/bin/env cabal
     {- cabal:
-    build-depends: base ^>= 4.11
-                , shelly ^>= 1.8.1
+    build-depends: base ^>= 4.14
+                , shelly ^>= 1.10
+    -}
+    {- project:
+    with-compiler: ghc-8.10.7
     -}
 
     main :: IO ()
     main = do
         ...
 
+Where there cabal metadata block is mandatory and contains fields from a
+package executable block, and the project metadata block is optional and
+contains fields that would be in the cabal.project file in a regular project.
+
 It can either be executed like any other script, using ``cabal`` as an
 interpreter, or through this command: