Improve the documentation of M-n for entering file names

* lisp/files.el (find-file, find-file-other-window)
(find-file-other-frame): Mention file-name-at-point-functions in
the doc string.  Reported by Florian Weimer <fw@deneb.enyo.de> in
http://lists.gnu.org/archive/html/emacs-devel/2017-11/msg00224.html.

* doc/emacs/mini.texi (Minibuffer History): Document
file-name-at-point-functions and its effect on M-n when typing
file names in the minibuffer.
* doc/emacs/files.texi (File Names):
* doc/emacs/mini.texi (Minibuffer File): Add a cross-reference to
"Minibuffer History", where special features of M-n regarding
files are described.

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 18f1c28571b796711577b2fbbebc12818cd57404..b11f588b466c88ecd8d63e915c4c9d5e3f5efdfb 100644 (file)
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -63,6 +63,9 @@ completing up to a nonexistent file name, Emacs prints
 @samp{[Confirm]} and you must type a second @key{RET} to confirm.
 @xref{Completion Exit}, for details.
 
+Minibuffer history commands offer some special features for reading
+file names, see @ref{Minibuffer History}.
+
 @cindex default directory
 @vindex default-directory
 @vindex insert-default-directory

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 83e7f3b7eb52c0d3d1136cbe39a1ca6f6df2e21b..93f914207713eda65cc8fe25bdc60f201d196b98 100644 (file)
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -89,7 +89,10 @@ the default directory.  If you now type @kbd{buffer.c} as input, that
 specifies the file @file{/u2/emacs/src/buffer.c}.  @xref{File Names},
 for information about the default directory.
 
-  You can specify the parent directory with @file{..}:
+  Alternative defaults for the file name you may want are available by
+typing @kbd{M-n}, see @ref{Minibuffer History}.
+
+  You can specify a file in the parent directory with @file{..}:
 @file{/a/b/../foo.el} is equivalent to @file{/a/foo.el}.
 Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names
 backwards (@pxref{Words}).
@@ -609,8 +612,6 @@ Move to a later item in the minibuffer history that matches
 
 @kindex M-p @r{(minibuffer history)}
 @kindex M-n @r{(minibuffer history)}
-@kindex UP @r{(minibuffer history)}
-@kindex DOWN @r{(minibuffer history)}
 @findex next-history-element
 @findex previous-history-element
   While in the minibuffer, @kbd{M-p} (@code{previous-history-element})
@@ -627,8 +628,25 @@ typed @kbd{M-p}), Emacs tries fetching from a list of default
 arguments: values that you are likely to enter.  You can think of this
 as moving through the ``future history''.
 
+@cindex future history for file names
+@cindex minibuffer defaults for file names
+@vindex file-name-at-point-functions
+  The ``future history'' for file names includes several possible
+alternatives you may find useful, such as the file name or the URL at
+point in the current buffer.  The defaults put into the ``future
+history'' in this case are controlled by the functions mentioned in
+the value of the option @code{file-name-at-point-functions}.  By
+default, its value invokes the @code{ffap} package (@pxref{FFAP}),
+which tries to guess the default file or URL from the text around
+point.  To disable this guessing, customize the option to a @code{nil}
+value, then the ``future history'' of file names will include only the
+file, if any, visited by the current buffer, and the default
+directory.
+
 @findex previous-line-or-history-element
 @findex next-line-or-history-element
+@kindex UP @r{(minibuffer history)}
+@kindex DOWN @r{(minibuffer history)}
   The arrow keys @kbd{@key{UP}} and @kbd{@key{DOWN}} work like
 @kbd{M-p} and @kbd{M-n}, but if the current history item is longer
 than a single line, they allow you to move to the previous or next

diff --git a/lisp/files.el b/lisp/files.el
index 9d46d5f85aa8463881ad3169f6c82d0ed233b053..b47411f206a51b24e8268e4264a031e1f30f8ae5 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1560,7 +1560,15 @@ Switch to a buffer visiting file FILENAME,
 creating one if none already exists.
 Interactively, the default if you just type RET is the current directory,
 but the visited file name is available through the minibuffer history:
-type M-n to pull it into the minibuffer.
+type \\[next-history-element] to pull it into the minibuffer.
+
+The first time \\[next-history-element] is used after Emacs prompts for
+the file name, the result is affected by `file-name-at-point-functions',
+which by default try to guess the file name by looking at point in the
+current buffer.  Customize the value of `file-name-at-point-functions'
+or set it to nil, if you want only the visited file name and the
+current directory to be available on first \\[next-history-element]
+request.
 
 You can visit files on remote machines by specifying something
 like /ssh:SOME_REMOTE_MACHINE:FILE for the file name.  You can
@@ -1591,7 +1599,15 @@ an existing one.  See the function `display-buffer'.
 
 Interactively, the default if you just type RET is the current directory,
 but the visited file name is available through the minibuffer history:
-type M-n to pull it into the minibuffer.
+type \\[next-history-element] to pull it into the minibuffer.
+
+The first time \\[next-history-element] is used after Emacs prompts for
+the file name, the result is affected by `file-name-at-point-functions',
+which by default try to guess the file name by looking at point in the
+current buffer.  Customize the value of `file-name-at-point-functions'
+or set it to nil, if you want only the visited file name and the
+current directory to be available on first \\[next-history-element]
+request.
 
 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
 expand wildcards (if any) and visit multiple files."
@@ -1615,7 +1631,15 @@ an existing one.  See the function `display-buffer'.
 
 Interactively, the default if you just type RET is the current directory,
 but the visited file name is available through the minibuffer history:
-type M-n to pull it into the minibuffer.
+type \\[next-history-element] to pull it into the minibuffer.
+
+The first time \\[next-history-element] is used after Emacs prompts for
+the file name, the result is affected by `file-name-at-point-functions',
+which by default try to guess the file name by looking at point in the
+current buffer.  Customize the value of `file-name-at-point-functions'
+or set it to nil, if you want only the visited file name and the
+current directory to be available on first \\[next-history-element]
+request.
 
 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
 expand wildcards (if any) and visit multiple files."