Update documentation for more next-error features

* doc/emacs/maintaining.texi (Change Log Commands): Mention
change-log-goto-source.

* doc/emacs/building.texi (Compilation Mode): Document
next-error-find-buffer-function and next-error-select-buffer.

* doc/emacs/building.texi (Grep Searching):
* doc/emacs/files.texi (Diff Mode):
* doc/emacs/search.texi (Other Repeating Search):
* doc/emacs/windows.texi (Displaying Buffers):
Prefer ‘M-g M-n’ over ‘C-x `’.

* lisp/simple.el (next-error-find-buffer-function, next-error)
(next-error-select-buffer): Elaborate docstrings.  (Bug#20493)

7 files changed, 42 insertions, 23 deletions

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index a4ff69d21b4..1e2dac9534e 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -202,11 +202,11 @@ Re-run the last command whose output is shown in the
 This command can be invoked from any buffer, not just a Compilation
 mode buffer.  The first time you invoke it after a compilation, it
 visits the locus of the first error message.  Each subsequent
-@w{@kbd{C-x `}} visits the next error, in a similar fashion.  If you
+@w{@kbd{M-g M-n}} visits the next error, in a similar fashion.  If you
 visit a specific error with @key{RET} or a mouse click in the
-@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
-advance from there.  When @w{@kbd{C-x `}} finds no more error messages
-to visit, it signals an error.  @w{@kbd{C-u C-x `}} starts again from
+@file{*compilation*} buffer, subsequent @w{@kbd{M-g M-n}} commands
+advance from there.  When @w{@kbd{M-g M-n}} finds no more error messages
+to visit, it signals an error.  @w{@kbd{C-u M-g M-n}} starts again from
 the beginning of the compilation buffer, and visits the first locus.
 
   @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates
@@ -219,10 +219,15 @@ match lists produced by other commands, such as @kbd{M-x occur}
 (@pxref{Other Repeating Search}).  If the current buffer contains
 error messages or matches, these commands will iterate through them;
 otherwise, Emacs looks for a buffer containing error messages or
-matches amongst the windows of the selected frame, then for any buffer
-that @code{next-error} or @code{previous-error} previously visited,
-and finally all other buffers.  Any buffer these commands iterate
-through that is not currently displayed in a window will be displayed.
+matches amongst the windows of the selected frame (if the variable
+@code{next-error-find-buffer-function} is customized to the value
+@code{next-error-buffer-on-selected-frame}), then for a buffer used
+previously by @code{next-error} or @code{previous-error}, and finally
+all other buffers.  Any buffer these commands iterate through that is
+not currently displayed in a window will be displayed.  You can use
+the @command{next-error-select-buffer} command to switch to
+a different buffer to be used by the subsequent invocation of
+@code{next-error}.
 
 @vindex compilation-skip-threshold
   By default, the @code{next-error} and @code{previous-error} commands
@@ -394,8 +399,8 @@ grep -nH -e foo *.el | grep bar | grep toto
 @end example
 
   The output from @command{grep} goes in the @file{*grep*} buffer.  You
-can find the corresponding lines in the original files using @w{@kbd{C-x
-`}}, @key{RET}, and so forth, just like compilation errors.
+can find the corresponding lines in the original files using @w{@kbd{M-g
+M-n}}, @key{RET}, and so forth, just like compilation errors.
 @xref{Compilation Mode}, for detailed description of commands and key
 bindings available in the @file{*grep*} buffer.
 
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 4e9e7ac3f0a..79420878e85 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1430,7 +1430,7 @@ remains correct.  To disable automatic line number correction,
 change the variable @code{diff-update-on-the-fly} to @code{nil}.
 
   Diff mode treats each hunk as an error message, similar to
-Compilation mode.  Thus, you can use commands such as @kbd{C-x `} to
+Compilation mode.  Thus, you can use commands such as @kbd{M-g M-n} to
 visit the corresponding source locations.  @xref{Compilation Mode}.
 
   In addition, Diff mode provides the following commands to navigate,
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 9421691ba76..649ca1ec51f 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1640,11 +1640,14 @@ entry is considered a page.  This facilitates editing the entries.
 @kbd{C-j} and auto-fill indent each new line like the previous line;
 this is convenient for entering the contents of an entry.
 
-You can use the @code{next-error} command (by default bound to
-@kbd{C-x `}) to move between entries in the Change Log, when Change
-Log mode is on.  You will jump to the actual site in the file that was
-changed, not just to the next Change Log entry.  You can also use
-@code{previous-error} to move back in the same list.
+You can use the @code{change-log-goto-source} command (by default
+bound to @kbd{C-c C-c}) to go to the source location of the change log
+entry near point, when Change Log mode is on.  Then subsequent
+invocations of the @code{next-error} command (by default bound to
+@kbd{M-g M-n}) will move between entries in the change log.  You will
+jump to the actual site in the file that was changed, not just to the
+next change log entry.  You can also use @code{previous-error} to move
+back in the same list.
 
 @findex change-log-merge
   You can use the command @kbd{M-x change-log-merge} to merge other
@@ -1654,7 +1657,7 @@ ordering of entries.
   Version control systems are another way to keep track of changes in
 your program and keep a change log.  In the VC log buffer, typing
 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
-Change Log entry, if one exists.  @xref{Log Buffer}.
+change log entry, if one exists.  @xref{Log Buffer}.
 
 @node Format of ChangeLog
 @subsection Format of ChangeLog
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index b93010eab44..263c4c5dcca 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1796,7 +1796,7 @@ In the @file{*Occur*} buffer, you can click on each entry, or move
 point there and type @key{RET}, to visit the corresponding position in
 the buffer that was searched.  @kbd{o} and @kbd{C-o} display the match
 in another window; @kbd{C-o} does not select it.  Alternatively, you
-can use the @kbd{C-x `} (@code{next-error}) command to visit the
+can use the @kbd{M-g M-n} (@code{next-error}) command to visit the
 occurrences one by one (@pxref{Compilation Mode}).
 
 @cindex Occur Edit mode
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 7dbd680b9b2..809363305fb 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -354,7 +354,7 @@ various help commands (@pxref{Help}), work by calling
 
   Other commands do the same as @code{display-buffer}, and
 additionally select the displaying window so that you can begin
-editing its buffer.  The command @kbd{C-x `} (@code{next-error}) is
+editing its buffer.  The command @kbd{M-g M-n} (@code{next-error}) is
 one example (@pxref{Compilation Mode}).  Such commands work by calling
 the function @code{pop-to-buffer} internally.  @xref{Switching
 Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp
diff --git a/etc/NEWS b/etc/NEWS
index 366eccae80b..ffe2f508a89 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -292,6 +292,7 @@ can now be searched via 'C-s'.
 
 ** Search and Replace
 
++++
 *** 'search-exit-option' provides new options 'move' and 'shift-move'
 to extend the search string by yanking text that ends at the new
 position after moving point in the current buffer.  'shift-move'
@@ -317,6 +318,7 @@ by default.
 
 ** grep
 
++++
 *** rgrep, lgrep and zrgrep now hide part of the command line
 that contains a list of ignored directories and files.
 Clicking on the button with ellipsis unhides it.
@@ -347,6 +349,7 @@ are evaluated lazily.
 
 ** next-error
 
++++
 *** New customizable variable 'next-error-find-buffer-function'.
 This variable defines the logic of finding a next-error capable
 buffer.  It has an option to use a single such buffer on selected
diff --git a/lisp/simple.el b/lisp/simple.el
index b51be3a8f8a..56b89b36fd6 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -178,7 +178,10 @@ rejected, and the function returns nil."
                 (funcall extra-test-inclusive))))))
 
 (defcustom next-error-find-buffer-function #'ignore
-  "Function called to find a `next-error' capable buffer."
+  "Function called to find a `next-error' capable buffer.
+This functions takes the same three arguments as the function
+`next-error-find-buffer', and returns the buffer to be used
+by the subsequent invocation of the command `next-error'."
   :type '(choice (const :tag "No default" ignore)
                  (const :tag "Single next-error capable buffer on selected frame"
                         next-error-buffer-on-selected-frame)
@@ -287,8 +290,9 @@ more generally, on any buffer in Compilation mode or with
 Compilation Minor mode enabled, or any buffer in which
 `next-error-function' is bound to an appropriate function.
 To specify use of a particular buffer for error messages, type
-\\[next-error] in that buffer when it is the only one displayed
-in the current frame.
+\\[next-error] in that buffer.  You can also use the command
+`next-error-select-buffer' to select the buffer to use for the subsequent
+invocation of `next-error'.
 
 Once \\[next-error] has chosen the buffer for error messages, it
 runs `next-error-hook' with `run-hooks', and stays with that buffer
@@ -334,7 +338,11 @@ and TO-BUFFER is a target buffer."
   (run-hooks 'next-error-hook))
 
 (defun next-error-select-buffer (buffer)
-  "Select a `next-error' capable buffer and set it as the last used."
+  "Select a `next-error' capable BUFFER and set it as the last used.
+This means that the selected buffer becomes the source of locations
+for the subsequent invocation of `next-error'.  Interactively, this command
+allows selection only among buffers where `next-error-function' is bound to
+an appropriate function."
   (interactive
    (list (get-buffer
           (read-buffer "Select next-error buffer: " nil nil