* cygwinenv.sgml: Add text to explain new UTF-16 symlinks.

* faq-api.xml: Add FAQ entry "Why do some of my old symlinks don't
	work anymore?"
	* new-features.sgml: Fix symlink text.  Add new UTF-16 symlinks.
	* overview2.sgml: Add text about new UTF-16 symlinks and potential
	problems with old symlinks.
	* pathnames.sgml: Fix typo.
	* setup2.sgml: Extend text about problems with symlinks.

winsup/doc/ChangeLog

@@ -1,4 +1,15 @@
-2009-03-25  Corinna Vinschen  <corinna@vinschen.de>
+2009-03-26  Corinna Vinschen  <corinna@vinschen.de>
+
+	* cygwinenv.sgml: Add text to explain new UTF-16 symlinks.
+	* faq-api.xml: Add FAQ entry "Why do some of my old symlinks don't
+	work anymore?"
+	* new-features.sgml: Fix symlink text.  Add new UTF-16 symlinks.
+	* overview2.sgml: Add text about new UTF-16 symlinks and potential
+	problems with old symlinks.
+	* pathnames.sgml: Fix typo.  
+	* setup2.sgml: Extend text about problems with symlinks.
+
+2009-03-26  Corinna Vinschen  <corinna@vinschen.de>
 
 	* new-features.sgml: Replace GB2312 with GBK.
 	* setup2.sgml: Ditto.

winsup/doc/cygwinenv.sgml

@@ -141,7 +141,10 @@ The current list of always uppercased variables is:</para>
 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 not set since plain
-file symlinks are faster to write and faster to read.</para>
+file symlinks are faster to write and faster to read.  The new style of
+plain file symlinks is incompatible with older Cygwin releases because
+the new symlinks use UTF-16 to encode the target filename, while the
+old symlinks used the current ANSI or OEM charset.</para>
 </listitem>
 
 </itemizedlist>

winsup/doc/faq-api.xml

@@ -177,9 +177,9 @@ 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 or use the second method to create
+explicitly enable this attribute or use the second method to create symlinks.
-symlinks.
 </para>
+
 <para>The second method is enabled if `winsymlinks' is set in the environment
 variable CYGWIN.
 Using this method, Cygwin generates symlinks by creating Windows shortcuts.
@@ -194,12 +194,31 @@ 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.
 </para>
+
 <para>Both, types of symlinks can live peacefully together since Cygwin
 treats both as symlinks regardless of the setting of `(no)winsymlinks' in
 the environment variable CYGWIN.
 </para>
 </answer></qandaentry>
 
+<qandaentry id="faq.api.symlinkstoppedworking">
+<question><para>Why do some of my old symlinks don't work anymore?</para></question>
+<answer>
+
+<para>Beginning with Cygwin 1.7, Cygwin supports multiple character sets.
+Symlinks created with Cygwin 1.7 are using the UTF-16 character set, which is
+portable across all character sets.  Old symlinks were written using your
+current Windows codepage, which is not portable across all character sets.
+If the target of the symlink doesn't resolve anymore, it's very likely that
+the symlink points to a target filename using native, non-ASCII characters,
+and you're now using another character set than way back when you created
+the symlink.</para>
+
+<para>Solution: Delete the symlink and create it again under you new Cygwin.
+The new symlink will be correctly point to the target no matter what character
+set you're using in future.</para>
+</answer></qandaentry>
+
 <qandaentry id="faq.api.executables">
 <question><para>Why do some files, which are not executables have the 'x' type.</para></question>
 <answer>

winsup/doc/new-features.sgml

@@ -75,10 +75,14 @@
 
 - New open(2) flags O_DIRECTORY, O_EXEC and O_SEARCH.
 
-- Make the original style symlinks (file with SYSTEM attribute set)
+- Make the "plain file with SYSTEM attribute set" style symlink
   default again when creating symlinks.  Only create Windows shortcut
   style symlinks if CYGWIN=winsymlinks is set in the environment.
 
+- Symlinks are now using UTF-16 encoding for the target filename for
+  better internationalization support.  Cygwin 1.7 can read all old style
+  symlinks, but the new style is not compatible with older Cygwin releases.
+
 - Handle NTFS native symlinks available since Vista/2008 as symlinks
   (but don't create Vista/2008 symlinks due to unfortunate OS restrictions).
 

winsup/doc/overview2.sgml

@@ -215,6 +215,15 @@ 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 some other file systems, the call falls back to simply copying the file,
 a strategy that works in many cases.</para>

winsup/doc/pathnames.sgml

@@ -291,12 +291,11 @@ Windows path, strips off the innermost directory component and adds
 well as the innermost directory (<filename>bin</filename>) is stripped
 off: <filename>C:\cygwin\</filename>.  Then "etc" and the filename to
 look for is attached: <filename>C:\cygwin\etc\fstab</filename>.  So the
-/etc directory must be parallel to the directory in which the cygwn1.dll
+/etc directory must be parallel to the directory in which the cygwin1.dll
 exists and <filename>/etc</filename> must not be a Cygwin symlink
 pointing to another directory.  Consequentially none of the files from
-the above list, including the directory
+the above list, including the directory <filename>/etc/fstab.d</filename>
-<filename>/etc/fstab.d</filename>is allowed to be a Cygwin symlink
+is allowed to be a Cygwin symlink either.</para>
-either.</para>
 
 <para>However, native NTFS symlinks and reparse points are transparent
 when accessing the above files so all these files as well as

winsup/doc/setup2.sgml

@@ -290,14 +290,19 @@ the underscore for maximum portablilty.</para></note>
 
 <para>And here's another problem when switching charsets on the fly.
 Symbolic links.  A symbolic link contains the filename of the target
-file the symlink points to.  When a symlink is created, the current
+file the symlink points to.  When a symlink had been created with older
-character set is used to store the target filename.  If the target
+versions of Cygwin, the current ANSI or OEM character set had been used
-filename contains non-ASCII characters and you switch to another
+to store the target filename, dependent on the old <envar>CYGWIN</envar>
-character set, the target filename of the symlink is now potentially
+environment variable setting <envar>codepage</envar>
-an invalid character sequence in the new character set.  This behaviour
+(see <xref linkend="cygwinenv-removed-options"></xref>.  If the target
-is not different from the behaviour in other Operating Systems.  So,
+filename contains non-ASCII characters and you use another
-if you suddenly can't access a symlink anymore, maybe it's because you
+character set than your default ANSI/OEM charset, the target filename of
-switched to another character set?
+the symlink is now potentially an invalid character sequence in the new
+character set.  This behaviour is not different from the behaviour in other
+Operating Systems.  So, if you suddenly can't access a symlink anymore
+which worked all these years before, maybe it's because you switched to
+another character set.  This doesn't occur with symlinks created with
+Cygwin 1.7 or later.
 </para>
 
 </sect2>