GNU bug report logs - #42532
28.0.50; Can eldoc-prefer-doc-buffer be more aggressive?

Previous Next

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

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

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

From: Felician Nemeth <felician.nemeth <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; Can eldoc-prefer-doc-buffer be more aggressive?
Date: Sat, 25 Jul 2020 20:17:34 +0200

[Message part 1 (text/plain, inline)]

With the attached file, start emacs as:

  emacs -Q --load bug.el

and then move the point left or right.  Originally I started to write
this file as demonstration to bug#42421, but you fixed the bug faster
than I could find time to finish it.  Now, I think everything works as
documented, but with the help of this recipe, I'd like to argue that
eldoc-prefer-doc-buffer is a bit annoying in this case.  Its
documentation says:

   Prefer ElDoc’s documentation buffer if it is showing in some frame.
   If this variable’s value is t and a piece of documentation needs to
   be truncated to fit in the echo area, do so if ElDoc’s documentation
   buffer is not already showing, since the buffer always holds the full
   documentation.

I think it would be better to show the documentation only in the *eldoc*
buffer and not in the echo area even if the documentation doesn't need
to be truncated but the echo are needs to be resized to display the full
documentation.

(bug.el changes eldoc-documentation-function to circumvent bug#42531,
which I reported few minutes ago, but changing the order of the hooks in
eldoc--eval-expression-setup, doesn't seem to fix bug#42531)

Thank you, João, for your work on eldoc.

[bug.el (#("application/emacs-lisp", attachment)]

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

From: João Távora <joaotavora <at> gmail.com>
To: Felician Nemeth <felician.nemeth <at> gmail.com>, Yuan Fu <casouri <at> gmail.com>
Cc: 42532 <at> debbugs.gnu.org
Subject: Re: bug#42532: 28.0.50;
 Can eldoc-prefer-doc-buffer be more aggressive?
Date: Mon, 7 Sep 2020 09:38:16 +0100

[Message part 1 (text/plain, inline)]

Hi Felician,

Sorry for the late reply. I'm working, and am very close to publishing,
the promised introduction of eldoc-display-functions to help users (and
third-party devs) better control the display of eldoc documentation.

Regardless, I think it's reasonable to add a third possible value
for eldoc-prefer-doc-buffer (which should really be renamed
eldoc-echo-area-prefer-doc-buffer).  The value could be the symbol
'aggressive or 'aggressively.  Then it would behave as you propose:
if the ElDoc doc buffer is showing, the echo area display code is
a noop.

What do you think?

João

On Sat, Jul 25, 2020 at 7:18 PM Felician Nemeth <felician.nemeth <at> gmail.com>
wrote:

> With the attached file, start emacs as:
>
>   emacs -Q --load bug.el
>
> and then move the point left or right.  Originally I started to write
> this file as demonstration to bug#42421, but you fixed the bug faster
> than I could find time to finish it.  Now, I think everything works as
> documented, but with the help of this recipe, I'd like to argue that
> eldoc-prefer-doc-buffer is a bit annoying in this case.  Its
> documentation says:
>
>    Prefer ElDoc’s documentation buffer if it is showing in some frame.
>    If this variable’s value is t and a piece of documentation needs to
>    be truncated to fit in the echo area, do so if ElDoc’s documentation
>    buffer is not already showing, since the buffer always holds the full
>    documentation.
>
> I think it would be better to show the documentation only in the *eldoc*
> buffer and not in the echo area even if the documentation doesn't need
> to be truncated but the echo are needs to be resized to display the full
> documentation.
>
> (bug.el changes eldoc-documentation-function to circumvent bug#42531,
> which I reported few minutes ago, but changing the order of the hooks in
> eldoc--eval-expression-setup, doesn't seem to fix bug#42531)
>
> Thank you, João, for your work on eldoc.
>
>

-- 
João Távora

[Message part 2 (text/html, inline)]

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

From: João Távora <joaotavora <at> gmail.com>
To: Felician Nemeth <felician.nemeth <at> gmail.com>
Cc: Yuan Fu <casouri <at> gmail.com>, 42532 <at> debbugs.gnu.org
Subject: Re: bug#42532: 28.0.50; Can eldoc-prefer-doc-buffer be more
 aggressive?
Date: Mon, 07 Sep 2020 11:11:39 +0100

João Távora <joaotavora <at> gmail.com> writes:

> Regardless, I think it's reasonable to add a third possible value 
> for eldoc-prefer-doc-buffer (which should really be renamed 
> eldoc-echo-area-prefer-doc-buffer).  The value could be the symbol
> 'aggressive or 'aggressively.  Then it would behave as you propose:
> if the ElDoc doc buffer is showing, the echo area display code is 
> a noop.
>
> What do you think?

Instead of an abstract idea, here's an actual patch you can try on top
of the current eldoc.el

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 772c907c28..2eae30f004 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -111,13 +111,19 @@ eldoc-echo-area-use-multiline-p
  symbol names if it will\ enable argument list to fit on one
  line" truncate-sym-name-if-fit)))
 
-(defcustom eldoc-prefer-doc-buffer nil
+(define-obsolete-variable-alias 'eldoc-prefer-doc-buffer
+  'eldoc-echo-area-prefer-doc-buffer "eldoc-1.11.0")
+(defcustom eldoc-echo-area-prefer-doc-buffer nil
   "Prefer ElDoc's documentation buffer if it is showing in some frame.
 If this variable's value is t and a piece of documentation needs
-to be truncated to fit in the echo area, do so if ElDoc's
+to be truncated to fit in the echo area, do so if ElDoc's only
 documentation buffer is not already showing, since the buffer
-always holds the full documentation."
-  :type 'boolean)
+always holds the full documentation.  If the value is
+`aggressively' do so even if the documentation doesn't need to be
+truncated."
+  :type '(radio (const :tag "Yes" t)
+                (const :tag "Yes, aggressively." 'aggressively)
+                (const :tag "No" nil)))
 
 (defface eldoc-highlight-function-argument
   '((t (:inherit bold)))
@@ -458,7 +464,8 @@ eldoc--handle-docs
                       (t 1)))
          (things-reported-on)
          (request eldoc--last-request-state)
-         single-doc single-doc-sym)
+         single-doc single-doc-sym
+         (eldoc-buffer-showing (get-buffer-window eldoc--doc-buffer)))
       ;; Then, compose the contents of the `*eldoc*' buffer.
       (with-current-buffer (eldoc-doc-buffer)
         ;; Set doc-buffer's `eldoc--last-request-state', too
@@ -490,6 +497,9 @@ eldoc--handle-docs
       ;; function into some `eldoc-display-functions' special hook.
       (let ((echo-area-message
              (cond
+              ((and eldoc-buffer-showing
+                    (eq eldoc-echo-area-prefer-doc-buffer 'aggressively))
+               nil)
               (;; We handle the `truncate-sym-name-if-fit' special
                ;; case first, by checking if for a lot of special
                ;; conditions.
@@ -519,8 +529,8 @@ eldoc--handle-docs
                   (while (and (not (bobp)) (bolp)) (goto-char (line-end-position 0)))
                   finally
                   (unless (and truncated
-                               eldoc-prefer-doc-buffer
-                               (get-buffer-window eldoc--doc-buffer))
+                               (eq eldoc-echo-area-prefer-doc-buffer t)
+                               eldoc-buffer-showing)
                     (cl-return
                      (concat
                       (buffer-substring (point-min) (point))

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

From: Felician Nemeth <felician.nemeth <at> gmail.com>
To: João Távora <joaotavora <at> gmail.com>
Cc: Yuan Fu <casouri <at> gmail.com>, 42532 <at> debbugs.gnu.org
Subject: Re: bug#42532: 28.0.50;
 Can eldoc-prefer-doc-buffer be more aggressive?
Date: Sat, 26 Sep 2020 14:58:24 +0200

[Message part 1 (text/plain, inline)]

>> Regardless, I think it's reasonable to add a third possible value 
>> for eldoc-prefer-doc-buffer (which should really be renamed 
>> eldoc-echo-area-prefer-doc-buffer).  The value could be the symbol
>> 'aggressive or 'aggressively.  Then it would behave as you propose:
>> if the ElDoc doc buffer is showing, the echo area display code is 
>> a noop.
>>
>> What do you think?
>
> Instead of an abstract idea, here's an actual patch you can try on top
> of the current eldoc.el
> [...]

Thank you.  I've finally tried the patch out with different settings of
eldoc-echo-area-prefer-doc-buffer and eldoc-echo-area-use-multiline-p.
It works as I wished when eldoc-echo-area-prefer-doc-buffer is
'aggressively.  And it works in line with the documentation in most
cases.  However, if I understand the documentation correctly, it doesn't
work as intended with

   (setq eldoc-echo-area-use-multiline-p nil)
   (setq eldoc-echo-area-prefer-doc-buffer t)

For example, with the attached file, moving the point right after "emacs
-Q --load ./bug.el" displays the truncated documentation in the echo
area, but it shouldn't.

[bug.el (#("application/emacs-lisp", attachment)]

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

From: João Távora <joaotavora <at> gmail.com>
To: Felician Nemeth <felician.nemeth <at> gmail.com>
Cc: Yuan Fu <casouri <at> gmail.com>, 42532 <at> debbugs.gnu.org
Subject: Re: bug#42532: 28.0.50; Can eldoc-prefer-doc-buffer be more
 aggressive?
Date: Sat, 03 Oct 2020 20:18:59 +0100

Felician Nemeth <felician.nemeth <at> gmail.com> writes:

> For example, with the attached file, moving the point right after "emacs
> -Q --load ./bug.el" displays the truncated documentation in the echo
> area, but it shouldn't.

Hello Felicián,

I pushed an alternate version of this patch to the branch
scratch/eldoc-display-functions

To git.sv.gnu.org:/srv/git/emacs.git
 * [new branch]            scratch/eldoc-display-functions -> scratch/eldoc-display-functions

It contains more than just this patch, but notably it passes your test,
I think.  Can you try it out?  A point of mention is that the value `t'
is now what `aggressive' used to be.  This is more straightfoward and
much simplified  docstring writing the docstring.  If you want the old
"only prefer if truncated" behaviour, set it to `maybe' (maybe that name
can be reviewed).

Best regards,
João

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

From: Felician Nemeth <felician.nemeth <at> gmail.com>
To: João Távora <joaotavora <at> gmail.com>
Cc: Yuan Fu <casouri <at> gmail.com>, 42532 <at> debbugs.gnu.org
Subject: Re: bug#42532: 28.0.50;
 Can eldoc-prefer-doc-buffer be more aggressive?
Date: Fri, 15 Jan 2021 19:00:19 +0100

I'm sorry I haven't replied earlier.  I've now tested the master branch
instead of scratch/eldoc-display-functions because the master branch
seems to contain most commits from the feature branch.  And it passes
all my tests regarding this bug report.  So I think it can be closed.

Thank you.

João Távora <joaotavora <at> gmail.com> writes:

> Felician Nemeth <felician.nemeth <at> gmail.com> writes:
>
>> For example, with the attached file, moving the point right after "emacs
>> -Q --load ./bug.el" displays the truncated documentation in the echo
>> area, but it shouldn't.
>
> Hello Felicián,
>
> I pushed an alternate version of this patch to the branch
> scratch/eldoc-display-functions
>
> To git.sv.gnu.org:/srv/git/emacs.git
>  * [new branch]            scratch/eldoc-display-functions -> scratch/eldoc-display-functions
>
> It contains more than just this patch, but notably it passes your test,
> I think.  Can you try it out?  A point of mention is that the value `t'
> is now what `aggressive' used to be.  This is more straightfoward and
> much simplified  docstring writing the docstring.  If you want the old
> "only prefer if truncated" behaviour, set it to `maybe' (maybe that name
> can be reviewed).
>
> Best regards,
> João

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

From: João Távora <joaotavora <at> gmail.com>
To: Felician Nemeth <felician.nemeth <at> gmail.com>
Cc: 42532-done <at> debbugs.gnu.org, Yuan Fu <casouri <at> gmail.com>
Subject: Re: bug#42532: 28.0.50;
 Can eldoc-prefer-doc-buffer be more aggressive?
Date: Fri, 15 Jan 2021 18:01:23 +0000

That's great! Closing.

On Fri, Jan 15, 2021 at 6:00 PM Felician Nemeth
<felician.nemeth <at> gmail.com> wrote:
>
> I'm sorry I haven't replied earlier.  I've now tested the master branch
> instead of scratch/eldoc-display-functions because the master branch
> seems to contain most commits from the feature branch.  And it passes
> all my tests regarding this bug report.  So I think it can be closed.
>
> Thank you.

Previous Next

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