Tidy-up documentation of script to customise GHC installation

Author: mpilgrem

ChangeLog.md

@@ -1,6 +1,5 @@
 # Changelog
 
-
 ## Unreleased changes
 
 Release notes:
@@ -32,6 +31,8 @@ Other enhancements:
 * Fuller help is provided at the command line if a subcommand is missing (for
   example, `stack ls` now yields the equivalent of `stack ls --help`). See
   [#809](https://github.com/commercialhaskell/stack/issues/809)
+* Add the possibility of a `sh` script to customise fully GHC installation. See
+  [#5585](https://github.com/commercialhaskell/stack/pull/5585)
 
 Bug fixes:
 
@@ -59,8 +60,6 @@ Other enhancements:
 * `stack upload` supports authentication with a Hackage API key (via
   `HACKAGE_KEY` environment variable).
 
-* Add GHC installation hooks wrt [#5585](https://github.com/commercialhaskell/stack/pull/5585)
-
 Bug fixes:
 
 * Ensure that `extra-path` works for case-insensitive `PATH`s on Windows.

doc/yaml_configuration.md

@@ -1197,27 +1197,29 @@ has the following effect:
 
 This field is convenient in setups that restrict access to GitHub, for instance closed corporate setups. In this setting, it is common for the development environment to have general access to the internet, but not for testing/building environments. To avoid the firewall, one can run a local snapshots mirror and then use a custom `snapshot-location-base` in the closed environments only.
 
-
 Since 2.5.0
 
-## Hooks
+## Customisation
 
-### GHC installation hooks (experimental)
+### GHC installation customisation (experimental)
 
-Stack's installation procedure can be fully customized by placing a shell script at
-`~/.stack/hooks/ghc-install.sh` and making it executable.
+On Unix-like operating systems and Windows, Stack's installation procedure can
+be fully customised by placing a `sh` shell script (a 'hook') in the Stack root
+directory at `hooks/ghc-install.sh`. On Unix-like operating systems, the script
+file must be made executable. The script is run by the `sh` application (which
+is provided by MSYS2 on Windows).
 
-The script **must** return an exit code of `0` and the standard output **must** be the
-absolute path to the ghc binary that was installed. Otherwise stack will ignore
-the hook and possibly fall back to its own installation procedure.
+The script **must** return an exit code of `0` and the standard output **must**
+be the absolute path to the GHC binary that was installed. Otherwise Stack will
+ignore the script and possibly fall back to its own installation procedure.
 
-Hooks are not run when `system-ghc: true`.
+The script is not run when `system-ghc: true`.
 
-When `install-ghc: false`, hooks are still run,
-which allows you to ensure that only your hook will install GHC and stack won't default
-to its own installation logic, even when the hook fails.
+When `install-ghc: false`, the script is still run, which allows you to ensure
+that only your script will install GHC and Stack won't default to its own
+installation logic, even when the script fails.
 
-An example hook is:
+An example script is:
 
 ```sh
 #!/bin/sh
@@ -1242,7 +1244,7 @@ esac
 echo "location/to/ghc/executable"
 ```
 
-The following environment variables are always passed to the hook:
+The following environment variables are always available to the script:
 
 * `HOOK_GHC_TYPE = "bindist" | "git" | "ghcjs"`
 
@@ -1260,4 +1262,4 @@ For "ghcjs", additional variables are:
 * `HOOK_GHC_VERSION = <ver>`
 * `HOOK_GHCJS_VERSION = <ver>`
 
-Since 2.8.X
+Since 2.7.X