[Emacs-diffs] emacs-26 603a071: Improve the documentation of M-n for entering file names

[Eli Zaretskii]

branch: emacs-26
commit 603a0716a8824731a689d3b5144b55eed9ee4db4
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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 <address@hidden> 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.
---
 doc/emacs/files.texi |  3 +++
 doc/emacs/mini.texi  | 24 +++++++++++++++++++++---
 lisp/files.el        | 30 +++++++++++++++++++++++++++---
 3 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 18f1c28..b11f588 100644
--- 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 83e7f3b..93f9142 100644
--- 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 @address@hidden 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)}
address@hidden UP @r{(minibuffer history)}
address@hidden 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''.
 
address@hidden future history for file names
address@hidden minibuffer defaults for file names
address@hidden 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
address@hidden UP @r{(minibuffer history)}
address@hidden DOWN @r{(minibuffer history)}
   The arrow keys @address@hidden and @address@hidden 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 9d46d5f..b47411f 100644
--- 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."