* cygwinenv.sgml: Add text for `winsymlinks' option.

        * how-api.texinfo: Add text to explain new symlinks==shortcuts
        and the CYGWIN setting `(no)winsymlinks'.
        * how-using.texinfo: Add text that Cygwin now treats shortcuts
        as symlinks.

4 files changed, 48 insertions, 9 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index fa69921b0..05beb12a6 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,11 @@
+Fri Mar  2 12:42:00 2001  Corinna Vinschen <corinna@vinschen.de>
+
+	* cygwinenv.sgml: Add text for `winsymlinks' option.
+	* how-api.texinfo: Add text to explain new symlinks==shortcuts
+	and the CYGWIN setting `(no)winsymlinks'.
+	* how-using.texinfo: Add text that Cygwin now treats shortcuts
+	as symlinks.
+
 2001-02-07  Eric M. Monsler  <emonsler@beamreachnetworks.com>
 
 	* setup2.sgml: Add docs about domain accounts.
diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml
index 41c94019e..f4ebad01c 100644
--- a/winsup/doc/cygwinenv.sgml
+++ b/winsup/doc/cygwinenv.sgml
@@ -93,5 +93,11 @@ expected instead of ^Z, and is settable via stty.
 This option must be specified before starting a Cygwin shell 
 and it cannot be changed in the shell.</para>
 </listitem>
+<listitem>
+<para><FirstTerm>(no)winsymlinks</FirstTerm> - if set, Cygwin creates
+symlinks as Windows shortcuts with a special header and the R/O attribute
+set. If not set, Cygwin creates symlinks as plain files with a magic number,
+a path and the system attribute set. Defaults to set.</para>
+</listitem>
 </itemizedlist>
 </sect1>
diff --git a/winsup/doc/how-api.texinfo b/winsup/doc/how-api.texinfo
index 8fc28b0c3..1d9135add 100644
--- a/winsup/doc/how-api.texinfo
+++ b/winsup/doc/how-api.texinfo
@@ -141,15 +141,36 @@ Beware: globbing uses @code{malloc}.  If your application defines
 
 @subsection How do symbolic links work?
 
-Cygwin generates link files with a magic header.  When
-you open a file or directory that is a link to somewhere else, it
-opens the file or directory listed in the magic header.  Because we
-don't want to have to open every referenced file to check symlink
-status, Cygwin marks symlinks with the system attribute.  Files
-without the system attribute are not checked.  Because remote samba
-filesystems do not enable the system attribute by default, symlinks do
-not work on network drives unless you explicitly enable this
-attribute.
+Cygwin knows of two ways to create symlinks.
+
+The old method is the only valid one up to but not including version 1.3.0.
+If it's enabled (from 1.3.0 on by setting `nowinsymlinks' in the environment
+variable CYGWIN) Cygwin generates link files with a magic header.  When you
+open a file or directory that is a link to somewhere else, it opens the file
+or directory listed in the magic header.  Because we don't want to have to
+open every referenced file to check symlink status, Cygwin marks symlinks
+with the system attribute.  Files without the system attribute are not
+checked.  Because remote samba filesystems do not enable the system
+attribute by default, symlinks do not work on network drives unless you
+explicitly enable this attribute.
+
+The new method which is introduced with Cygwin version 1.3.0 is enabled
+by default or if `winsymlinks' is set in the environment variable CYGWIN.
+Using this method, Cygwin generates symlinks by creating Windows shortcuts.
+Cygwin created shortcuts have a special header (which is in that way never
+created by Explorer) and the R/O attribute set.  A DOS path is stored in
+the shortcut as usual and the description entry is used to store the POSIX
+path.  While the POSIX path is stored as is, the DOS path has perhaps to be
+rearranged to result in a valid path.  This may result in a divergence
+between the DOS and the POSIX path when symlinks are moved crossing mount
+points.  When a user changes the shortcut, this will be detected by Cygwin
+and it will only use the DOS path then.  While Cygwin shortcuts are shown
+without the ".lnk" suffix in `ls' output, non-Cygwin shortcuts are shown
+with the suffix.  However, both are treated as symlinks.
+
+Both, the old and the new symlinks can live peacefully together since Cygwin
+treats both as symlinks regardless of the setting of `(no)winsymlinks' in
+the environment variable CYGWIN.
 
 @subsection Why do some files, which are not executables have the 'x' type.
 
diff --git a/winsup/doc/how-using.texinfo b/winsup/doc/how-using.texinfo
index d1077b837..0c1745d9e 100644
--- a/winsup/doc/how-using.texinfo
+++ b/winsup/doc/how-using.texinfo
@@ -98,6 +98,8 @@ or
 
 @subsection Why can't I cd into a shortcut to a directory?
 
+This is only valid up to but not including version 1.3.0:
+
 Cygwin does not follow MS Windows Explorer Shortcuts (*.lnk files).  It
 sees a shortcut as a regular file and this you cannot "cd" into it.
 
@@ -106,6 +108,8 @@ with shortcuts.  The major problem with this is that .LNK files would
 then be used to symlink Cygwin paths that may or may not be valid
 under native Win32 non-Cygwin applications such as Explorer.
 
+Since version 1.3.0, Cygwin treats shortcuts as symlinks.
+
 @subsection I'm having basic problems with find.  Why?
 
 Make sure you are using the find that came with Cygwin and that you