add documentation for single-file Haskell scripts (#8559)

* add documentation for single-file Haskell scripts

This is a useful feature which I think would benefit newcomers by being a top-level, early entry in the docs. See: https://stackoverflow.com/a/65541020

* Add project metadata and cabal run doc link

* Fix cabal run link

* Add custom anchor for 'cabal run'

* Qualify use of executable shell script to unix-likes

doc/cabal-commands.rst

@@ -845,6 +845,8 @@ The configuration information for the script is cached under the cabal directory
 and can be pre-built with ``cabal build path/to/script``.
 See ``cabal run`` for more information on scripts.
 
+.. _cabal run:
+
 cabal run
 ^^^^^^^^^
 

doc/getting-started.rst

@@ -166,6 +166,44 @@ Now you can build and re-run your code to see the new output:
         /    /  /    /   \    \
        /____/  /____/     \____\
 
+Run a single-file Haskell script
+--------------------------------
+
+Cabal also enables us to run single-file Haskell scripts
+without creating a project directory or ``.cabal`` file.
+The cabal directives are placed in the file within a comment.
+
+.. code-block:: haskell
+
+    #!/usr/bin/env cabal
+    {- cabal:
+    build-depends: base, split
+    -}
+
+    import Data.List.Split (chunksOf)
+
+    main :: IO ()
+    main = getLine >>= print . chunksOf 3
+
+This can be run using ``cabal run myscript``.
+On Unix-like systems this can be run directly with execute permission.
+
+.. code-block:: console
+
+    $ cabal run myscript
+
+    $ chmod +x myscript
+    $ ./myscript
+
+Project metadata can also be included:
+
+.. code-block:: haskell
+
+    {- project:
+    with-compiler: ghc-8.10.7
+    -}
+
+See more in the documentation for :ref:`cabal run`.
 
 What Next?
 ----------