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

* src/gtkutil.c: Related comment.

3 files changed, 17 insertions, 5 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))
 
diff --git a/src/gtkutil.c b/src/gtkutil.c
index f7983fdd5a4..1ed5833bd5c 100644
--- a/src/gtkutil.c
+++ b/src/gtkutil.c
@@ -1741,8 +1741,9 @@ xg_toggle_notify_cb (GObject *gobject, GParamSpec *arg1, gpointer user_data)
    PROMPT is a prompt to show to the user.  May not be NULL.
    DEFAULT_FILENAME is a default selection to be displayed.  May be NULL.
    If MUSTMATCH_P is non-zero, the returned file name must be an existing
-   file.  *FUNC is set to a function that can be used to retrieve the
-   selected file name from the returned widget.
+   file.  (Actually, this only has cosmetic effects, the user can
+   still enter a non-existing file.)  *FUNC is set to a function that
+   can be used to retrieve the selected file name from the returned widget.
 
    Returns the created widget.  */