Re #6647 Improve online docs on space in path to GHC executable

Author: mpilgrem

doc/README.md

@@ -150,6 +150,19 @@ Stack can be installed directly or by using the GHCup tool.
                 Systems with antivirus software may need to add Stack to the
                 list of 'trusted' applications.
 
+            ??? warning "I have a Windows username with a space in it"
+
+                GHC 9.4.1 and later have a bug which means they do not work if
+                the path to the `ghc` executable has a space character in it.
+                The default location for Stack's 'programs' directory will have
+                a space in the path if the value of the `USERNAME` environment
+                variable includes a space.
+
+                A solution is to configure Stack to use a different location for
+                its 'programs' directory. For further information, see the
+                [`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
+                non-project specific configuration option documentation.
+
         === "Windows on Arm"
 
             The GHC project does not yet provide a version of GHC that runs on

doc/configure/yaml/non-project.md

@@ -932,18 +932,45 @@ Stack's defaults differ between Unix-like operating systems and Windows.
 
     The MSYS2 tool is also installed in the Stack 'programs' directory.
 
-    !!! warning
+    !!! warning "Space character in the path to Stack's 'programs' directory"
 
         If there is a space character in the path to Stack's 'programs'
-        directory this may cause problems with building packages that make use
-        of the GNU project's `autoconf` package and `configure` shell script
-        files. That may be the case particularly if there is no corresponding
-        short name ('8 dot 3' name) for the directory in the path with the space
-        (which may be the case if '8 dot 3' names have been stripped or their
-        creation not enabled by default). If there are problems building, it
-        will be necessary to specify an alternative path that does not contain
-        space characters. Examples of packages on Hackage that make use of
-        `configure` are `network` and `process`.
+        directory this may cause problems:
+
+        *   with building packages that make use of the GNU project's `autoconf`
+            package and `configure` shell script files. That may be the case
+            particularly if there is no corresponding short name ('8 dot 3'
+            name) for the directory in the path with the space (which may be the
+            case if '8 dot 3' names have been stripped or their creation not
+            enabled by default). Examples of packages on Hackage that make use
+            of `configure` are `network` and `process`; and
+
+        *   building with GHC 9.4.1 and later. These versions of GHC have a bug
+            which means they do not work if the path to the `ghc` executable has
+            a space in it.
+
+        The default location for Stack's 'programs' directory will have a space
+        in the path if the value of the `USERNAME` environment variable includes
+        a space.
+
+        If there are problems building, it will be necessary to specify an
+        alternative path that does not contain spaces. For example, the
+        `programs` directory in the [Stack root](../../topics/stack_root.md)
+        (assuming that path is space-free). For example, if the relevant
+        directory is `C:\sr\programs`, add:
+        ~~~yaml
+        local-program-paths: C:\sr\programs
+        ~~~
+
+        to Stack's [global configuration](https://docs.haskellstack.org/en/stable/configure/yaml/#location-of-global-configuration)
+        file (`config.yaml`).
+
+        If that global configuration file does not yet exist, command:
+        ~~~text
+        stack --no-install-ghc setup
+        ~~~
+
+        to cause Stack to create it (without also installing GHC).
 
 === "Windows (Command Prompt)"
 

doc/faq.md

@@ -581,6 +581,11 @@
     Stack. See issue [#399](https://github.com/commercialhaskell/stack/issues/399)
     for the ongoing effort and information on workarounds.
 
+??? question "I have a Windows username with a space in it and problems building"
+
+    See the [`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
+    non-project specific configuration option documentation for advice.
+
 ??? question "How to get a working executable on Windows?"
 
     When executing a binary after building with `stack build` (e.g. for target
@@ -604,14 +609,3 @@
     https://msdn.microsoft.com/de-de/library/7d83bc18.aspx).
 
     See issue [#425](https://github.com/commercialhaskell/stack/issues/425).
-
-    Another issue that may arise with building on Windows is as follows. The default
-    location of Stack's programs folder is `%LOCALAPPDATA\Programs\stack`. If there
-    is a space character in the `%LOCALAPPDATA%` path this may, in some
-    circumstances, cause problems with building packages that make use of the GNU
-    project's `autoconf` package and `configure` shell script files. It may be
-    necessary to override the default location of Stack's programs folder. See the
-    [local-programs-path](configure/yaml/non-project.md#local-programs-path) option
-    for more information.
-
-    See issue [#4726](https://github.com/commercialhaskell/stack/issues/4726).

doc/install_and_upgrade.md

@@ -646,7 +646,20 @@ Stack can be installed directly or by using the GHCup tool.
                 installer. If so, click on **More info**, and then click on the
                 **Run anyway** button that appears.
 
-            !!! warning "Long user PATH environment variable"
+            ??? warning "I have a Windows username with a space in it"
+
+                GHC 9.4.1 and later have a bug which means they do not work if
+                the path to the `ghc` executable has a space character in it.
+                The default location for Stack's 'programs' directory will have
+                a space in the path if the value of the `USERNAME` environment
+                variable includes a space.
+
+                A solution is to configure Stack to use a different location for
+                its 'programs' directory. For further information, see the
+                [`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
+                non-project specific configuration option documentation.
+
+            ??? warning "Stack 2.9.1, 2.9.3 and 2.11.1: Long user PATH environment variable"
 
                 The Windows installer for Stack 2.9.1, 2.9.3 and 2.11.1 (only)
                 will replace the user `PATH` environment variable (rather than