procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of 'M-X' and related features

Browse source 
* doc/emacs/m-x.texi (M-x): Index 'M-X'.
* doc/lispref/commands.texi (Interactive Call, Command Modes):
Mention 'M-X' and 'execute-extended-command-for-buffer'.

* etc/NEWS: Clarify that the '(declare (completion ...' and
'(declare (modes ...' forms have no effect by default.  Likewise
for '(interactive "..." MODE)' specs.  (Bug#52839)
This commit is contained in:
Eli Zaretskii 2021-12-29 16:39:20 +02:00
parent 06dcd2be5d
commit f11779f01b
3 changed files with 40 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/emacs/m-x.texi
View file

@ -59,6 +59,7 @@ the option @code{read-extended-command-predicate} to exclude those
irrelevant commands from completion results.
@kindex M-S-x
@kindex M-X
Conversely, Emacs can exclude all commands except those that are
particularly relevant to the current buffer. The @kbd{M-S-x} (that's
``meta shift x'') command works just like @kbd{M-x}, but instead of

28
doc/lispref/commands.texi
View file

@ -630,17 +630,26 @@ any modes that are derived from @code{dired-mode}). Any number of
modes can be added to the @code{interactive} form.
@vindex read-extended-command-predicate
Specifying modes may affect completion in @kbd{M-x}, depending on the
Specifying modes affects command completion in @kbd{M-S-x}
(@code{execute-extended-command-for-buffer}, @pxref{Interactive
Call}). It may also affect completion in @kbd{M-x}, depending on the
value of @code{read-extended-command-predicate}.
For instance, when using the
@code{command-completion-default-include-p} predicate, @kbd{M-x} won't
list commands that have been marked as being applicable to a specific
mode (unless you are in a buffer that uses that mode, of course).
This goes for both major and minor modes.
@code{command-completion-default-include-p} predicate as the value of
@code{read-extended-command-predicate}, @kbd{M-x} won't list commands
that have been marked as being applicable to a specific mode (unless
you are in a buffer that uses that mode, of course). This goes for
both major and minor modes. (By contrast, @kbd{M-S-x} always omits
inapplicable commands from the completion candidates.)
Marking commands this way will also make @kbd{C-h m} list these
commands (if they aren't bound to any keys).
By default, @code{read-extended-command-predicate} is @code{nil}, and
completion in @kbd{M-x} lists all the commands that match what the
user has typed, whether those commands are or aren't marked as
applicable to the current buffer's mode.
Marking commands to be applicable to a mode will also make @kbd{C-h m}
list these commands (if they aren't bound to any keys).
If using this extended @code{interactive} form isn't convenient
(because the code is supposed to work in older versions of Emacs that
@ -857,13 +866,16 @@ non-@code{nil} if the command is to be included when completing in
that buffer.
@end deffn
@kindex @kbd{M-X}
@kindex @kbd{M-S-x}
@deffn Command execute-extended-command-for-buffer prefix-argument
This is like @code{execute-extended-command}, but limits the commands
offered for completion to those commands that are of particular
relevance to the current major mode (and enabled minor modes). This
includes commands that are tagged with the modes (@pxref{Using
Interactive}), and also commands that are bound to locally active
keymaps.
keymaps. This command is the normal definition of @kbd{M-S-x}
(that's ``meta shift x'').
@end deffn
@node Distinguish Interactive

25
etc/NEWS
View file

@ -3730,15 +3730,28 @@ commands as being applicable for modes derived from 'dired-mode',
or if the mode is a minor mode, when the current buffer has that
minor mode activated. Note that using this form will create byte code
that is not compatible with byte code in previous Emacs versions.
Also note that by default these annotations have no effect, unless the
new option 'read-extended-command-predicate' option is customized to call
'command-completion-default-include-p' or a similar function.
+++
** New forms to declare how completion should happen has been added.
** New 'declare' forms to control completion of commands in 'M-x'.
'(declare (completion PREDICATE))' can be used as a general predicate
to say whether the command should be present when completing with
'M-x TAB'. '(declare (modes MODE...))' can be used as a short-hand
way of saying that the command should be present when completing from
buffers in major modes derived from MODE..., or, if it's a minor mode,
when that minor mode is enabled in the current buffer.
to say whether the command should be considered a completion candidate
when completing with 'M-x TAB'.
'(declare (modes MODE...))' can be used as a short-hand way of saying
that the command should be considered a completion candidate when
completing on commands from buffers in major modes derived from
MODE..., or, if it's a minor mode, when that minor mode is enabled in
the current buffer.
Note that these forms will only have their effect if the
'read-extended-command-predicate' option is customized to call
'command-completion-default-include-p' or a similar function. The
default value of 'read-extended-command-predicate' is nil, which means
no commands that match what you have typed are excluded from being
completion candidates.
+++
** 'define-minor-mode' now takes an ':interactive' argument.