unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#64045: [PATCH] Improve wording of the documentation about declare form
@ 2023-06-13 13:36 Shynur Xie
  2023-06-13 13:46 ` Eli Zaretskii
  0 siblings, 1 reply; 5+ messages in thread
From: Shynur Xie @ 2023-06-13 13:36 UTC (permalink / raw)
  To: 64045

[-- Attachment #1: Type: text/plain, Size: 402 bytes --]

I modified section 13.14 (The declare form) of the GNU Emacs Lisp
Reference Manual.  The manual didn't say how to make

    (declare (completion ...)
             (modes ...))

take effect; the original text is even somewhat misleading.  Simply
evaluating a (defun ...) form which includes the above declare form
won't make Emacs filter commands when asking for completion in M-x.

--
shynur

[-- Attachment #2: 0001-Improve-wording-of-the-documentation-about-declare-f.patch --]
[-- Type: application/octet-stream, Size: 2503 bytes --]

From 36ed6cf7b74b33cb4df2b28950736854eddcdbf3 Mon Sep 17 00:00:00 2001
From: Shynur <one.last.kiss@outlook.com>
Date: Tue, 13 Jun 2023 21:14:37 +0800
Subject: [PATCH] ; Improve wording of the documentation about declare form

---
 doc/lispref/functions.texi | 20 +++++++++++---------
 lisp/simple.el             |  5 ++++-
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index a94fdee1d82..68296dd437a 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2613,15 +2613,17 @@ additionally have access to the macro (or function)'s arguments and it will
 be passed to @code{gv-define-setter}.
 
 @item (completion @var{completion-predicate})
-Declare @var{completion-predicate} as a function to determine whether
-to include the symbol in the list of functions when asking for
-completions in @kbd{M-x}.  @var{completion-predicate} is called with
-two parameters: The first parameter is the symbol, and the second is
-the current buffer.
-
-@item (modes @var{modes})
-Specify that this command is meant to be applicable for @var{modes}
-only.
+Declare @var{completion-predicate} as a function to determine, when
+option @code{read-extended-command-predicate} is set to
+@code{command-completion-default-include-p}, whether to include the
+symbol in the list of functions when asking for completions in
+@kbd{M-x}.  @var{completion-predicate} is called with two parameters:
+The first parameter is the symbol, and the second is the current
+buffer.
+
+@item (modes @var{mode} ...)
+Specify that this command is meant to be applicable for @var{mode}s
+only.  See @xref{Command Modes}.
 
 @item (interactive-args @var{arg} ...)
 Specify the arguments that should be stored for @code{repeat-command}.
diff --git a/lisp/simple.el b/lisp/simple.el
index e08bf4fdd64..30410cde4c2 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2226,7 +2226,10 @@ are available:
          This excludes from completion candidates those commands
          which have been marked specific to modes other than the
          current buffer's mode.  Commands that are not specific
-         to any mode are included.
+         to any mode are included.  If there's a
+         `completion-predicate' for a command, this command is
+         excluded as well if the result calling from its predicate
+         is nil.
 
   `command-completion-using-modes-p'
          This includes in completion candidates only commands
-- 
2.39.1


^ permalink raw reply related	[flat|nested] 5+ messages in thread

* bug#64045: [PATCH] Improve wording of the documentation about declare form
  2023-06-13 13:36 bug#64045: [PATCH] Improve wording of the documentation about declare form Shynur Xie
@ 2023-06-13 13:46 ` Eli Zaretskii
  2023-06-13 13:54   ` Shynur Xie
  0 siblings, 1 reply; 5+ messages in thread
From: Eli Zaretskii @ 2023-06-13 13:46 UTC (permalink / raw)
  To: Shynur Xie; +Cc: 64045

> From: Shynur Xie <one.last.kiss@outlook.com>
> Date: Tue, 13 Jun 2023 13:36:50 +0000
> msip_labels: 
> 
> I modified section 13.14 (The declare form) of the GNU Emacs Lisp
> Reference Manual.  The manual didn't say how to make
> 
>     (declare (completion ...)
>              (modes ...))
> 
> take effect; the original text is even somewhat misleading.  Simply
> evaluating a (defun ...) form which includes the above declare form
> won't make Emacs filter commands when asking for completion in M-x.

Thanks, but the text you suggest reads as more complex and harder to
understand.  So how about explaining what was wrong or missing or
unclear in the original text?  Then I could come up with a better
wording.





^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#64045: [PATCH] Improve wording of the documentation about declare form
  2023-06-13 13:46 ` Eli Zaretskii
@ 2023-06-13 13:54   ` Shynur Xie
  2023-06-15  6:29     ` Eli Zaretskii
  0 siblings, 1 reply; 5+ messages in thread
From: Shynur Xie @ 2023-06-13 13:54 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 64045@debbugs.gnu.org

>    From: Eli Zaretskii <eliz@gnu.org>
>    Date: Tue, 13 Jun 2023 16:46:47 +0300
> Subject: Re: bug#64045
>      To: Shynur Xie <one.last.kiss@outlook.com>
>
> So how about explaining what was wrong or missing or unclear in the
> original text?

You can read these 2 posts (very short and won't take up much of your
time):

- Question: Effect of `modes` In Declare Form
  https://emacs.stackexchange.com/questions/77597
- Question: `completion` In Declare Form Not Working
  https://emacs.stackexchange.com/questions/77599

Thanks.




^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#64045: [PATCH] Improve wording of the documentation about declare form
  2023-06-13 13:54   ` Shynur Xie
@ 2023-06-15  6:29     ` Eli Zaretskii
  2023-06-21 14:07       ` Eli Zaretskii
  0 siblings, 1 reply; 5+ messages in thread
From: Eli Zaretskii @ 2023-06-15  6:29 UTC (permalink / raw)
  To: Shynur Xie; +Cc: 64045

> From: Shynur Xie <one.last.kiss@outlook.com>
> CC: "64045@debbugs.gnu.org" <64045@debbugs.gnu.org>
> Date: Tue, 13 Jun 2023 13:54:26 +0000
> msip_labels:
> 
> >    From: Eli Zaretskii <eliz@gnu.org>
> >    Date: Tue, 13 Jun 2023 16:46:47 +0300
> > Subject: Re: bug#64045
> >      To: Shynur Xie <one.last.kiss@outlook.com>
> >
> > So how about explaining what was wrong or missing or unclear in the
> > original text?
> 
> You can read these 2 posts (very short and won't take up much of your
> time):
> 
> - Question: Effect of `modes` In Declare Form
>   https://emacs.stackexchange.com/questions/77597
> - Question: `completion` In Declare Form Not Working
>   https://emacs.stackexchange.com/questions/77599

Thanks, I've clarified these now on the emacs-29 branch.





^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#64045: [PATCH] Improve wording of the documentation about declare form
  2023-06-15  6:29     ` Eli Zaretskii
@ 2023-06-21 14:07       ` Eli Zaretskii
  0 siblings, 0 replies; 5+ messages in thread
From: Eli Zaretskii @ 2023-06-21 14:07 UTC (permalink / raw)
  To: one.last.kiss; +Cc: 64045-done

> Cc: 64045@debbugs.gnu.org
> Date: Thu, 15 Jun 2023 09:29:48 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Shynur Xie <one.last.kiss@outlook.com>
> > CC: "64045@debbugs.gnu.org" <64045@debbugs.gnu.org>
> > Date: Tue, 13 Jun 2023 13:54:26 +0000
> > msip_labels:
> > 
> > >    From: Eli Zaretskii <eliz@gnu.org>
> > >    Date: Tue, 13 Jun 2023 16:46:47 +0300
> > > Subject: Re: bug#64045
> > >      To: Shynur Xie <one.last.kiss@outlook.com>
> > >
> > > So how about explaining what was wrong or missing or unclear in the
> > > original text?
> > 
> > You can read these 2 posts (very short and won't take up much of your
> > time):
> > 
> > - Question: Effect of `modes` In Declare Form
> >   https://emacs.stackexchange.com/questions/77597
> > - Question: `completion` In Declare Form Not Working
> >   https://emacs.stackexchange.com/questions/77599
> 
> Thanks, I've clarified these now on the emacs-29 branch.

No further comments, so I'm now closing this bug.





^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2023-06-21 14:07 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-06-13 13:36 bug#64045: [PATCH] Improve wording of the documentation about declare form Shynur Xie
2023-06-13 13:46 ` Eli Zaretskii
2023-06-13 13:54   ` Shynur Xie
2023-06-15  6:29     ` Eli Zaretskii
2023-06-21 14:07       ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).