GNU bug report logs - #27230
eldoc doc

Previous Next

Package: emacs;

Reported by: "Charles A. Roelli" <charles <at> aurox.ch>

Date: Sun, 4 Jun 2017 10:39:02 UTC

Severity: minor

Tags: patch

Done: Eli Zaretskii <eliz <at> gnu.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 27230 in the body.
You can then email your comments to 27230 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Sun, 04 Jun 2017 10:39:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to "Charles A. Roelli" <charles <at> aurox.ch>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sun, 04 Jun 2017 10:39:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Charles A. Roelli" <charles <at> aurox.ch>
To: bug-gnu-emacs <at> gnu.org
Subject: eldoc doc
Date: Sun, 4 Jun 2017 12:38:36 +0200
From the top of eldoc.el:

;; One useful way to enable this minor mode is to put the following in your
;; .emacs:
;;
;;      (add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
;;      (add-hook 'lisp-interaction-mode-hook 'eldoc-mode)
;;      (add-hook 'ielm-mode-hook 'eldoc-mode)
;;      (add-hook 'eval-expression-minibuffer-setup-hook 'eldoc-mode)

In 25.2, none of these lines are needed.  Maybe
these lines could be replaced with a mention of global-eldoc-mode,
and how the "globalized" minor mode and eldoc-mode interact (not sure
how they do).

Also, most of the functions in eldoc have no docstring (seems ironic).
Would there be any interest in a patch to fix that?





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Mon, 05 Jun 2017 22:09:02 GMT) Full text and rfc822 format available.

Message #8 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Tue, 6 Jun 2017 01:08:02 +0300
On 6/4/17 1:38 PM, Charles A. Roelli wrote:
>  From the top of eldoc.el:
> 
> ;; One useful way to enable this minor mode is to put the following in your
> ;; .emacs:
> ;;
> ;;      (add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
> ;;      (add-hook 'lisp-interaction-mode-hook 'eldoc-mode)
> ;;      (add-hook 'ielm-mode-hook 'eldoc-mode)
> ;;      (add-hook 'eval-expression-minibuffer-setup-hook 'eldoc-mode)
> 
> In 25.2, none of these lines are needed.  Maybe
> these lines could be replaced with a mention of global-eldoc-mode,
> and how the "globalized" minor mode and eldoc-mode interact (not sure
> how they do).

Do you mean that how define-globalized-minor-mode works is unclear to 
you, or some aspects of how it applies to eldoc-mode?

> Also, most of the functions in eldoc have no docstring (seems ironic).
> Would there be any interest in a patch to fix that?

Sure!




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Tue, 06 Jun 2017 18:34:01 GMT) Full text and rfc822 format available.

Message #11 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: "Charles A. Roelli" <charles <at> aurox.ch>
To: Dmitry Gutov <dgutov <at> yandex.ru>, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Tue, 6 Jun 2017 20:33:09 +0200
I'm confused about how the command `define-globalized-minor-mode'
defines will handle buffers that already have the minor mode turned
on.  Say buffers A and B have simple `eldoc-mode' switched on, and
buffers C and D don't (and global-eldoc-mode is off).  If I then
switch global-eldoc-mode on, is every buffer's value of eldoc-mode
now /on/, or do the values get toggled instead (leaving A and B off, C
and D on)?  And after that, if I toggle global-eldoc-mode off again,
are the previous values remembered and restored, or does every buffer
now have eldoc-mode switched off?


Thanks for your help with this.  I've probably missed a paragraph in the 
docs somewhere.


On 06/06/2017 00:08, Dmitry Gutov wrote:
> On 6/4/17 1:38 PM, Charles A. Roelli wrote:
>>  From the top of eldoc.el:
>>
>> ;; One useful way to enable this minor mode is to put the following 
>> in your
>> ;; .emacs:
>> ;;
>> ;;      (add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
>> ;;      (add-hook 'lisp-interaction-mode-hook 'eldoc-mode)
>> ;;      (add-hook 'ielm-mode-hook 'eldoc-mode)
>> ;;      (add-hook 'eval-expression-minibuffer-setup-hook 'eldoc-mode)
>>
>> In 25.2, none of these lines are needed.  Maybe
>> these lines could be replaced with a mention of global-eldoc-mode,
>> and how the "globalized" minor mode and eldoc-mode interact (not sure
>> how they do).
>
> Do you mean that how define-globalized-minor-mode works is unclear to 
> you, or some aspects of how it applies to eldoc-mode?
>
>> Also, most of the functions in eldoc have no docstring (seems ironic).
>> Would there be any interest in a patch to fix that?
>
> Sure!





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Tue, 06 Jun 2017 20:20:02 GMT) Full text and rfc822 format available.

Message #14 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Tue, 6 Jun 2017 23:19:46 +0300
On 6/6/17 9:33 PM, Charles A. Roelli wrote:
> I'm confused about how the command `define-globalized-minor-mode'
> defines will handle buffers that already have the minor mode turned
> on.

Indeed, the docstring is a bit ambiguous.

Maybe you want to improve the documentation of the said function, or the 
auto-generated docstring that it puts on the created minor modes.

> Say buffers A and B have simple `eldoc-mode' switched on, and
> buffers C and D don't (and global-eldoc-mode is off).  If I then
> switch global-eldoc-mode on, is every buffer's value of eldoc-mode
> now /on/, or do the values get toggled instead (leaving A and B off, C
> and D on)?

Not toggled, of course. On everywhere (where appropriate).

> And after that, if I toggle global-eldoc-mode off again,
> are the previous values remembered and restored, or does every buffer
> now have eldoc-mode switched off?

Not remembered, no. Off everywhere.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Sun, 25 Jun 2017 09:15:01 GMT) Full text and rfc822 format available.

Message #17 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: "Charles A. Roelli" <charles <at> aurox.ch>
To: Dmitry Gutov <dgutov <at> yandex.ru>, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Sun, 25 Jun 2017 11:14:23 +0200
[Message part 1 (text/plain, inline)]
Here's a doc patch for ElDoc, with some minor readability fixes.

I'm unsure how to improve the doc for globalized minor modes, so I'll
leave that for another time.


On 06/06/2017 22:19, Dmitry Gutov wrote:
> On 6/6/17 9:33 PM, Charles A. Roelli wrote:
>> I'm confused about how the command `define-globalized-minor-mode'
>> defines will handle buffers that already have the minor mode turned
>> on.
>
> Indeed, the docstring is a bit ambiguous.
>
> Maybe you want to improve the documentation of the said function, or 
> the auto-generated docstring that it puts on the created minor modes.
>
>> Say buffers A and B have simple `eldoc-mode' switched on, and
>> buffers C and D don't (and global-eldoc-mode is off).  If I then
>> switch global-eldoc-mode on, is every buffer's value of eldoc-mode
>> now /on/, or do the values get toggled instead (leaving A and B off, C
>> and D on)?
>
> Not toggled, of course. On everywhere (where appropriate).
>
>> And after that, if I toggle global-eldoc-mode off again,
>> are the previous values remembered and restored, or does every buffer
>> now have eldoc-mode switched off?
>
> Not remembered, no. Off everywhere.

[0001-ElDoc-add-docstrings-and-minor-refactoring.patch (text/x-patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Sun, 25 Jun 2017 14:28:01 GMT) Full text and rfc822 format available.

Message #20 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: 27230 <at> debbugs.gnu.org, dgutov <at> yandex.ru
Subject: Re: bug#27230: eldoc doc
Date: Sun, 25 Jun 2017 17:26:56 +0300
> From: "Charles A. Roelli" <charles <at> aurox.ch>
> Date: Sun, 25 Jun 2017 11:14:23 +0200
> 
> Here's a doc patch for ElDoc, with some minor readability fixes.

Thanks.  Please allow me a few comments below.

> -(defun eldoc-message (&rest args)
> +(defun eldoc-message (&optional format-string &rest args)
> +  "Store and display the given message.

The first line of a doc string should ideally mention the arguments.

> +FORMAT-STRING and ARGS, if given, are passed to `format-message',
> +the output of which is stored in `eldoc-last-message'.

This leaves me wondering what happens if no arguments are supplied.

>  (defun eldoc--message-command-p (command)
> +  "Non-nil if COMMAND is a command in `eldoc-message-commands'."

"Return non-nil if ...".  The way you wrote it is appropriate for a
variable, not for a function.

>  (defun eldoc-pre-command-refresh-echo-area ()
> +  "Reprint `eldoc-last-message' to the echo area."

Are you sure about the "to" part?  I'd say "in" sounds more correct.

>  (defun eldoc-display-message-p ()
> +  "Non-nil when appropriate to display an ElDoc message."

"Return non-nil"

>  (defun eldoc-display-message-no-interference-p ()
> +  "Nil when displaying an ElDoc message would cause interference
> +with other features."

Likewise.  Also, the first line of a doc string should be a complete
sentence.

>  (defun eldoc-print-current-symbol-info ()
> +  "Print the output of `eldoc-documentation-function'."

"Print the output" sounds confusing.  How about this instead:

  Print the text produced by `eldoc-documentation-function'.

>  (defun eldoc-docstring-format-sym-doc (prefix doc &optional face)
> +  "Concatenate PREFIX and DOC, returning the largest part of the
> +resultant string that can fit in the minibuffer window.

First line not a complete sentence again.

> +When PREFIX is a symbol, apply FACE to it before concatenating.

But FACE is optional, so what if it isn't given?

Thanks for working on this.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Sun, 25 Jun 2017 19:48:02 GMT) Full text and rfc822 format available.

Message #23 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: "Charles A. Roelli" <charles <at> aurox.ch>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 27230 <at> debbugs.gnu.org, dgutov <at> yandex.ru
Subject: Re: bug#27230: eldoc doc
Date: Sun, 25 Jun 2017 21:47:46 +0200
[Message part 1 (text/plain, inline)]
Thanks for the quick review!  Revised patch is attached.


On 25/06/2017 16:26, Eli Zaretskii wrote:
>> From: "Charles A. Roelli" <charles <at> aurox.ch>
>> Date: Sun, 25 Jun 2017 11:14:23 +0200
>>
>> Here's a doc patch for ElDoc, with some minor readability fixes.
> Thanks.  Please allow me a few comments below.
>
>> -(defun eldoc-message (&rest args)
>> +(defun eldoc-message (&optional format-string &rest args)
>> +  "Store and display the given message.
> The first line of a doc string should ideally mention the arguments.

  "Store and possibly display FORMAT-STRING formatted with ARGS.

FORMAT-STRING (or nil, if not given) is stored in
`eldoc-last-message'.  If ARGS are given, FORMAT-STRING is first
formatted through `format-message'.

If `eldoc-last-message' is non-nil, display it using
`eldoc-message-function'.  If it is nil, clear the echo area if
there was recently a message from ElDoc there.

Return `eldoc-last-message'."

>
>> +FORMAT-STRING and ARGS, if given, are passed to `format-message',
>> +the output of which is stored in `eldoc-last-message'.
> This leaves me wondering what happens if no arguments are supplied.

See above.

>
>>   (defun eldoc--message-command-p (command)
>> +  "Non-nil if COMMAND is a command in `eldoc-message-commands'."
> "Return non-nil if ...".  The way you wrote it is appropriate for a
> variable, not for a function.

Fixed.

>
>>   (defun eldoc-pre-command-refresh-echo-area ()
>> +  "Reprint `eldoc-last-message' to the echo area."
> Are you sure about the "to" part?  I'd say "in" sounds more correct.

Agreed, it's fixed.

>
>>   (defun eldoc-display-message-p ()
>> +  "Non-nil when appropriate to display an ElDoc message."
> "Return non-nil"

Fixed.

>
>>   (defun eldoc-display-message-no-interference-p ()
>> +  "Nil when displaying an ElDoc message would cause interference
>> +with other features."
> Likewise.  Also, the first line of a doc string should be a complete
> sentence.

Fixed.

>
>>   (defun eldoc-print-current-symbol-info ()
>> +  "Print the output of `eldoc-documentation-function'."
> "Print the output" sounds confusing.  How about this instead:
>
>    Print the text produced by `eldoc-documentation-function'.

Fixed.

>
>>   (defun eldoc-docstring-format-sym-doc (prefix doc &optional face)
>> +  "Concatenate PREFIX and DOC, returning the largest part of the
>> +resultant string that can fit in the minibuffer window.
> First line not a complete sentence again.

How about this?

  "Combine PREFIX and DOC, and shorten the result to fit in the echo area.

When PREFIX is a symbol, propertize its symbol name with FACE
before combining it with DOC.  If FACE is not provided, just
apply the nil face.

See also: `eldoc-echo-area-use-multiline-p'."

>> +When PREFIX is a symbol, apply FACE to it before concatenating.
> But FACE is optional, so what if it isn't given?

See above.

>
> Thanks for working on this.

Thanks again for your advice.

[0001-ElDoc-add-docstrings-and-minor-refactoring-v2.patch (text/x-patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Mon, 26 Jun 2017 01:05:01 GMT) Full text and rfc822 format available.

Message #26 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Mon, 26 Jun 2017 04:04:18 +0300
On 6/25/17 10:47 PM, Charles A. Roelli wrote:

> FORMAT-STRING (or nil, if not given) is stored in
> `eldoc-last-message'.  If ARGS are given, FORMAT-STRING is first
> formatted through `format-message'.

I wonder if we ever call this function with more than one argument. If 
not, the code and the doc call for simplification. We can avoid 
advertising this possibility, at least.

> If `eldoc-last-message' is non-nil, display it using
> `eldoc-message-function'.  If it is nil, clear the echo area if
> there was recently a message from ElDoc there.

I think this needlessly prioritizes the implementation over the 
intention. And the latter is to display whatever the documentation 
function returns (if non-nil). Saving to eldoc-last-message is 
secondary, and can be mentioned later.

> Return `eldoc-last-message'."

This is probably non-essential, and we can avoid mentioning it.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Tue, 27 Jun 2017 19:52:02 GMT) Full text and rfc822 format available.

Message #29 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: "Charles A. Roelli" <charles <at> aurox.ch>
To: Dmitry Gutov <dgutov <at> yandex.ru>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Tue, 27 Jun 2017 21:51:44 +0200
On 26/06/2017 03:04, Dmitry Gutov wrote:
> On 6/25/17 10:47 PM, Charles A. Roelli wrote:
>
>> FORMAT-STRING (or nil, if not given) is stored in
>> `eldoc-last-message'.  If ARGS are given, FORMAT-STRING is first
>> formatted through `format-message'.
>
> I wonder if we ever call this function with more than one argument. If 
> not, the code and the doc call for simplification. We can avoid 
> advertising this possibility, at least.

I think it follows the tradition of other *-message functions, which
normally use the calling convention of `message'/`format-message'.

>
>> If `eldoc-last-message' is non-nil, display it using
>> `eldoc-message-function'.  If it is nil, clear the echo area if
>> there was recently a message from ElDoc there.
>
> I think this needlessly prioritizes the implementation over the 
> intention. And the latter is to display whatever the documentation 
> function returns (if non-nil). Saving to eldoc-last-message is 
> secondary, and can be mentioned later.

Agreed. Can you suggest how to word it?  Here's what I come up with:

  "Display FORMAT-STRING formatted with ARGS as an ElDoc message.

Store the message (if any) in `eldoc-last-message', and return it."

>
>> Return `eldoc-last-message'."
>
> This is probably non-essential, and we can avoid mentioning it.

I think it once again follows the convention of other *-message
functions, probably for consistency.





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Tue, 27 Jun 2017 23:51:02 GMT) Full text and rfc822 format available.

Message #32 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Wed, 28 Jun 2017 02:50:24 +0300
On 6/27/17 10:51 PM, Charles A. Roelli wrote:

> I think it follows the tradition of other *-message functions, which
> normally use the calling convention of `message'/`format-message'.

Do we really need a function in "the tradition of other *-message 
functions" if we don't ever use it like that?

> Agreed. Can you suggest how to word it?  Here's what I come up with:
> 
>    "Display FORMAT-STRING formatted with ARGS as an ElDoc message.
> 
> Store the message (if any) in `eldoc-last-message', and return it."

Looks okay to me, aside from what I mentioned above.

>>> Return `eldoc-last-message'."
>>
>> This is probably non-essential, and we can avoid mentioning it.
> 
> I think it once again follows the convention of other *-message
> functions, probably for consistency.

Yeah, ok.





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Wed, 28 Jun 2017 19:17:02 GMT) Full text and rfc822 format available.

Message #35 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: "Charles A. Roelli" <charles <at> aurox.ch>
To: Dmitry Gutov <dgutov <at> yandex.ru>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Wed, 28 Jun 2017 21:16:32 +0200
[Message part 1 (text/plain, inline)]
On 28/06/2017 01:50, Dmitry Gutov wrote:
> On 6/27/17 10:51 PM, Charles A. Roelli wrote:
>
>> I think it follows the tradition of other *-message functions, which
>> normally use the calling convention of `message'/`format-message'.
>
> Do we really need a function in "the tradition of other *-message 
> functions" if we don't ever use it like that?

I don't know.  It might be helpful in the future, and it makes sense
to follow the existing convention even if we don't make use of it yet
(patch v3 attached).


[0001-ElDoc-add-docstrings-and-minor-refactoring-v3.patch (text/x-patch, attachment)]

Added tag(s) patch. Request was from npostavs <at> users.sourceforge.net to control <at> debbugs.gnu.org. (Mon, 17 Jul 2017 02:20:02 GMT) Full text and rfc822 format available.

Reply sent to Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility. (Sat, 22 Jul 2017 08:12:01 GMT) Full text and rfc822 format available.

Notification sent to "Charles A. Roelli" <charles <at> aurox.ch>:
bug acknowledged by developer. (Sat, 22 Jul 2017 08:12:02 GMT) Full text and rfc822 format available.

Message #42 received at 27230-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: 27230-done <at> debbugs.gnu.org, dgutov <at> yandex.ru
Subject: Re: bug#27230: eldoc doc
Date: Sat, 22 Jul 2017 11:11:44 +0300
> Cc: 27230 <at> debbugs.gnu.org
> From: "Charles A. Roelli" <charles <at> aurox.ch>
> Date: Wed, 28 Jun 2017 21:16:32 +0200
> 
> (patch v3 attached).

Thanks, pushed.

In the future, please mention the bug number in the commit log
message, so that whoever pushes the changes won't need to do that by
hand.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sat, 19 Aug 2017 11:24:04 GMT) Full text and rfc822 format available.

bug unarchived. Request was from peder <at> klingenberg.no (Peder O. Klingenberg) to control <at> debbugs.gnu.org. (Thu, 14 Sep 2017 11:43:01 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 14 Sep 2017 11:48:02 GMT) Full text and rfc822 format available.

Message #49 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: pok <at> netfonds.no (Peder O. Klingenberg)
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: Eli Zaretskii <eliz <at> gnu.org>, "Charles A. Roelli" <charles <at> aurox.ch>,
 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Thu, 14 Sep 2017 13:47:27 +0200
On Mon, Jun 26 2017 at 04:04, Dmitry Gutov wrote:

> On 6/25/17 10:47 PM, Charles A. Roelli wrote:
>
>> FORMAT-STRING (or nil, if not given) is stored in
>> `eldoc-last-message'.  If ARGS are given, FORMAT-STRING is first
>> formatted through `format-message'.
>
> I wonder if we ever call this function with more than one argument. If
> not, the code and the doc call for simplification. We can avoid
> advertising this possibility, at least.

As I discovered today, when I updated my tree, there are callers outside
emacs core that do call eldoc-message with more than one argument.
slime-autodoc.el is one such package, which I use.

The slime project has an open issue on this, with a patch, but it hasn't
been applied yet, after sitting in the discussion for 17 days.

IMO commit 7ef0b5f611c2d56ac2edb8de287190f04c4b8f32 was an ill-advised
change.  The code worked fine before, the cleanup afforded by breaking
the api was negligible.  I think it should be reverted.

(Slime would benefit from cleaing up their callers as well, no doubt,
but not every slime user should be forced to do that on their own.  And
there may be more third-party, infrequently maintained packages using
eldoc.)

...Peder...
-- 
This must be Thursday.  I never could get the hang of Thursdays.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 14 Sep 2017 12:03:01 GMT) Full text and rfc822 format available.

Message #52 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Peder O. Klingenberg" <pok <at> netfonds.no>
Cc: "Charles A. Roelli" <charles <at> aurox.ch>, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Thu, 14 Sep 2017 15:02:11 +0300
On 9/14/17 2:47 PM, Peder O. Klingenberg wrote:

> As I discovered today, when I updated my tree, there are callers outside
> emacs core that do call eldoc-message with more than one argument.
> slime-autodoc.el is one such package, which I use.

Thanks for letting us know.

> The slime project has an open issue on this, with a patch, but it hasn't
> been applied yet, after sitting in the discussion for 17 days.

I've commented on it: https://github.com/slime/slime/issues/400

For one thing, third-party packages should *not* use eldoc-message.

> IMO commit 7ef0b5f611c2d56ac2edb8de287190f04c4b8f32 was an ill-advised
> change.  The code worked fine before, the cleanup afforded by breaking
> the api was negligible.  I think it should be reverted.

Aside from breaking the "obviously wrong" callers like explained above, 
the code had a subtle bug where calling it with no format arguments, and 
then with some arguments, wouldn't update the message area.

> (Slime would benefit from cleaing up their callers as well, no doubt,
> but not every slime user should be forced to do that on their own.

Of course, the project maintainers should do it.

All the best,
Dmitry.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 14 Sep 2017 19:40:02 GMT) Full text and rfc822 format available.

Message #55 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Thu, 14 Sep 2017 21:39:04 +0200
> From: Dmitry Gutov <dgutov <at> yandex.ru>
> Date: Thu, 14 Sep 2017 15:02:11 +0300
> 
> For one thing, third-party packages should *not* use eldoc-message.

Right.  But why should we break its calling convention without good
reason, when we can see that now that other packages have been using
it?  Moreover, the function has probably been around for awhile, and
without good documentation, it might not have been clear that it's
best suited for "internal" use.

This change might also be mentioned under "Incompatible Lisp Changes"
in NEWS, and it should be discussed in a separate bug report since it
doesn't have much to do with "eldoc doc" (which this bug was about).




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 14 Sep 2017 22:04:01 GMT) Full text and rfc822 format available.

Message #58 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Fri, 15 Sep 2017 01:03:35 +0300
On 9/14/17 10:39 PM, Charles A. Roelli wrote:

> Right.  But why should we break its calling convention without good
> reason, when we can see that now that other packages have been using
> it?

Now they know they should fix it, though.

> This change might also be mentioned under "Incompatible Lisp Changes"
> in NEWS, and it should be discussed in a separate bug report since it
> doesn't have much to do with "eldoc doc" (which this bug was about).

Sometimes we go off tangent. It's not the end of the world.

But yes, it's a good idea, thanks.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Tue, 19 Sep 2017 20:03:01 GMT) Full text and rfc822 format available.

Message #61 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Tue, 19 Sep 2017 22:02:33 +0200
[Message part 1 (text/plain, inline)]
> From: Dmitry Gutov <dgutov <at> yandex.ru>
> Date: Fri, 15 Sep 2017 01:03:35 +0300
> 
> > Right.  But why should we break its calling convention without good
> > reason, when we can see that now that other packages have been using
> > it?
> 
> Now they know they should fix it, though.

Unfortunately it means there are probably other users of the function,
and if we don't document the change, the function should stay as is.
Attached is a patch that brings back the old behavior, without the
convoluted buggy logic for setting eldoc-last-message.  What do you
think?

And from an earlier message:

> Aside from breaking the "obviously wrong" callers like explained above, 
> the code had a subtle bug where calling it with no format arguments, and 
> then with some arguments, wouldn't update the message area.

Should be fixed with this patch.

[0001-Keep-old-calling-convention-of-eldoc-message.patch (text/x-patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Wed, 20 Sep 2017 18:13:01 GMT) Full text and rfc822 format available.

Message #64 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: charles <at> aurox.ch (Charles A. Roelli)
Cc: 27230 <at> debbugs.gnu.org, pok <at> netfonds.no, dgutov <at> yandex.ru
Subject: Re: bug#27230: eldoc doc
Date: Wed, 20 Sep 2017 20:12:38 +0200
[Message part 1 (text/plain, inline)]
Sorry, I had forgotten to update the docstring.  Updated patch
attached.

[0001-Keep-old-calling-convention-of-eldoc-message.patch (text/x-patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 21 Sep 2017 14:24:02 GMT) Full text and rfc822 format available.

Message #67 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Thu, 21 Sep 2017 17:23:22 +0300
Hey Charles,

On 9/20/17 9:12 PM, Charles A. Roelli wrote:
> Sorry, I had forgotten to update the docstring.  Updated patch
> attached.

Is there a reason you so strongly insist on returning to the original 
calling convention? I'd rather add a NEWS entry instead.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 21 Sep 2017 18:34:01 GMT) Full text and rfc822 format available.

Message #70 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Thu, 21 Sep 2017 20:33:29 +0200
> Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
> From: Dmitry Gutov <dgutov <at> yandex.ru>
> Date: Thu, 21 Sep 2017 17:23:22 +0300
> 
> Hey Charles,
> 
> On 9/20/17 9:12 PM, Charles A. Roelli wrote:
> > Sorry, I had forgotten to update the docstring.  Updated patch
> > attached.
> 
> Is there a reason you so strongly insist on returning to the original 
> calling convention?

Yes, and another user gave an opinion too.  What do others think?




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Thu, 21 Sep 2017 23:07:02 GMT) Full text and rfc822 format available.

Message #73 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Fri, 22 Sep 2017 02:05:54 +0300
On 9/21/17 9:33 PM, Charles A. Roelli wrote:

> Yes, and another user gave an opinion too.  What do others think?

Just FYI, the SLIME project has merged the patch a week ago. It 
shouldn't be a problem anymore.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#27230; Package emacs. (Mon, 25 Sep 2017 23:27:02 GMT) Full text and rfc822 format available.

Message #76 received at 27230 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: pok <at> netfonds.no, 27230 <at> debbugs.gnu.org
Subject: Re: bug#27230: eldoc doc
Date: Tue, 26 Sep 2017 02:26:42 +0300
On 9/21/17 9:33 PM, Charles A. Roelli wrote:
> What do others think?

Since nobody else is chiming in, I've updated the "Incompatible Lisp 
Changes" in etc/NEWS.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Tue, 24 Oct 2017 11:24:05 GMT) Full text and rfc822 format available.

This bug report was last modified 7 years and 297 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.