Cygwin: docs: revamp docs explaining symlinks

The descriptions of symlink handling are a bit dated, so
revamp them and add the new WSL symlink type.

Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

1 files changed, 36 insertions, 39 deletions

diff --git a/winsup/doc/pathnames.xml b/winsup/doc/pathnames.xml
index 6f9fefa24..2966bdabf 100644
--- a/winsup/doc/pathnames.xml
+++ b/winsup/doc/pathnames.xml
@@ -377,51 +377,41 @@ like this:</para>
 
 <sect2 id="pathnames-symlinks"><title>Symbolic links</title>
 
-<para>Symbolic links are not present and supported on Windows until Windows
-Vista/Server 2008, and then only on some filesystems.  Since POSIX applications
-are rightfully expecting to use symlinks and the
-<literal>symlink(2)</literal> system call, Cygwin had to find a
-workaround for this Windows flaw.</para>
+<para>Symbolic links are supported by Windows only on NTFS and have
+a lot of quirks making them (almost) unusable in a POSIX context.
+POSIX applications are rightfully expecting to use symlinks and the
+<literal>symlink(2)</literal> system call, so Cygwin has worked around
+the Windows shortcomings.</para>
 
 <para>Cygwin creates symbolic links potentially in multiple different
-ways:</para>
+ways.</para>
 
 <itemizedlist mark="bullet">
 
 <listitem>
-<para>The default symlinks are plain files containing a magic cookie
-followed by the path to which the link points.  They are marked with the
-DOS SYSTEM attribute so that only files with that attribute have to be
-read to determine whether or not the file is a symbolic link.</para>
-
-<note><para>Cygwin symbolic links are using UTF-16 to encode the filename of
-the target file, to better support internationalization.  Symlinks created by
-old Cygwin releases can be read just fine.  However, you could run into
-problems with them if you're now using another character set than the one you
-used when creating these symlinks
-(see <xref linkend="setup-locale-problems"></xref>).
+<para>The default symlinks created by Cygwin are either special reparse
+points shared with WSL on Windows 10, or plain files containing a magic
+cookie followed by the path to which the link points.  The reparse point
+is used on NTFS, the plain file on almost any other filesystem.</para>
+
+<note><para>Symlinks created by really old Cygwin releases (prior to
+Cygwin 1.7.0) are usually readable.  However, you could run into problems
+if you're now using another character set than the one you used when
+creating these symlinks (see <xref linkend="setup-locale-problems"></xref>).
 </para></note>
 </listitem>
 
 <listitem>
-<para>The shortcut style symlinks are Windows <literal>.lnk</literal>
-shortcut files with a special header and the DOS READONLY attribute set.
-This symlink type is created if the environment variable
-<literal>CYGWIN</literal> (see <xref linkend="using-cygwinenv"></xref>)
-is set to contain the string <literal>winsymlinks</literal> or
-<literal>winsymlinks:lnk</literal>.  On the MVFS filesystem, which does
-not support the DOS SYSTEM attribute, this is the one and only supported
-symlink type, independently from the <literal>winsymlinks</literal>
-setting.</para> 
+<para>On filesystems mounted via Microsoft's NFS client, Cygwin always
+creates real NFS symlinks.</para>
 </listitem>
 
 <listitem>
-<para>Native Windows symlinks are only created on Windows Vista/2008 and later,
-and only on filesystems supporting reparse points.  Due to to their weird
-restrictions and behaviour, they are only created if the user
-explicitely requests creating them.  This is done by setting the
-environment variable <literal>CYGWIN</literal> to contain the string
-<literal>winsymlinks:native</literal> or
+<para>Native Windows symlinks are only created on filesystems supporting
+reparse points.  Due to their weird restrictions and behaviour, they are
+only created if the user explicitely requests creating them.  This is done
+by setting the environment variable <literal>CYGWIN</literal> to contain
+the string <literal>winsymlinks:native</literal> or
 <literal>winsymlinks:nativestrict</literal>.  For the difference between
 these two settings, see <xref linkend="using-cygwinenv"></xref>.
 On AFS, native symlinks are the only supported type of symlink due to
@@ -433,21 +423,28 @@ symlinks that lie in the target path.</para>
 </listitem>
 
 <listitem>
-<para>On the NFS filesystem, Cygwin always creates real NFS symlinks.</para>
+<para>Shortcut style symlinks are Windows <literal>.lnk</literal>
+shortcut files with a special header and the DOS READONLY attribute set.
+This symlink type is created if the environment variable
+<literal>CYGWIN</literal> (see <xref linkend="using-cygwinenv"></xref>)
+is set to contain the string <literal>winsymlinks</literal> or
+<literal>winsymlinks:lnk</literal>.  On the MVFS filesystem, which does
+not support the DOS SYSTEM attribute, this is the one and only supported
+symlink type, independently from the <literal>winsymlinks</literal>
+setting.</para>
 </listitem>
 
 </itemizedlist>
 
-<para>All of the above four symlink types are recognized and used as symlinks
+<para>All of the above symlink types are recognized and used as symlinks
 under all circumstances.  However, if the default plain file symlink type
 is lacking its DOS SYSTEM bit, or if the shortcut file is lacking the DOS
 READONLY attribute, they are not recognized as symlink.</para>
 
-<para>Apart from these four types, there's also a fifth type, which is
-recognized as symlink but never generated by Cygwin, directory
-junctions.  This is an older reparse point type, supported by Windows
-since Windows 2000.  Filesystem junctions on the other hand are not
-handled as symlinks, since otherwise they would not be recognized as
+<para>Apart from these types, there's also a Windows native type,
+so called directory junctions.  They are recognized as symlink but
+never generated by Cygwin.  Filesystem junctions on the other hand
+are not handled as symlinks, otherwise they would not be recognized as
 filesystem borders by commands like <command>find -xdev</command>.</para>
 
 </sect2>