From 47d8e79960fe3ba98e360b201a6893812212880d Mon Sep 17 00:00:00 2001 From: Juri Linkov Date: Sat, 21 Apr 2018 22:52:47 +0300 Subject: [PATCH] Update documentation for more next-error features MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * 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) --- doc/emacs/building.texi | 25 +++++++++++++++---------- doc/emacs/files.texi | 2 +- doc/emacs/maintaining.texi | 15 +++++++++------ doc/emacs/search.texi | 2 +- doc/emacs/windows.texi | 2 +- etc/NEWS | 3 +++ lisp/simple.el | 16 ++++++++++++---- 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 -- 2.39.5