* lisp/minibuffer.el (read-file-name): Doc fix. (Bug#10798)

* src/gtkutil.c: Related comment.

2 files changed, 14 insertions, 3 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index bbbfb8dd000..5c7e8f2e8f8 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-13  Glenn Morris  <rgm@gnu.org>
+
+        * minibuffer.el (read-file-name): Doc fix.  (Bug#10798)
+
 2012-02-13  Teodor Zlatanov  <tzz@lifelogs.com>
 
         * net/gnutls.el (gnutls-trustfiles): New variable.
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 913bfeba0ca..3cdece57e70 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -2011,12 +2011,19 @@ DIR should be an absolute directory name.  It defaults to the value of
 If this command was invoked with the mouse, use a graphical file
 dialog if `use-dialog-box' is non-nil, and the window system or X
 toolkit in use provides a file dialog box, and DIR is not a
-remote file.  For graphical file dialogs, any the special values
-of MUSTMATCH; `confirm' and `confirm-after-completion' are
-treated as equivalent to nil.
+remote file.  For graphical file dialogs, any of the special values
+of MUSTMATCH `confirm' and `confirm-after-completion' are
+treated as equivalent to nil.  Some graphical file dialogs respect
+a MUSTMATCH value of t, and some do not (or it only has a cosmetic
+effect, but does not actually prevent the user from entering a
+non-existent file).
 
 See also `read-file-name-completion-ignore-case'
 and `read-file-name-function'."
+  ;; If x-gtk-use-old-file-dialog = t (xg_get_file_with_selection),
+  ;; then MUSTMATCH is enforced.  But with newer Gtk
+  ;; (xg_get_file_with_chooser), it only has a cosmetic effect.
+  ;; The user can still type a non-existent file name.
   (funcall (or read-file-name-function #'read-file-name-default)
            prompt dir default-filename mustmatch initial predicate))