bug#62029: 29.0.60; Allow users to customize eldoc buffer separator

[João Távora]

On Sat, Mar 25, 2023 at 3:05 AM Yuan Fu <casouri@gmail.com> wrote:
>
>
>
> > On Mar 24, 2023, at 10:44 AM, João Távora <joaotavora@gmail.com> wrote:
> >
> > Yuan Fu <casouri@gmail.com> writes:
> >
> >> For separator, maybe something like
> >>
> >> (insert “Title" (propertize "-" 'display
> >>                             '(space :align-to right)
> >>                             'font-lock-face '(:strike-through t)
> >>                             'face '(:strike-through t)))
> >>
> >> for GUI, and use underline for terminal.
> >
> > I've now pushed a commit to master introducing the user variable
> > eldoc-doc-buffer-separator.  It's not a defcustom yet, as I'm not too
> > familiar with those, but feel free to change it.
> >
> >  (defvar eldoc-doc-buffer-separator
> >    "String used to separate items in Eldoc documentation buffer."
> >    (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend 
> > t)) "\n"))
> >
> > There is a difference between a separator and a title.  I've stopped
> > short of adding titles, as I fear it would be confusing unless the
> > content allows it.  To be investigated later for
> > eldoc-display-in-echo-area or maybe you can try it in eldoc-box.
> >
> > Also, I've been testing with these unpushed changes to elisp-mode.el,
> > which render more of the docstring in emacs-lisp-mode.
> >
> > The use case here is navigating around in an .el file while having a
> > window open with the *eldoc* buffer.
> >
> > João
>
> Looks good to me (except for the “documentatiok” ;-) eldoc-box can also 
> benefit from this (right now if you use it in emacs-lisp-mode, it just shows 
> a thin strip of text, not very exciting).
>
> I’ll experiment with the title thing in eldoc-box. Does eglot and flymake 
> already pass a :source cookie? Those two displaying stuff together is the 
> most possible case I can think of.


> it just shows a thin strip of text, not very exciting).

Indeed.  I'll present my patch soon in emacs-devel.
There's one thing I don't like about it which is that
is re-does a lot of complicated parsing for both *Help*
and *eldoc* forms.  Could be slow, or could be meaningless.
Another aspect is that function documentation looks great
because there is this nifty describe-function-1 helper, but
variable documentation looks poor because there is
no such thing.

> Does eglot and flymake already pass a :source cookie?

You mean ':origin', not ':source'.  Though the latter name is
acceptable and there's plently of time to change to it if you
think it's better or more consistent with other parts of Emacs.

Yes they do.  This cookie is automatic.  Maybe I should state that
in the documentatiok.

> Those two displaying stuff together is the most possible case
> I can think of.

In Eglot it's very usual to have three sources, and in Emacs
Lisp you can also have three (function, variable and flymake).

You do need to set eldoc-documentation-strategy to
eldoc-documentation-compose though (this should really
be the default).

João