[newlib-cygwin] Cygwin: doc: update case-sensitive dirs description

[newlib-cygwin] Cygwin: doc: update case-sensitive dirs description

[Corinna Vinschen]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=c18f7d72dc5554b1e12f035fcf7d66be25ee3881

commit c18f7d72dc5554b1e12f035fcf7d66be25ee3881
Author: Corinna Vinschen <corinna@vinschen.de>
Date:   Mon Mar 4 14:03:32 2019 +0100

    Cygwin: doc: update case-sensitive dirs description
    
    Since we have to disable automatic case-sensitive mkdir again,
    change documentation accordingly.
    
    Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

Diff:
---
 winsup/doc/specialnames.xml | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/winsup/doc/specialnames.xml b/winsup/doc/specialnames.xml
index f278360..1120f86 100644
--- a/winsup/doc/specialnames.xml
+++ b/winsup/doc/specialnames.xml
@@ -230,13 +230,26 @@ feature available via <literal>Programs and Features</literal> ->
 turning <literal>WSL</literal> on and performing the compulsory reboot,
 case-sensitive directories are activated.</para>
 
-<para>With <literal>WSL</literal> activated and starting with Cygwin 3.0,
-Cygwin's <command>mkdir</command> system call will automatically create all
+<para>Of course, there's a drawback.  While these case-sensitive directories
+work like charm on the local machine, there are massive interoperability
+problems when trying to access these directories from remote machines at
+the time of writing this.  We opened a bug report for that at
+<ulink url="https://github.com/Microsoft/WSL/issues/3885">Microsoft's WSL issue tracker</ulink>,
+if you're interested in the details.</para>
+
+<note><para>If you want case-sensitivity and need interoperability with remote
+machines, better stick to switching the kernel to case-sensitivity as
+outlined in <xref linkend="pathnames-casesensitive"></xref></para></note>
+
+<para>With <literal>WSL</literal> activated and starting with Cygwin 3.0.0,
+Cygwin's <command>mkdir</command> system call automatically created all
 directories below the Cygwin installation directory as case-sensitive.
-Directories created outside the Cygwin installation tree will be left
-alone.  However, you can use Cygwin's new <xref linkend="chattr"></xref> tool
-with the <literal>-C</literal> option to control case-sensitivity of
-directories on NTFS filesystems.</para>
+With Cygwin 3.0.2, this feature had been disabled again for hopefully
+obvious reasons.</para>
+
+<para>However, you can still use Cygwin's new
+<xref linkend="chattr"></xref> tool with the <literal>-C</literal> option
+to control case-sensitivity of directories on NTFS filesystems.</para>
 
 <para>Please keep in mind that switching <emphasis>off</emphasis>
 case-sensitivity on a directory has a condition attached to it:  If