GNU bug report logs - #44885
28.0.50; [PATCH] ElDoc buffer mode and separator

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 44885 in the body.
You can then email your comments to 44885 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: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Thu, 26 Nov 2020 14:42:47 +0200

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

Hi,

Patch attached.

The configurable separator will make it possible to show multiple docs
in user pleasant way.

The mode will allow tweak ElDoc doc buffer appearance by adding hooks.

With little customization and custom display function in
display-buffer-alist 'M-x eldoc-doc-buffer' can show the ElDoc buffer
like some kind of tooltip.  See attached screenshot.

Thanks!

[0001-ElDoc-buffer-mode-and-separator.patch (text/x-patch, attachment)]

[eldoc.png (image/png, attachment)]

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

From: João Távora <joaotavora <at> gmail.com>
To: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
Cc: 44885 <at> debbugs.gnu.org
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Sat, 28 Nov 2020 23:54:36 +0000

Andrii Kolomoiets <andreyk.mad <at> gmail.com> writes:

> Hi,
>
> Patch attached.
>
> The configurable separator will make it possible to show multiple docs
> in user pleasant way.

Thanks. The patch looks generally good but it has an important flaw that
can be fixed. See comments below.

> The mode will allow tweak ElDoc doc buffer appearance by adding hooks.

Yes.  I also have some ideas about how to sophisticate this buffer.

One of them involves having some backends, like the Elisp backends,
transmit a special key on the side -- much like :thing or :face -- that
specifies a function that fills in the whole buffer.  Thus, M-x eldoc in
a symbol of the Elisp buffer could eventually format this Eldoc doc
buffer much in the same way that currently M-x describe-symbol does.

And thus the Elisp disconnect between M-x eldoc and M-x describe-* would
be bridged.

The only incompatibility I see between my idea and your current proposal
is the major mode that you picked for the Eldoc doc buffer.  I wonder if
you could make it inherit from Help mode?  Then it would glue better
with my idea.

> With little customization and custom display function in
> display-buffer-alist 'M-x eldoc-doc-buffer' can show the ElDoc buffer
> like some kind of tooltip.

Very interesting. Can you share the display-buffer-alist hack that
allowed you to do this?  I didn't think about the possibility of
tweaking it like this, but it's certainly "legal".  I wonder if you
cann't do the same by adding a different function to
eldoc-display-functions, which was how I intented it to work.

> +(defvar eldoc-doc-mode-map
> +  (let ((map (make-sparse-keymap)))
> +    (suppress-keymap map)
> +    (define-key map "q" 'quit-window)
> +    (define-key map " " 'scroll-up-command)
> +    (define-key map [?\S-\ ] 'scroll-down-command)
> +    (define-key map "\C-?" 'scroll-down-command)
> +    (define-key map "?" 'describe-mode)
> +    (define-key map "h" 'describe-mode)
> +    (define-key map ">" 'end-of-buffer)
> +    (define-key map "<" 'beginning-of-buffer)
> +    map)
> +  "Keymap used in ElDoc documentation buffer.")
> +
> +(define-derived-mode eldoc-doc-mode fundamental-mode "ElDoc doc"
> +  "Major mode for ElDoc documentation buffer."
> +  (setq buffer-read-only t))

As I said above, I wonder if inheriting from help-mode wouldn't give us
most of this for free.  Maybe it would bring us _too much_ though...  So
some inheritance snipping would be needed.

>                   do (insert this-doc)
> -                 when rest do (insert "\n")
> +                 when rest do (insert eldoc-doc-buffer-separator)

I like this and I like the separator, however, notice that the current
implementation of the eldoc-display-in-echo-area also uses this buffer
as an implementation detail.  So this would break eldoc-display-in-echo
area.

The solution would be for eldoc-display-in-echo-area to use its own
"hidden" buffer and then eldoc-display-in-buffer would be free to format
the buffer as it sees fit.

So you could extract the buffer-formatting code to a common helper, use
it in eldoc-display-in-echo-area with a "\n" separator and in
eldoc-display-in-buffer with an arbitrary user-chosen separator.  The
performance hit of formatting two buffers would likely be negligible.

João

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
Cc: 44885 <at> debbugs.gnu.org, joaotavora <at> gmail.com
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Sun, 29 Nov 2020 13:02:25 +0000

Andrii Kolomoiets <andreyk.mad <at> gmail.com> writes:

> * lisp/emacs-lisp/eldoc.el (eldoc-doc-buffer-separator): New option.

Does this need calling out in etc/NEWS?

> +    (define-key map [?\S-\ ] 'scroll-down-command)

Nit: please prefer '\s' over '\ '.

> +(define-derived-mode eldoc-doc-mode fundamental-mode "ElDoc doc"
> +  "Major mode for ElDoc documentation buffer."

If it's the major mode for the ElDoc buffer, why not call it
eldoc-buffer-mode so as to avoid the repetition/ambiguity of "doc"?

> +  (setq buffer-read-only t))
> +
>  (defun eldoc--format-doc-buffer (docs)
>    "Ensure DOCS are displayed in an *eldoc* buffer."
>    (interactive (list t))
> @@ -472,12 +495,13 @@ eldoc--format-doc-buffer
>                             eldoc--doc-buffer
>                           (setq eldoc--doc-buffer
>                                 (get-buffer-create " *eldoc*")))
> +    (unless (eq major-mode 'eldoc-doc-mode)

Why not derived-mode-p?

Thanks,

-- 
Basil

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

From: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
To: João Távora <joaotavora <at> gmail.com>
Cc: 44885 <at> debbugs.gnu.org
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Thu, 03 Dec 2020 11:25:33 +0200

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

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

> The only incompatibility I see between my idea and your current proposal
> is the major mode that you picked for the Eldoc doc buffer.  I wonder if
> you could make it inherit from Help mode?  Then it would glue better
> with my idea.

Sure.

>> +(define-derived-mode eldoc-doc-mode fundamental-mode "ElDoc doc"
>> +  "Major mode for ElDoc documentation buffer."
>> +  (setq buffer-read-only t))
>
> As I said above, I wonder if inheriting from help-mode wouldn't give us
> most of this for free.  Maybe it would bring us _too much_ though...

The only reason I didn't inherit from `special-mode` is to avoid binding
the `g` key to the `revert-buffer` function.

> So some inheritance snipping would be needed.

OK, will do.

>> With little customization and custom display function in
>> display-buffer-alist 'M-x eldoc-doc-buffer' can show the ElDoc buffer
>> like some kind of tooltip.
>
> Very interesting. Can you share the display-buffer-alist hack that
> allowed you to do this?  I didn't think about the possibility of
> tweaking it like this, but it's certainly "legal".

See attached eldoc-frame.el.
In emacs -Q:
1. M-x load-file eldoc-frame.el
2. Type "(setq" and wait a bit for eldoc message to appear in the echo
   area
3. C-c h

> I wonder if you cann't do the same by adding a different function to
> eldoc-display-functions, which was how I intented it to work.

This will work even better.  This way the "tooltip" can fit to content
as soon as new docs will be shown.

>>                   do (insert this-doc)
>> -                 when rest do (insert "\n")
>> +                 when rest do (insert eldoc-doc-buffer-separator)
>
> I like this and I like the separator, however, notice that the current
> implementation of the eldoc-display-in-echo-area also uses this buffer
> as an implementation detail.  So this would break eldoc-display-in-echo
> area.

I was hoping it would look like an enhancement -- eldoc-separator
everywhere! :)

> The solution would be for eldoc-display-in-echo-area to use its own
> "hidden" buffer and then eldoc-display-in-buffer would be free to format
> the buffer as it sees fit.
>
> So you could extract the buffer-formatting code to a common helper, use
> it in eldoc-display-in-echo-area with a "\n" separator and in
> eldoc-display-in-buffer with an arbitrary user-chosen separator.  The
> performance hit of formatting two buffers would likely be negligible.

OK, will do.

[eldoc-frame.el (application/emacs-lisp, attachment)]

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

From: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 44885 <at> debbugs.gnu.org, joaotavora <at> gmail.com
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Thu, 03 Dec 2020 12:29:05 +0200

"Basil L. Contovounesios" <contovob <at> tcd.ie> writes:

>> * lisp/emacs-lisp/eldoc.el (eldoc-doc-buffer-separator): New option.
>
> Does this need calling out in etc/NEWS?

Sure.  But I left it for later, when the patch will be ready.

>> +    (define-key map [?\S-\ ] 'scroll-down-command)
>
> Nit: please prefer '\s' over '\ '.

This is copy-paste from the `special-mode-map` and will be removed once
eldoc-buffer mode will be derived from special-mode.

>> +(define-derived-mode eldoc-doc-mode fundamental-mode "ElDoc doc"
>> +  "Major mode for ElDoc documentation buffer."
>
> If it's the major mode for the ElDoc buffer, why not call it
> eldoc-buffer-mode so as to avoid the repetition/ambiguity of "doc"?

Indeed.  I think I was confused by the `eldoc-doc-buffer` command name.

>> +  (setq buffer-read-only t))
>> +
>>  (defun eldoc--format-doc-buffer (docs)
>>    "Ensure DOCS are displayed in an *eldoc* buffer."
>>    (interactive (list t))
>> @@ -472,12 +495,13 @@ eldoc--format-doc-buffer
>>                             eldoc--doc-buffer
>>                           (setq eldoc--doc-buffer
>>                                 (get-buffer-create " *eldoc*")))
>> +    (unless (eq major-mode 'eldoc-doc-mode)
>
> Why not derived-mode-p?

You are right.  Will fix.

Thanks!

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

From: Felician Nemeth <felician.nemeth <at> gmail.com>
To: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>, 44885 <at> debbugs.gnu.org,
 joaotavora <at> gmail.com
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Mon, 25 Jan 2021 15:19:29 +0100

I'm late to the game, but I think this new mode should be derived from
view-mode instead of fundamental-mode.  It would make the code cleaner
too.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>, 44885 <at> debbugs.gnu.org,
 joaotavora <at> gmail.com
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Wed, 08 Sep 2021 11:44:00 +0200

Andrii Kolomoiets <andreyk.mad <at> gmail.com> writes:

>>> +    (unless (eq major-mode 'eldoc-doc-mode)
>>
>> Why not derived-mode-p?
>
> You are right.  Will fix.

This was over half a year ago, but there was no follow-up to this (and
it seemed like everybody agreed that this was a good feature).  Andrii,
did you continue working on this patch?

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

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

From: João Távora <joaotavora <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>, 44885 <at> debbugs.gnu.org,
 Andrii Kolomoiets <andreyk.mad <at> gmail.com>
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Wed, 8 Sep 2021 10:46:38 +0100

This needs more design I think.  If Andrii doesn't, I'll try to look at
it again soon, as it's kind of on my list of things to go into master
before 28 is cut.

João

On Wed, Sep 8, 2021 at 10:44 AM Lars Ingebrigtsen <larsi <at> gnus.org> wrote:
>
> Andrii Kolomoiets <andreyk.mad <at> gmail.com> writes:
>
> >>> +    (unless (eq major-mode 'eldoc-doc-mode)
> >>
> >> Why not derived-mode-p?
> >
> > You are right.  Will fix.
>
> This was over half a year ago, but there was no follow-up to this (and
> it seemed like everybody agreed that this was a good feature).  Andrii,
> did you continue working on this patch?
>
> --
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no



-- 
João Távora

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

From: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
To: João Távora <joaotavora <at> gmail.com>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>,
 Lars Ingebrigtsen <larsi <at> gnus.org>, 44885 <at> debbugs.gnu.org
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Wed, 08 Sep 2021 21:56:17 +0300

Lars, I didn't have time to continue working on this patch.

João, please feel free to make your own implementation or to modify this
patch.  Let me know if I can help you with anything.

Thanks! And sorry for delay with the patch.


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

> This needs more design I think.  If Andrii doesn't, I'll try to look at
> it again soon, as it's kind of on my list of things to go into master
> before 28 is cut.
>
> João
>
> On Wed, Sep 8, 2021 at 10:44 AM Lars Ingebrigtsen <larsi <at> gnus.org> wrote:
>>
>> Andrii Kolomoiets <andreyk.mad <at> gmail.com> writes:
>>
>> >>> +    (unless (eq major-mode 'eldoc-doc-mode)
>> >>
>> >> Why not derived-mode-p?
>> >
>> > You are right.  Will fix.
>>
>> This was over half a year ago, but there was no follow-up to this (and
>> it seemed like everybody agreed that this was a good feature).  Andrii,
>> did you continue working on this patch?
>>
>> --
>> (domestic pets only, the antidote for overdose, milk.)
>>    bloggy blog: http://lars.ingebrigtsen.no

-- 
Andrii

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Andrii Kolomoiets <andreyk.mad <at> gmail.com>
Cc: 44885 <at> debbugs.gnu.org, joaotavora <at> gmail.com
Subject: Re: bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator
Date: Sun, 11 Sep 2022 13:33:27 +0200

Andrii Kolomoiets <andreyk.mad <at> gmail.com> writes:

> +(defvar eldoc-doc-mode-map
> +  (let ((map (make-sparse-keymap)))
> +    (suppress-keymap map)

This was fixed in 97abe8511a by just using `special-mode' in this buffer
instead.

Previous Next

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