* cygwinenv.xml (cygwinenv-implemented-options): Explain new

winsymliks:nativestrict option.  Strip out description of symlink types
	and refer to new pathnames-symlinks section.
	* highlights.xml (ov-hi-files): Rip out most of symlink description and
	refer to new pathnames-symlinks section instead.
	* new-features.xml (ov-new1.7.19): Add CYGWIN=winsymlinks:nativestrict.
	* pathnames.xml (pathnames-symlinks): New section describing symbolic
	link handling.

winsup/doc/ChangeLog

@@ -1,12 +1,23 @@
+2013-05-23  Corinna Vinschen  <corinna@vinschen.de>
+
+	* cygwinenv.xml (cygwinenv-implemented-options): Explain new
+	winsymliks:nativestrict option.  Strip out description of symlink types
+	and refer to new pathnames-symlinks section.
+	* highlights.xml (ov-hi-files): Rip out most of symlink description and
+	refer to new pathnames-symlinks section instead.
+	* new-features.xml (ov-new1.7.19): Add CYGWIN=winsymlinks:nativestrict.
+	* pathnames.xml (pathnames-symlinks): New section describing symbolic
+	link handling.
+
 2013-05-21  Corinna Vinschen  <corinna@vinschen.de>
 
-	* new-features.sgml (ov-new1.7.19): Add arc4random,
+	* new-features.xml (ov-new1.7.19): Add arc4random,
 	arc4random_addrandom, arc4random_buf, arc4random_stir and
 	arc4random_uniform.
 
 2013-05-21  Corinna Vinschen  <corinna@vinschen.de>
 
-	* new-features.sgml (ov-new1.7.19): Add __b64_ntop and __b64_pton.
+	* new-features.xml (ov-new1.7.19): Add __b64_ntop and __b64_pton.
 
 2013-05-13  Warren Young  <warren@etr-usa.com>
 

winsup/doc/cygwinenv.xml

@@ -82,26 +82,27 @@ time and when handles are inherited.  Defaults to set.</para>
 </listitem>
 
 <listitem>
-<para><envar>winsymlinks:{lnk,native}</envar> - if set to just
+<para><envar>winsymlinks:{lnk,native,nativestrict}</envar> - if set to just
 <literal>winsymlinks</literal> or <literal>winsymlinks:lnk</literal>,
 Cygwin creates symlinks as Windows shortcuts with a special header and
-the R/O attribute set.  If set to <literal>winsymlinks:native</literal>,
+the R/O attribute set.</para>
-Cygwin creates symlinks as native Windows symlinks as supported by NTFS
-since Windows Vista/2008.
 
-If not set, Cygwin creates symlinks as plain files with a magic number,
+<para>If set to <literal>winsymlinks:native</literal> or
-a path and the DOS SYSTEM attribute set by default, unless this is not
+<literal>winsymlinks:nativestrict</literal>, Cygwin creates symlinks as
-supported by the underlying filesystem.  For instance, on MVFS symlinks
+native Windows symlinks on filesystems and OS versions supporting them.
-are always created as Windows shortcuts, because it doesn't support the
+If the OS is known not to support native symlinks (Windows XP, Windows
-DOS SYSTEM attribute, on AFS always as native symlink because it doesn't
+Server 2003), a warning message is produced once per session.</para>
-support DOS attributes.  On NFS, symlinks are always created as native
-symlinks of the underlying filesystem.
-</para>
 
-<para>Please note that symlinks created under Cygwin 1.7 or later are
+<para>The difference between <literal>winsymlinks:native</literal> and
-not readable by older Cygwin releases because the new symlinks use UTF-16
+<literal>winsymlinks:nativestrict</literal> is this:  If the filesystem
-to encode the target filename, while the old symlinks used the current
+supports native symlinks and Cygwin fails to create a native symlink for
-ANSI or OEM charset.</para>
+some reason, it will fall back to creating Cygwin default symlinks
+with <literal>winsymlinks:native</literal>, while with
+<literal>winsymlinks:nativestrict</literal> the <literal>symlink(2)</literal>
+system call will immediately fail.</para>
+
+<para>For more information on symbolic links, see
+<xref linkend="pathnames-symlinks"></xref>.</para>
 </listitem>
 
 </itemizedlist>

winsup/doc/highlights.xml

@@ -113,30 +113,9 @@ supporting that.  Since Windows XP, the OS only supports case
 sensitivity when a specific registry value is changed.  Therefore, case
 sensitivity is not usually the default.</para>
 
-<para>Symbolic links are not present and supported on Windows up to and
+<para>Cygwin supports creating and reading symbolic links, even on Windows
-including Windows Server 2003 R2.  Native symlinks are available starting
+filesystems and OS versions which don't support them.
-with Windows Vista.  Due to their strange implementation, however,
+See <xref linkend="pathnames-symlinks"></xref> for details.</para>
-they are not useful in a POSIX emulation layer.  Cygwin recognizes
-native symlinks, but does not create them.</para>
-
-<para>Symbolic links are potentially created in two different ways.
-The file style symlinks are files containing a magic cookie followed by
-the path to which the link points.  They are marked with the System DOS
-attribute so that only files with that attribute have to be read to
-determine whether or not the file is a symbolic link.  The shortcut style
-symlinks are Windows shortcut files with a special header and the
-Readonly DOS attribute set.  The advantage of file symlinks is speed,
-the advantage of shortcut symlinks is the fact that they can be utilized
-by non-Cygwin Win32 tools as well.</para>
-
-<para>Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode
-the filename of the target file, to better support internationalization.
-Symlinks created by older 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>.  Please note that this
-new UTF-16 style of symlinks is not compatible with older Cygwin release,
-which can't read the target filename correctly.</para>
 
 <para>Hard links are fully supported on NTFS and NFS file systems.  On FAT
 and other file systems which don't support hardlinks, the call returns with

winsup/doc/new-features.xml

@@ -18,7 +18,8 @@ Add support for building a 64 bit version of Cygwin on x86_64 natively.
 
 <listitem><para>
 Add support for creating native NTFS symlinks starting with Windows Vista
-by setting the CYGWIN=winsymlinks:native option.
+by setting the CYGWIN=winsymlinks:native or CYGWIN=winsymlinks:nativestrict
+option.
 </para></listitem>
 
 <listitem><para>

winsup/doc/pathnames.xml

@@ -355,6 +355,81 @@ the cygdrive prefix, use a distinct path prefix:</para>
 
 </sect2>
 
+<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>Cygwin creates symbolic links potentially in multiple different
+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>Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode
+the filename of the target file, to better support internationalization.
+Symlinks created by older 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>).  Please note that this
+new UTF-16 style of symlinks is not compatible with older Cygwin release,
+which can't read the target filename correctly.</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> 
+</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
+<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
+AFS lacking support for DOS attributes.  This is independent from the
+<literal>winsymlinks</literal> setting.</para>
+</listitem>
+
+<listitem>
+<para>On the NFS filesystem, Cygwin always creates real NFS symlinks.</para>
+</listitem>
+
+</itemizedlist>
+
+<para>All of the above four 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
+filesystem borders by commands like <command>find -xdev</command>.</para>
+
+</sect2>
+
 <sect2 id="pathnames-win32"><title>Using native Win32 paths</title>
 
 <para>Using native Win32 paths in Cygwin, while possible, is generally