From 7df14908a304c99289eaa314987f65565f94f4df Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 7 Dec 2013 18:51:33 +0200
Subject: [PATCH] Updated documentation.

---
 doc/emacs/mule.texi       | 15 +++++++++++++++
 doc/lispref/nonascii.texi | 10 ++++++++++
 etc/NEWS                  |  8 ++++++++
 src/fileio.c              | 10 ++++++++--
 4 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index ebddc46be94..6efbc2b7190 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1130,6 +1130,21 @@ In the default language environment, non-@acronym{ASCII} characters in
 file names are not encoded specially; they appear in the file system
 using the internal Emacs representation.
 
+@cindex file-name encoding, MS-Windows
+@vindex w32-unicode-filenames
+  When Emacs runs on MS-Windows versions that are descendants of the
+NT family (Windows 2000, XP, Vista, Windows 7, and Windows 8), the
+value of @code{file-name-coding-system} is largely ignored, as Emacs
+by default uses APIs that allow to pass Unicode file names directly.
+By contrast, on Windows 9X, file names are encoded using
+@code{file-name-coding-system}, which should be set to the codepage
+(@pxref{Coding Systems, codepage}) pertinent for the current system
+locale.  The value of the variable @code{w32-unicode-filenames}
+controls whether Emacs uses the Unicode APIs when it calls OS
+functions that accept file names.  This variable is set by the startup
+code to @code{nil} on Windows 9X, and to @code{t} on newer versions of
+MS-Windows.
+
   @strong{Warning:} if you change @code{file-name-coding-system} (or the
 language environment) in the middle of an Emacs session, problems can
 result if you have already visited files whose names were encoded using
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 96adb629f37..4132c1f8de0 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -1108,6 +1108,16 @@ visited file name, saving may use the wrong file name, or it may get
 an error.  If such a problem happens, use @kbd{C-x C-w} to specify a
 new file name for that buffer.
 
+@cindex file-name encoding, MS-Windows
+  On Windows 2000 and later, Emacs by default uses Unicode APIs to
+pass file names to the OS, so the value of
+@code{file-name-coding-system} is largely ignored.  Lisp applications
+that need to encode or decode file names on the Lisp level should use
+@code{utf-8} coding-system when @code{system-type} is
+@code{windows-nt}; the conversion of UTF-8 encoded file names to the
+encoding appropriate for communicating with the OS is performed
+internally by Emacs.
+
 @node Lisp and Coding Systems
 @subsection Coding Systems in Lisp
 
diff --git a/etc/NEWS b/etc/NEWS
index 132c461b258..5f6cf12fb24 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -930,6 +930,14 @@ files are in share/emacs/VERSION/etc.  (Emacs knows about all these
 directories and will find the files in there automatically; there's no
 need to set any variables due to this change.)
 
++++
+** Emacs on Windows 2000 and later can now access files and directories
+whose names cannot be encoded in the current system codepage.
+
+The new variable `w32-unicode-filenames' controls this feature: if it
+is t, Emacs uses Unicode APIs to pass file names to system calls,
+which lifts the limitation of file names to the current locale.
+
 +++
 ** The "generate a backtrace on fatal error" feature now works on MS Windows.
 The backtrace is written to the 'emacs_backtrace.txt' file in the
diff --git a/src/fileio.c b/src/fileio.c
index e5347ce765a..a98ed6b9fa5 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -5849,7 +5849,10 @@ syms_of_fileio (void)
 
   DEFVAR_LISP ("file-name-coding-system", Vfile_name_coding_system,
 	       doc: /* Coding system for encoding file names.
-If it is nil, `default-file-name-coding-system' (which see) is used.  */);
+If it is nil, `default-file-name-coding-system' (which see) is used.
+
+On MS-Windows, the value of this variable is largely ignored if
+\`w32-unicode-filenames' (which see) is non-nil.  */);
   Vfile_name_coding_system = Qnil;
 
   DEFVAR_LISP ("default-file-name-coding-system",
@@ -5860,7 +5863,10 @@ This variable is used only when `file-name-coding-system' is nil.
 This variable is set/changed by the command `set-language-environment'.
 User should not set this variable manually,
 instead use `file-name-coding-system' to get a constant encoding
-of file names regardless of the current language environment.  */);
+of file names regardless of the current language environment.
+
+On MS-Windows, the value of this variable is largely ignored if
+\`w32-unicode-filenames' (which see) is non-nil.  */);
   Vdefault_file_name_coding_system = Qnil;
 
   DEFSYM (Qformat_decode, "format-decode");
-- 
2.39.2