bug#44885: 28.0.50; [PATCH] ElDoc buffer mode and separator

[João Távora]

Andrii Kolomoiets <andreyk.mad@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