GNU bug report logs - #47109
eldoc.el: Allow custom separator between documentations in the echo area

Previous Next

To reply to this bug, email your comments to 47109 AT debbugs.gnu.org.

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

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

From: Mathieu Marques <mathieumarques78 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: eldoc.el: Allow custom separator between documentations in the echo
 area
Date: Fri, 12 Mar 2021 20:10:17 +0100

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

Hello,

While trying out eglot.el, I played around with eldoc.el and needed to
display all pieces of documentations in the echo area at once. The joined
patch allows for a custom separator between said documentations.

First patch is a fix to indenting levels as well as untabifying the whole
file. That was done automatically by my configuration and given the
existing code I thought it would be beneficial to most to provide a patch
for that as well. Feel free to dismiss it if needed.

The second patch is the subject of this very email. With the updated code,
in the user configuration, one can customize the separator to `"\n"` and
its face to `((t :inherit shadow :strike-through t))` in order to have a
horizontal line between documentations in the echo area for instance.

I've tried following conventions described over at gnu.org, do let me know
if I've missed anything.

Best regards

-- 
Mathieu Marques

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

[0001-lisp-emacs-lisp-eldoc.el-Untabify-and-fix-indent-lev.patch (text/x-patch, attachment)]

[0002-lisp-emacs-lisp-eldoc.el-Allow-custom-separator.patch (text/x-patch, attachment)]

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Mathieu Marques <mathieumarques78 <at> gmail.com>
Cc: João Távora <joaotavora <at> gmail.com>,
 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Fri, 12 Mar 2021 21:13:51 +0000

severity 47109 wishlist
tags 47109 patch
quit

Mathieu Marques <mathieumarques78 <at> gmail.com> writes:

> While trying out eglot.el, I played around with eldoc.el and needed to
> display all pieces of documentations in the echo area at once. The
> joined patch allows for a custom separator between said
> documentations.

Thanks, CCing João as an expert on both packages.

> First patch is a fix to indenting levels as well as untabifying the
> whole file. That was done automatically by my configuration and given
> the existing code I thought it would be beneficial to most to provide
> a patch for that as well. Feel free to dismiss it if needed.

Indeed, the Emacs convention is to only make whitespace/formatting
changes when already modifying that code for other purposes.

> Subject: [PATCH 2/2] * lisp/emacs-lisp/eldoc.el (eldoc--format-doc-buffer):
>  Allow custom separator

The log message should also mention the new symbols being added, e.g.:

  Make ElDoc separator customizable

  * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
  New user option (bug#47109).
  (eldoc-documentation-separator): New face.
  (eldoc--format-doc-buffer): Use them as a custom separator.

> +(defcustom eldoc-documentation-separator ""
> +  "Separator to use between each documentation thing, when multiple."
> +  :type 'string)
> +
> +(defface eldoc-documentation-separator '((t (:extend t :inherit shadow)))

According to (info "(elisp) Defining Faces"), this syntax is supported
for backward compatibility; nowadays the preferred format is:

  '((t :inherit shadow :extend t))

But: ElDoc supports Emacs ≥ 26.3, so use of the newer :extend attribute
has to be conditional on that, e.g.:

  `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))

> +  "Face to use for the separator between documentation things.")

Both the defcustom and the defface also need a :version tag.

Thanks,

-- 
Basil

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

From: Mathieu Marques <mathieumarques78 <at> gmail.com>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: João Távora <joaotavora <at> gmail.com>,
 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Sat, 13 Mar 2021 13:26:56 +0100

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

Thanks for the feedback. Joined a replacement for 2nd patch following the
suggested improvements.

On Fri, Mar 12, 2021 at 10:13 PM Basil L. Contovounesios <contovob <at> tcd.ie>
wrote:

> severity 47109 wishlist
> tags 47109 patch
> quit
>
> Mathieu Marques <mathieumarques78 <at> gmail.com> writes:
>
> > While trying out eglot.el, I played around with eldoc.el and needed to
> > display all pieces of documentations in the echo area at once. The
> > joined patch allows for a custom separator between said
> > documentations.
>
> Thanks, CCing João as an expert on both packages.
>
> > First patch is a fix to indenting levels as well as untabifying the
> > whole file. That was done automatically by my configuration and given
> > the existing code I thought it would be beneficial to most to provide
> > a patch for that as well. Feel free to dismiss it if needed.
>
> Indeed, the Emacs convention is to only make whitespace/formatting
> changes when already modifying that code for other purposes.
>
> > Subject: [PATCH 2/2] * lisp/emacs-lisp/eldoc.el
> (eldoc--format-doc-buffer):
> >  Allow custom separator
>
> The log message should also mention the new symbols being added, e.g.:
>
>   Make ElDoc separator customizable
>
>   * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
>   New user option (bug#47109).
>   (eldoc-documentation-separator): New face.
>   (eldoc--format-doc-buffer): Use them as a custom separator.
>
> > +(defcustom eldoc-documentation-separator ""
> > +  "Separator to use between each documentation thing, when multiple."
> > +  :type 'string)
> > +
> > +(defface eldoc-documentation-separator '((t (:extend t :inherit
> shadow)))
>
> According to (info "(elisp) Defining Faces"), this syntax is supported
> for backward compatibility; nowadays the preferred format is:
>
>   '((t :inherit shadow :extend t))
>
> But: ElDoc supports Emacs ≥ 26.3, so use of the newer :extend attribute
> has to be conditional on that, e.g.:
>
>   `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))
>
> > +  "Face to use for the separator between documentation things.")
>
> Both the defcustom and the defface also need a :version tag.
>
> Thanks,
>
> --
> Basil
>


-- 
Mathieu Marques

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

[0002-Make-ElDoc-separator-customizable.patch (text/x-patch, attachment)]

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Mathieu Marques <mathieumarques78 <at> gmail.com>
Cc: João Távora <joaotavora <at> gmail.com>,
 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Sat, 13 Mar 2021 14:02:11 +0000

Mathieu Marques <mathieumarques78 <at> gmail.com> writes:

> Thanks for the feedback. Joined a replacement for 2nd patch following
> the suggested improvements.

LGTM, thanks,

-- 
Basil

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

From: João Távora <joaotavora <at> gmail.com>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: Mathieu Marques <mathieumarques78 <at> gmail.com>, 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Sat, 13 Mar 2021 14:35:38 +0000

Thank you both,

Personally, I'm fine with the first whitespace patch, as long as it's
only whitespace.

I've had a look at the simple second patch and while such a thing is
indeed mostly innocuous (and potentially very useful), I wonder if we
shouldn't be a bit more ambitious.

There are bound to be many more sophisticated strategies for composing
items of documentation and it doesn't make sense, to me, for Eldoc to
add two new user-visible endpoints to what is already a long,
ad-hoc-tailored list of legacy endpoints just for the relatively limited
technique of "composition by concatenation".

For example, in elisp-mode, one plan could be have the composition of
the multiple documentation items collected by the elisp eldoc backends
resultin a documentation buffer that looks very much like what you get
from describe-symbol or C-h o in form, function and content.  That
potentially needs a much more sophisticated composition strategy that is
specific to the elisp-mode major mode.

So I'd argue for a a new eldoc-render-documentation function.

That should give the user enough freedom to do these basic separators
but doesn't bloat the API with limited micro-switches (at least not yet,
we can add such things in the main eldoc.el eventually).

eldoc-render-documentation could be a generic function given:

- the items of documentation to render

- the target "canvas", which may be a buffer (the eldoc buffer), the echo
  area, or some other object (a tooltip? some user-defined documentation
  container?)

It should output things in a buffer, or maybe a string.

There seems be bit of an overlap here with `eldoc-display-functions',
but it is rather a healthy relation, in my view.  Those functions should
be more concerned with managing access and visibility of the target
canvas than actually rendering the text, which may be specific to a
major-mode and a potentially orthogonal task.

So each element in `eldoc-display-functions` should call
`eldoc-render-documentation` passing it suitable arguments to produce
the final text.

João

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

From: Mathieu Marques <mathieumarques78 <at> gmail.com>
To: João Távora <joaotavora <at> gmail.com>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>, 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Thu, 18 Mar 2021 19:30:12 +0100

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

 Hello again,

Thanks for the feedback.  I agree with the will of allowing more freedom.

I joined a replacement patch with the different route that this is now
taking,
namely the removal of `eldoc--format-doc-buffer' in favor of
`eldoc-render-documentation'.  Is that closer to what you had in mind?

There's an issue however with the `-hr` format function that won't work with
terminal-based Emacs due to `:strike-through` apparently not supported
there.  I
was wondering whether a simple mention of that limitation in the docstring
would
be enough?  Terminal-based users would still be able to use the default
format
function.  Regarding the `:extend` keyword not being supported on 26, I
think
a better way than conditionally add it would be to provide a second `-hr`
formatting function that relies on something that is supported on 26 ie.
overlay.  Although I have little to no experience with overlays so I'm not
sure
what would be the preferred way of making a horizontal divider.
Furthermore, it
shouldn't break when the render function is used to return a string.
-- 
Mathieu Marques

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

[0002-Add-a-responsible-Eldoc-render-to-target-function.patch (text/x-patch, attachment)]

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mathieu Marques <mathieumarques78 <at> gmail.com>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>,
 João Távora <joaotavora <at> gmail.com>, 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Mon, 17 May 2021 17:37:58 +0200

I have no comment on this patch, but I note that bug#44885 seems to deal
with similar issues (i.e., custom eldoc separators, if I skimmed that
bug report correctly).  

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

Message #30 received at 47109 <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>,
 Mathieu Marques <mathieumarques78 <at> gmail.com>, 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Mon, 17 May 2021 16:44:57 +0100

Thanks for the ping, Lars.  I will read that bug, too.    I hope to
propose my own patch to solve this problem in the not so distant
future.

To be clear, I'm just slightly wary of introducing this patch, a limited
way to solve this, if that means we would have to provide backward
compatibility for it in case we want to move to a more robust system
later on. Thing is, as far as I understand it, between two Emacs
releases (i.e. in trunk) we're generally not obliged to provide this
backward compatibility.  But Eldoc is also distributed independently
in ELPA releases, directly from trunk, and that may change things
a bit.  So erring on the side of caution here.  Feel free to comment
on the policy followed here.

João

On Mon, May 17, 2021 at 4:38 PM Lars Ingebrigtsen <larsi <at> gnus.org> wrote:
>
> I have no comment on this patch, but I note that bug#44885 seems to deal
> with similar issues (i.e., custom eldoc separators, if I skimmed that
> bug report correctly).
>
> --
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no
>


-- 
João Távora

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: João Távora <joaotavora <at> gmail.com>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>,
 Mathieu Marques <mathieumarques78 <at> gmail.com>, 47109 <at> debbugs.gnu.org
Subject: Re: bug#47109: eldoc.el: Allow custom separator between
 documentations in the echo area
Date: Tue, 18 May 2021 15:39:56 +0200

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

> Thanks for the ping, Lars.  I will read that bug, too.    I hope to
> propose my own patch to solve this problem in the not so distant
> future.
>
> To be clear, I'm just slightly wary of introducing this patch, a limited
> way to solve this, if that means we would have to provide backward
> compatibility for it in case we want to move to a more robust system
> later on. Thing is, as far as I understand it, between two Emacs
> releases (i.e. in trunk) we're generally not obliged to provide this
> backward compatibility.  But Eldoc is also distributed independently
> in ELPA releases, directly from trunk, and that may change things
> a bit.  So erring on the side of caution here.  Feel free to comment
> on the policy followed here.

Yeah, I understand the worries here -- especially since eldoc is such a
central feature in Emacs.

So waiting while you develop a more thorough solution here is fine by me.

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

Previous Next

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