From 415e8593edfa582edd9d2c03748e9ae9cec5022c Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sun, 22 Apr 2018 20:39:46 +0300
Subject: [PATCH] Minor improvements of next-error docs

* lisp/simple.el (next-error-find-buffer-function)
(previous-error, next-error-select-buffer): Doc fixes.
* doc/emacs/maintaining.texi (Change Log Commands):
* doc/emacs/building.texi (Compilation Mode): Index the new
commands and variables.  Improve wording.
(Bug#20493)
---
 doc/emacs/building.texi    |  5 +++++
 doc/emacs/maintaining.texi | 11 ++++++-----
 lisp/simple.el             | 18 ++++++++++++------
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 1e2dac9534e..496c4275bc2 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -190,6 +190,9 @@ compilation buffer produce automatic source display.
 @item g
 Re-run the last command whose output is shown in the
 @file{*compilation*} buffer.
+@item M-x next-error-select-buffer
+Select a buffer to be used by next invocation of @code{next-error} and
+@code{previous-error}.
 @end table
 
 @kindex M-g M-n
@@ -212,6 +215,8 @@ 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
 through errors in the opposite direction.
 
+@vindex next-error-find-buffer-function
+@findex next-error-select-buffer
   The @code{next-error} and @code{previous-error} commands don't just
 act on the errors or matches listed in @file{*compilation*} and
 @file{*grep*} buffers; they also know how to iterate through error or
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 649ca1ec51f..df8c4479000 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1640,14 +1640,15 @@ 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{change-log-goto-source} command (by default
+@findex change-log-goto-source
+  You can use the command @code{change-log-goto-source} (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.
+@kbd{M-g M-n} and @kbd{C-x `}) 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 through the change log entries.
 
 @findex change-log-merge
   You can use the command @kbd{M-x change-log-merge} to merge other
diff --git a/lisp/simple.el b/lisp/simple.el
index 56b89b36fd6..839a4dd2c6c 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -180,8 +180,12 @@ rejected, and the function returns nil."
 (defcustom next-error-find-buffer-function #'ignore
   "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'."
+`next-error-find-buffer', and should return the buffer to be
+used by the subsequent invocation of the command `next-error'
+and `previous-error'.
+If the function returns nil, `next-error-find-buffer' will
+try to use the buffer it used previously, and failing that
+all other buffers."
   :type '(choice (const :tag "No default" ignore)
                  (const :tag "Single next-error capable buffer on selected frame"
                         next-error-buffer-on-selected-frame)
@@ -340,9 +344,9 @@ and TO-BUFFER is a target buffer."
 (defun next-error-select-buffer (buffer)
   "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."
+for the subsequent invocation of `next-error' or `previous-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
@@ -358,7 +362,9 @@ an appropriate function."
 Prefix arg N says how many error messages to move backwards (or
 forwards, if negative).
 
-This operates on the output from the \\[compile] and \\[grep] commands."
+This operates on the output from the \\[compile] and \\[grep] commands.
+
+See `next-error' for the details."
   (interactive "p")
   (next-error (- (or n 1))))
 
-- 
2.39.5