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

[martin rudalics <rudalics@gmx.at>]

 > * 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.

Let's disagree on the backward incompatibility issue.  As a rule, Emacs
changes have always tried to not alter the signatures of functions in a
way that makes previously written calls invalid but I'm not very eager
to argue about that.

For me the sad fact remains that I will now have to change all these
calls on my 50-some Winchester and USB partitions where I have Emacs
installed, whenever I plug in or reactivate any of them and the
respective error message pops up rendering the actual session invalid.

Something you could have avoided by keeping a clean separation of the
old behavior of 'eldoc-documentation-function' on the one side and the
new behavior of 'eldoc-documentation-functions' on the other.  Please
everybody keep in mind for future changes to avoid introducing such
incompatible behavior.  If there is a function definition and that
function is not clearly marked as internal (via the usual two slashes),
please keep the signature and the semantics intact so users can rely on
it behaving as intended until that function has been declared obsolete
for a sufficient long time.

 > 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.

I still have to make the change in all copies of my library I intend to
run.  While this may look like a minor issue to you, it would make Emacs
in the long term unusable for me, if such changes were introduced on a
regular basis.

 > 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

Since I don't use any package archives and do not require them, this is
not a practical option for me.

 > 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.

Thanks, martin