bug#27229: eldoc wrong highlighting for "when"

bug#27229: eldoc wrong highlighting for "when"

[Charles A. Roelli]

 From emacs -q, type "(when x y z": COND is highlighted
instead of BODY.  This is a regression from the behavior
of 24.5 (with eldoc-mode on).

bug#27229: eldoc wrong highlighting for "when"

[Andreas Politz]

In Emacs 24.5 this highlighting was done in the function
eldoc-highlight-function-argument, which since then has been moved to
elisp--highlight-function-argument and was also heavily extended.

From reading the new code, it seems to interpret doc-strings of the kind
"(FN ARG0 ARG1...)", as being a macro with alternating forms, e.g. like
setq.  While previously, I think, they were constantly treated as a "(FN
ARG BODY..)" type.

-ap

bug#27229: eldoc wrong highlighting for "when"

[Stefan Kangas]

found 27229 28.0.50
tags 27229 + confirmed
thanks

"Charles A. Roelli" <charles@aurox.ch> writes:

> From emacs -q, type "(when x y z": COND is highlighted
> instead of BODY.  This is a regression from the behavior
> of 24.5 (with eldoc-mode on).

I can reproduce this on current master.

Best regards,
Stefan Kangas

bug#27229: eldoc wrong highlighting for "when"

[Michael Heerdegen]

Stefan Kangas <stefan@marxist.se> writes:

> "Charles A. Roelli" <charles@aurox.ch> writes:
>
> > From emacs -q, type "(when x y z": COND is highlighted
> > instead of BODY.  This is a regression from the behavior
> > of 24.5 (with eldoc-mode on).
>
> I can reproduce this on current master.

Seems this code is the culprit (`elisp--highlight-function-argument'):

| ;; Back to index 0 in ARG1 ARG2 ARG2 ARG3 etc...
| ;; like in `setq'.
| ((or (and (string-match-p "\\.\\.\\.\\'" argument)
|           (string= argument (car (last args-lst))))
|      (and (string-match-p "\\.\\.\\.\\'"
|                           (substring args 1 (1- (length args))))
|           (= (length (remove "..." args-lst)) 2)
|           (> index 1) (eq (logand index 1) 1)))
|  (setq index 0))

In general, the problem is that "..." can have different meanings (it's
not clear which arguments have to be repeated), so this is not trivial
to fix I think.

Michael.

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

>> > From emacs -q, type "(when x y z": COND is highlighted
>> > instead of BODY.  This is a regression from the behavior
>> > of 24.5 (with eldoc-mode on).
>>
>> I can reproduce this on current master.
>
> Seems this code is the culprit (`elisp--highlight-function-argument'):
>
> | ;; Back to index 0 in ARG1 ARG2 ARG2 ARG3 etc...
> | ;; like in `setq'.
> | ((or (and (string-match-p "\\.\\.\\.\\'" argument)
> |           (string= argument (car (last args-lst))))
> |      (and (string-match-p "\\.\\.\\.\\'"
> |                           (substring args 1 (1- (length args))))
> |           (= (length (remove "..." args-lst)) 2)
> |           (> index 1) (eq (logand index 1) 1)))
> |  (setq index 0))
>
> In general, the problem is that "..." can have different meanings (it's
> not clear which arguments have to be repeated), so this is not trivial
> to fix I think.

I wonder -- why is this defined like this, anyway?

(defmacro when (cond &rest body)
  "If COND yields non-nil, do BODY, else return nil.
When COND yields non-nil, eval BODY forms sequentially and return
value of last one, or nil if there are none.

\(fn COND BODY...)"

(when COND &rest BODY)

is the correct signature, isn't it?  Removing the (fn ...) from the doc
string makes eldoc do the correct thing.

The commit message is helpful:

commit 7f67eea000b0ba102dd86c2666041dc395137413
Author:     Kim F. Storm <storm@cua.dk>
AuthorDate: Sun Mar 18 00:44:24 2007 +0000

    (when, unless): Doc fix.

Anybody know what the point of the (fn...) here is?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Andy Moreton]

On Fri 03 Sep 2021, Lars Ingebrigtsen wrote:

> Michael Heerdegen <michael_heerdegen@web.de> writes:
>
>>> > From emacs -q, type "(when x y z": COND is highlighted
>>> > instead of BODY.  This is a regression from the behavior
>>> > of 24.5 (with eldoc-mode on).
>>>
>>> I can reproduce this on current master.
>>
>> Seems this code is the culprit (`elisp--highlight-function-argument'):
>>
>> | ;; Back to index 0 in ARG1 ARG2 ARG2 ARG3 etc...
>> | ;; like in `setq'.
>> | ((or (and (string-match-p "\\.\\.\\.\\'" argument)
>> |           (string= argument (car (last args-lst))))
>> |      (and (string-match-p "\\.\\.\\.\\'"
>> |                           (substring args 1 (1- (length args))))
>> |           (= (length (remove "..." args-lst)) 2)
>> |           (> index 1) (eq (logand index 1) 1)))
>> |  (setq index 0))
>>
>> In general, the problem is that "..." can have different meanings (it's
>> not clear which arguments have to be repeated), so this is not trivial
>> to fix I think.
>
> I wonder -- why is this defined like this, anyway?
>
> (defmacro when (cond &rest body)
>   "If COND yields non-nil, do BODY, else return nil.
> When COND yields non-nil, eval BODY forms sequentially and return
> value of last one, or nil if there are none.
>
> \(fn COND BODY...)"
>
> (when COND &rest BODY)
>
> is the correct signature, isn't it?  Removing the (fn ...) from the doc
> string makes eldoc do the correct thing.
>
> The commit message is helpful:
>
> commit 7f67eea000b0ba102dd86c2666041dc395137413
> Author:     Kim F. Storm <storm@cua.dk>
> AuthorDate: Sun Mar 18 00:44:24 2007 +0000
>
>     (when, unless): Doc fix.
>
> Anybody know what the point of the (fn...) here is?

Have a look at (info "(elisp) Function Documentation") which explains
this usage. Perhaps eldoc needs fixing to understand that idiom.

    AndyM

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Andy Moreton <andrewjmoreton@gmail.com> writes:

>> Anybody know what the point of the (fn...) here is?
>
> Have a look at (info "(elisp) Function Documentation") which explains
> this usage. Perhaps eldoc needs fixing to understand that idiom.

I know what (fn ...) does.  I'm asking what's the point of it here,
since the (fn ...) just seems to restate what's already the actual
parameter list.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Andy Moreton]

On Fri 03 Sep 2021, Lars Ingebrigtsen wrote:

> Andy Moreton <andrewjmoreton@gmail.com> writes:
>
>>> Anybody know what the point of the (fn...) here is?
>>
>> Have a look at (info "(elisp) Function Documentation") which explains
>> this usage. Perhaps eldoc needs fixing to understand that idiom.
>
> I know what (fn ...) does.  I'm asking what's the point of it here,
> since the (fn ...) just seems to restate what's already the actual
> parameter list.

Without using "fn", it is shown as "(when COND &rest BODY)" which is
less helpful than showing "(when COND BODY...)".

    AndyM

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Andy Moreton <andrewjmoreton@gmail.com> writes:

> Without using "fn", it is shown as "(when COND &rest BODY)" which is
> less helpful than showing "(when COND BODY...)".

What do you feel the semantic difference is between the two?  And why
should `when' have this fn rewrite when we have hundreds of other
macros with &rest body that don't have an fn?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Andy Moreton]

On Sat 04 Sep 2021, Lars Ingebrigtsen wrote:

> Andy Moreton <andrewjmoreton@gmail.com> writes:
>
>> Without using "fn", it is shown as "(when COND &rest BODY)" which is
>> less helpful than showing "(when COND BODY...)".
>
> What do you feel the semantic difference is between the two?  And why
> should `when' have this fn rewrite when we have hundreds of other
> macros with &rest body that don't have an fn?

I think that the difference is whether the user sees it as describing
arguments to a function call, or forms in a control structure. The
"(when COND BODY...)" version also matches the style used for `if'.

Most of the other macros are intended to look like function calls to the
user, not control structures.

    AndyM

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Andy Moreton <andrewjmoreton@gmail.com> writes:

> I think that the difference is whether the user sees it as describing
> arguments to a function call, or forms in a control structure. The
> "(when COND BODY...)" version also matches the style used for `if'.
>
> Most of the other macros are intended to look like function calls to the
> user, not control structures.

Like...  `when-let'?

I think it pretty much looks like the (fn) in `when' (and `unless') is a
bug (it certainly trips up eldoc here, which would do the correct thing
if (fn) is removed).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I think it pretty much looks like the (fn) in `when' (and `unless') is a
> bug (it certainly trips up eldoc here, which would do the correct thing
> if (fn) is removed).

So I've now done this in Emacs 29.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Eli Zaretskii]

> Resent-From: Lars Ingebrigtsen <larsi@gnus.org>
> Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
> Resent-CC: bug-gnu-emacs@gnu.org
> Resent-Sender: help-debbugs@gnu.org
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 02 May 2022 12:30:56 +0200
> Cc: 27229@debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > I think it pretty much looks like the (fn) in `when' (and `unless') is a
> > bug (it certainly trips up eldoc here, which would do the correct thing
> > if (fn) is removed).
> 
> So I've now done this in Emacs 29.

So now "C-h f when" says

  (when COND &rest BODY)

where it previously said

  (when COND BODY...)

Isn't this a regression?

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> So now "C-h f when" says
>
>   (when COND &rest BODY)
>
> where it previously said
>
>   (when COND BODY...)
>
> Isn't this a regression?

In what way?  We have &rest BODY all over the place, and it's the
correct syntax to specify that there's a body, so I don't understand
what you mean.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: andrewjmoreton@gmail.com,  27229@debbugs.gnu.org
> Date: Tue, 03 May 2022 11:05:02 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So now "C-h f when" says
> >
> >   (when COND &rest BODY)
> >
> > where it previously said
> >
> >   (when COND BODY...)
> >
> > Isn't this a regression?
> 
> In what way?  We have &rest BODY all over the place, and it's the
> correct syntax to specify that there's a body, so I don't understand
> what you mean.

But when and unless aren't functions, they are "special forms".  So
using &rest there is less self-explanatory for those who aren't
necessarily privy to the internals.

IOW, the removed (fn ..." stuff was there for a reason.  The original
bug report here wasn't about how we display the doc string, it was
about what eldoc does.  So IMO the fix should have been in eldoc,
which would also avoid this negative effect.

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> But when and unless aren't functions, they are "special forms".  So
> using &rest there is less self-explanatory for those who aren't
> necessarily privy to the internals.

'defmacro.*&rest.body' gives me 487 results, and only `when' and `until'
had that odd (fn).

If we want *Help* to display &rest body in a different way, then we
should fix that in help-mode, not mess up the calling convention string.

> IOW, the removed (fn ..." stuff was there for a reason.  The original
> bug report here wasn't about how we display the doc string, it was
> about what eldoc does.  So IMO the fix should have been in eldoc,
> which would also avoid this negative effect.

As the bug report explains, there is no fix possible, since the "..."
syntax is ambiguous: We use it both for "and then there's more" and
"there are alternating pairs of arguments".

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: andrewjmoreton@gmail.com,  27229@debbugs.gnu.org
> Date: Tue, 03 May 2022 13:09:38 +0200
> 
> If we want *Help* to display &rest body in a different way, then we
> should fix that in help-mode, not mess up the calling convention string.
> 
> > IOW, the removed (fn ..." stuff was there for a reason.  The original
> > bug report here wasn't about how we display the doc string, it was
> > about what eldoc does.  So IMO the fix should have been in eldoc,
> > which would also avoid this negative effect.
> 
> As the bug report explains, there is no fix possible, since the "..."
> syntax is ambiguous: We use it both for "and then there's more" and
> "there are alternating pairs of arguments".

So you are saying that we cannot use "(fn ..." because eldoc doesn't
like that?  Doesn't sound reasonable to me.  eldoc is a minor, albeit
important, mode; it isn't right for a minor mode to dictate our
documentation formats.

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> So you are saying that we cannot use "(fn ..." because eldoc doesn't
> like that?  Doesn't sound reasonable to me.  eldoc is a minor, albeit
> important, mode; it isn't right for a minor mode to dictate our
> documentation formats.

No, I'm saying that the (fn ... in when/unless was wrong in any case, and
shouldn't have been there.  Since we don't use that in the hundreds of
other &rest body macros, it serves to confuse the users who will wonder
why when/unless look odd.

Like I said, if we want to change how we present &rest body to the
users, then we should do so for all of these macros, and not just two.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: andrewjmoreton@gmail.com,  27229@debbugs.gnu.org
> Date: Tue, 03 May 2022 13:24:15 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So you are saying that we cannot use "(fn ..." because eldoc doesn't
> > like that?  Doesn't sound reasonable to me.  eldoc is a minor, albeit
> > important, mode; it isn't right for a minor mode to dictate our
> > documentation formats.
> 
> No, I'm saying that the (fn ... in when/unless was wrong in any case, and
> shouldn't have been there.

What about the more general case of using that in any other place?
Are you saying that it will work in other places, and just in those
two places didn't work?

> Since we don't use that in the hundreds of other &rest body macros,
> it serves to confuse the users who will wonder why when/unless look
> odd.

I'm not worried too much about these two, I'm more worried about the
ability to use the advertised-signature feature in general.

> Like I said, if we want to change how we present &rest body to the
> users, then we should do so for all of these macros, and not just two.

What about if I want to change that only for a specific case, not in
general?  Is this now "verboten"?

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I'm not worried too much about these two, I'm more worried about the
> ability to use the advertised-signature feature in general.

There is no general case here -- the advertised convention in these two
cases were with all the other macros that have this signature, and
removed information to boot.

>> Like I said, if we want to change how we present &rest body to the
>> users, then we should do so for all of these macros, and not just two.
>
> What about if I want to change that only for a specific case, not in
> general?  Is this now "verboten"?

Not if the advertised convention is an improvement.  It wasn't here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: andrewjmoreton@gmail.com,  27229@debbugs.gnu.org
> Date: Wed, 04 May 2022 09:46:32 +0200
> 
> > What about if I want to change that only for a specific case, not in
> > general?  Is this now "verboten"?
> 
> Not if the advertised convention is an improvement.  It wasn't here.

So you are saying that adding

  (fn FOO BODY...)

in other cases will _not_ trip eldoc as it did with 'when' and
'unless'?

bug#27229: eldoc wrong highlighting for "when"

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> So you are saying that adding
>
>   (fn FOO BODY...)
>
> in other cases will _not_ trip eldoc as it did with 'when' and
> 'unless'?

No?  But I don't know whether we have any other cases like that in the
code base.

Let's see...  the only other instance we seem to have is in rx.el.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#27229: eldoc wrong highlighting for "when"

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > > So now "C-h f when" says
  > > >
  > > >   (when COND &rest BODY)
  > > >
  > > > where it previously said
  > > >
  > > >   (when COND BODY...)
  > > >
  > > > Isn't this a regression?
  > > 
  > > In what way?  We have &rest BODY all over the place, and it's the
  > > correct syntax to specify that there's a body, so I don't understand
  > > what you mean.

  > But when and unless aren't functions, they are "special forms".  So
  > using &rest there is less self-explanatory for those who aren't
  > necessarily privy to the internals.

That is right.  The keywords &rest and &optional are for arguments,
and they imply that the values are evaluated in the usual way.

A special form is a syntactic construct, not a function call.
Its parts are not arguments to a function.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)