Rework docstring (wording by Eli Zaretskii and Kai Grossjohann).

diff --git a/lisp/dos-fns.el b/lisp/dos-fns.el
index 65b6c0063c07148ab311f12247bea5918880dfce..1253b7b5811867fecf9b310b97db508b7ae3eb50 100644 (file)
--- a/lisp/dos-fns.el
+++ b/lisp/dos-fns.el
@@ -31,9 +31,13 @@
 ;; This overrides a trivial definition in files.el.
 (defun convert-standard-filename (filename)
   "Convert a standard file's name to something suitable for the current OS.
-This function's standard definition is trivial; it just returns the argument.
-However, on some systems, the function is redefined
-with a definition that really does change some file names."
+This means to guarantee valid names and perhaps to canonicalize
+certain patterns.
+
+On Windows and DOS, replace invalid characters.  On DOS, make
+sure to obey the 8.3 limitations.  On Windows, turn Cygwin names
+into native names, and also turn slashes into backslashes if the
+shell requires it (see `w32-shell-dos-semantics')."
   (if (or (not (stringp filename))
          ;; This catches the case where FILENAME is "x:" or "x:/" or
          ;; "/", thus preventing infinite recursion.

diff --git a/lisp/files.el b/lisp/files.el
index 47f4c070cba4594d7f817215d752382c7f9e670f..81e014d228333af9803777b199cddbcf771bbde5 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -481,10 +481,15 @@ Runs the usual ange-ftp hook, but only for completion operations."
 
 (defun convert-standard-filename (filename)
   "Convert a standard file's name to something suitable for the current OS.
-This function's standard definition is trivial; it just returns the argument.
-However, on some systems, the function is redefined with a definition
-that really does change some file names to canonicalize certain
-patterns and to guarantee valid names."
+This means to guarantee valid names and perhaps to canonicalize
+certain patterns.
+
+This function's standard definition is trivial; it just returns
+the argument.  However, on Windows and DOS, replace invalid
+characters.  On DOS, make sure to obey the 8.3 limitations.  On
+Windows, turn Cygwin names into native names, and also turn
+slashes into backslashes if the shell requires it (see
+`w32-shell-dos-semantics')."
   filename)
 
 (defun read-directory-name (prompt &optional dir default-dirname mustmatch initial)

diff --git a/lisp/w32-fns.el b/lisp/w32-fns.el
index 4a485414d7a4785f57ebd52964fe40fe3edeb484..86703a3b9b512f454e22818e46a40ee9767db80c 100644 (file)
--- a/lisp/w32-fns.el
+++ b/lisp/w32-fns.el
@@ -230,9 +230,13 @@ You should set this to t when using a non-system shell.\n\n"))))
 
 (defun convert-standard-filename (filename)
   "Convert a standard file's name to something suitable for the current OS.
-This function's standard definition is trivial; it just returns the argument.
-However, on some systems, the function is redefined
-with a definition that really does change some file names."
+This means to guarantee valid names and perhaps to canonicalize
+certain patterns.
+
+On Windows and DOS, replace invalid characters.  On DOS, make
+sure to obey the 8.3 limitations.  On Windows, turn Cygwin names
+into native names, and also turn slashes into backslashes if the
+shell requires it (see `w32-shell-dos-semantics')."
   (let ((name
          (save-match-data
            (if (string-match "\\`/cygdrive/\\([a-zA-Z]\\)/" filename)