users-guide: Move discussion MAX_PATH out of release notes

This discussion will be useful for users; move it into the users-guide proper.
Also fixes a few typos noted by @Phyx.

Test Plan: Read it

Reviewers: Phyx

Reviewed By: Phyx

Subscribers: dfeuer, Phyx, rwbarton, thomie, carter

Differential Revision: https://phabricator.haskell.org/D4420

2 files changed, 55 insertions, 43 deletions

diff --git a/docs/users_guide/8.6.1-notes.rst b/docs/users_guide/8.6.1-notes.rst
index bda1ddcbeb..25b93b8b8c 100644
--- a/docs/users_guide/8.6.1-notes.rst
+++ b/docs/users_guide/8.6.1-notes.rst
@@ -13,6 +13,13 @@ Highlights
 
 The highlights, since the 8.4.1 release, are:
 
+- Programs are no longer constrained by the Windows ``MAX_PATH`` file path
+  length limit. The file path limit is now approximately 32,767 characters. Note
+  that GHC itself is still somewhat limited due to GCC not supporting file
+  namespaced paths. Paths that are passed directly to the compiler, linker or
+  other GNU tools are currently still constrained. See :ref:`windows-file-paths`
+  for details.
+
 - Many, many bug fixes.
 
 
@@ -118,7 +125,8 @@ Runtime system
 - The GHC runtime linker now uses ``LIBRARY_PATH`` and the runtime loader now also
   searches ``LD_LIBRARY_PATH``.
 
-- The GHC runtime on Windows is no longer constrained by ``MAX_PATH``.
+- The GHC runtime on Windows is no longer constrained by the ``MAX_PATH`` file path
+  length limitation. See :ref:`windows-file-paths`.
 
 - The runtime now allows use of the :rts-flag:`-hT` profiling variety on
   programs built with :ghc-flag:`-prof`.
@@ -150,48 +158,6 @@ Template Haskell
 Build system
 ~~~~~~~~~~~~
 
-Windows Paths
-~~~~~~~~~~~~~
-
-Windows paths are not all the same. The different kinds of paths each have
-different meanings. The ``MAX_PATH`` limitation is not a limitation of the Operating
-System nor the File System. It is a limitation of the default namespace enforced
-by the Win32 API for backwards compatibility.
-
-The NT Kernel however allows you ways to opt out of this path preprocessing by
-the Win32 APIs. This is done by explicitly using the desired namespace in the
-PATH.
-
-The namespaces are:
-
- - file namespace: ``\\?\``
- - device namespace: ``\\.\``
- - nt namespace: ``\``
-
-Each of these turn off Path processing completely by the Win32 API and the paths
-are passed untouched to the filesystem.
-
-Paths with a drive letter are `legacy` paths. The drive letters are actually
-meaningless to the kernel. Just like Unix operating systems, drive letters are
-just a mount point. You can view your mount points by using the `mountvol`
-command.
-
-The Haskell I/O manager will now automatically promote paths in the legacy
-format to Win32 file namespace. By default the I/O manager will do two things to
-your paths:
-
-  - replace ``/`` with ``\\``
-  - expand relative paths to absolute paths
-
-If you want to opt out of all preprocessing just expliticly use namespaces in
-your paths. Due to this change, if you need to open raw devices (e.g. COM ports)
-you need to use the device namespace explicitly. (e.g. `\\.\COM1`). GHC and
-Haskell programs in general no longer support opening devices in the `legacy`
-format.
-
-See https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx for
-more details.
-
 
 Included libraries
 ------------------
diff --git a/docs/users_guide/win32-dlls.rst b/docs/users_guide/win32-dlls.rst
index 26c3ffe3b0..4ecdd10f72 100644
--- a/docs/users_guide/win32-dlls.rst
+++ b/docs/users_guide/win32-dlls.rst
@@ -97,6 +97,52 @@ Windows.
    ``IOExts.hSetBinaryMode``. The ``IOExts`` module is part of the
    ``lang`` package.
 
+.. _windows-file-paths:
+
+File paths under Windows
+------------------------
+
+Windows paths are not all the same. The different kinds of paths each have
+different meanings. The ``MAX_PATH`` limitation is not a limitation of the operating
+system nor the file system. It is a limitation of the default namespace enforced
+by the Win32 API for backwards compatibility.
+
+The NT kernel however allows you ways to opt out of this path preprocessing by
+the Win32 APIs. This is done by explicitly using the desired namespace in the
+path.
+
+The namespaces are:
+
+ - file namespace: ``\\?\``
+ - device namespace: ``\\.\``
+ - NT namespace: ``\``
+
+Each of these turn off path processing completely by the Win32 API and the paths
+are passed untouched to the filesystem.
+
+Paths with a drive letter are *legacy* paths. The drive letters are actually
+meaningless to the kernel. Just like Unix operating systems, drive letters are
+just a mount point. You can view your mount points by using the :command:`mountvol`
+command.
+
+Since GHC 8.6.1, the Haskell I/O manager automatically promotes paths in the legacy
+format to Win32 file namespace. By default the I/O manager will do two things to
+your paths:
+
+  - replace ``\`` with ``\\``
+  - expand relative paths to absolute paths
+
+If you want to opt out of all preprocessing just expliticly use namespaces in
+your paths. Due to this change, if you need to open raw devices (e.g. COM ports)
+you need to use the device namespace explicitly. (e.g. ``\\.\COM1``). GHC and
+Haskell programs in general no longer support opening devices in the legacy
+format.
+
+See the
+`Windows documentation <https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx>`_
+for more details.
+
+
 .. _ghci-cygwin:
 
 Using GHC (and other GHC-compiled executables) with Cygwin