bug#43609: 28.0.50; eldoc-documentation-function [vs new eldoc-display-functions]

[João Távora]

Hi martin,

Sorry for taking so long to reply.  I've been busy.

martin rudalics <rudalics@gmx.at> writes:

> Meanwhile, please provide the compatibility layer you earlier promised
> with
>
>   But if you really insist , it's a very easy function to bring back I
>   would say (in fact the function I gave you earlier is probably more
>   useful generalization of it).
>
> so we can close this bug.
>
> Ideally, this would render your earlier changes backward-compatible and
> make the obsoletion declaration for 'eldoc-documentation-function' clean
> and follow our usual practice.

As I explained, this is impossible. Let's recap:

* eldoc-documentation-function is a variable exposed by eldoc.el meant
  to be set, not called, by libraries.  Many libraries set it in a way
  that, when called without the proper context from within eldoc.el's
  internals, it doesn't make any sense.  Such libaries are long-standing
  such as SLIME, Elpy, etc, and have existed for a long time.  So,
  because your use case wasn't ever a valid use of that variable to
  begin with, I don't see the case for any backward-iccompatibility
  claim.

* As I said, it's possible to write a eldoc-get-me-the-string function
  (not a variable) with the semantics that you want.  This is what I
  meant by "if you insist".  By that I meant there would have to be good
  reason for it.  But is there?  The use case you gave me was cleanly
  solved by relying on eldoc-display-functions, a feature which I'll
  push very shortly to master.  So, while this _can_ be done, I don't
  think it's a priority, because there's no clear use case for it.

> The downside of this approach is obviously that we would have to keep
> the old definitions of 'elisp-eldoc-documentation-function' and its
> colleagues around for a while.  So if you think that removing these old
> definitions immediately is crucial for future development, please
> provide some substitute function and mention it in the doc-string of
> 'eldoc-documentation-function(s)'.

Let's say eldoc-get-me-the-string function is written: then there is no
need to bring back these definitions.  Your library calls
eldoc-get-me-the-string if it finds it (which it presumably will in
Emacs 28), and (brokenly) calls eldoc-documentation-function in other
Emacs versions.  In Emacs 28 your library will work OK will all
documentation producers and in Emacs <= 27 it will not, but it will work
with Elisp and C++ which appear to be your priorities.

But, again, is the previous exercise really needed?  I very much doubt
it. You asked, and I provided, a modificaiton of your library so that it
works in Emacs 28 _without_ this hypothetical eldoc-get-me-the-string.
I showed you that all that is needed is a new element in
eldoc-display-functions.  If you want to make that library (again,
brokenly) compatible to Emacs <= 27, you must merely check the version
and use the previous technique.  Surely you can make that happen
yourself, it's a simple "if" statement.

But a much better alternative, in my opinion, is to use the code I gave
you and create a robust package that works correctly in Emacs >= 26.3.
How?  You make use of the fact the latest ElDoc in master is now _also_
available in GNU ELPA and you install that..  This means that even in
Emacs 26.3 you can use your tooltip thing for Elisp and C++ and so would
other people, for those modes and many others.

As to the implementation of this solution, it's a simple case of adding
this line:

;; Package-Requires: ((emacs "26.3") (eldoc "1.xx.0"))

to the martin-tooltip.el file I gave you earlier, and then using the
package.el system to package it.  Alternatively, if you don't want to
make a package, just 'M-x package-install eldoc' in Emacs >= 26.3 should
bring in the latest eldoc.

xx is the version of eldoc that will contain the new
eldoc-display-functions development.

Best regards,
João