Commit 47d8e799 authored by Juri Linkov's avatar Juri Linkov

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)
parent 94e794c8
......@@ -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.
......
......@@ -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,
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment