* 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.

1 files changed, 21 insertions, 2 deletions

diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml
index 100d6bf91..2f7a9f15a 100644
--- a/winsup/doc/faq-api.xml
+++ b/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
-symlinks.
+explicitly enable this attribute or use the second method to create 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>