From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#43609: 28.0.50; eldoc-documentation-function [vs new eldoc-display-functions] Date: Sat, 31 Oct 2020 09:01:29 +0100 Message-ID: References: <2e610c3f-6e5f-c7dd-af2e-aeb5e20d8664@gmx.at> <87r1qjjppu.fsf@gmail.com> <3fa6b315-7fc0-06ee-81e9-b68d164aec1b@gmx.at> <87a6x7jf9a.fsf@gmail.com> <874knbi0jc.fsf_-_@gmail.com> <87362tggvl.fsf@gmail.com> <87d01vem7z.fsf@gmail.com> <17da3e99-d4fc-a603-baa3-4180d612af41@gmx.at> <878scie5ti.fsf@gmail.com> <87tuujr6sd.fsf@gmail.com> <803c87c2-7d60-5997-2247-85d3e62e3d2c@gmx.at> <87a6w7puuz.fsf@gmail.com> <64831acc-996e-51d7-ce6f-b667a6334e3c@gmx.at> <87imavo322.fsf@gmail.com> <874kmeofl6.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="36007"; mail-complaints-to="usenet@ciao.gmane.io" Cc: larsi@gnus.org, Yuan Fu , 43609@debbugs.gnu.org To: =?UTF-8?Q?Jo=C3=A3o_?= =?UTF-8?Q?T=C3=A1vora?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Oct 31 09:02:36 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kYlqN-0009EZ-J8 for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 31 Oct 2020 09:02:35 +0100 Original-Received: from localhost ([::1]:54556 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kYlqM-0007L1-CZ for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 31 Oct 2020 04:02:34 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59798) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kYlpq-0007Ka-OW for bug-gnu-emacs@gnu.org; Sat, 31 Oct 2020 04:02:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48937) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kYlpq-0004mK-Eh for bug-gnu-emacs@gnu.org; Sat, 31 Oct 2020 04:02:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kYlpq-00034b-Cf for bug-gnu-emacs@gnu.org; Sat, 31 Oct 2020 04:02:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 31 Oct 2020 08:02:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 43609 X-GNU-PR-Package: emacs Original-Received: via spool by 43609-submit@debbugs.gnu.org id=B43609.160413130011773 (code B ref 43609); Sat, 31 Oct 2020 08:02:02 +0000 Original-Received: (at 43609) by debbugs.gnu.org; 31 Oct 2020 08:01:40 +0000 Original-Received: from localhost ([127.0.0.1]:60482 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kYlpT-00033p-KM for submit@debbugs.gnu.org; Sat, 31 Oct 2020 04:01:40 -0400 Original-Received: from mout.gmx.net ([212.227.15.15]:34649) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kYlpR-00033W-CL for 43609@debbugs.gnu.org; Sat, 31 Oct 2020 04:01:38 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1604131290; bh=3iF+d6VyyApKsG01x4ym6xfRT7sHOI6/VOx9B66uGQA=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=jKZohQzunrpKo0GWGO8H3pzTnOGdGtzqsUBi1J/V+bgPo8yWu//xnvpJuxX5SQq7D V8fd4fMk7KJuVv/c/xnZJXjS3iSzVM/56CK62CGUkfUonqFtRTXson2ynawqK0yxig 4VfWkJLMUojUVUb78d0IR3mflAmSgrYX0KX2FcSc= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [192.168.1.102] ([212.95.7.235]) by mail.gmx.com (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1M1Ygz-1kWq132jcp-0039R1; Sat, 31 Oct 2020 09:01:30 +0100 In-Reply-To: <874kmeofl6.fsf@gmail.com> Content-Language: en-US X-Provags-ID: V03:K1:JhNSP4Xgxalz/xLd+8iaTz59jXGPj5ZyLo9W/I3hwZPQWrqNVDh 6Rg/BhUdqND4FYsmBDpAvv7uTKM1iI66/jnURaulhm1dysoMGxjYnUi3h7dJwvaBEEfHAOB CaE5n8KncGgY10t2+vgV6k9rkqA4nj72AOkLRD5rBjqR3dsE+kVfOG8tR2gYn3mFvdqIQ5e xXWy1UhsdtpREOExpUPpg== X-UI-Out-Filterresults: notjunk:1;V03:K0:+cm2Gg3Auuw=:exfhc2dEQnyAVjeGCGrBd5 JQKwybCR01PeOdPLYeBWa6n/Cbx5DDXYg70KDw8HFk7PTZZYjRWMG0pChPEKFfYK61sa5x/MH ssIE/2cuObBkM3dHhsfZPPMFoivxHMc/7kJAecjq75sjz/mrNy7kcW9T4td5dclNrrWQK69uE LOawKKqtk0akhOE7Fa6tmYP4Tx9TjFXlEPqQ1U0AFAiTEM+PLpsRkUL8dX0zi8MB1G7Fm/w6j L7ZpzqHMoiOquv4yrCIk9ladzIQhokJQJTuYItxw8xNdRMc2penucCaI6gmXkte03wsMaMYYe KCe66JQGuLlkHsZ+ucf/lMvFBJz6ljOh9Xq9hZ4amJgn3Ee/f17165jlUW0F43uHFRGyeZDYG j9PHVJRu1nrmo1wEVOHiXgbtTnZhICIyT4KuYBkkMdshBxBRqrN8qWZ8uscpjVHB/Z2CRGsVx gUJuFOJVop3cKdu7YRM/Zc9xY4/+EoUkfGOMY8/KPILd9C9XIY882tILNINU5ArLLzmjXNEX7 ljw1gbgTBsZCah55LVQfHaTzK8tLe4me96U7MfWZeWAGMTDW/3E+yNpFrt/VBykSGwvZEdRm0 yRRDFzsAMOn1NLZNH0xRyppc2SytqXQaGPu5CNaQXJbyW+s2EVHm7Jjo9OgssrN/pKqxalq7S F1cVzQazF/nPcH/rCRKxF068YNQn0I/YbEroS0zTAr1NYqIX0c1kYbL1YUDgbrjPWWmK+7Gp6 O3ulDbxCzuNo2sNCPq/jvcXYzGSinRz2AfBkZb7cOPBI2Rk3sAR820xjQVEJh16UgUj5c5b6 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:192246 Archived-At: > But changing the _value_ of eldoc-documentation-function (the variable= ) > was _not_ a backward incompatible change And I disagree. (1) Fifteen years ago we had (defvar eldoc-documentation-function nil "If non-nil, function to call to return doc string. The function of no args should return a one-line string for displaying doc about a function etc. appropriate to the context around point. It should return nil if there's no doc appropriate for the context. Typically doc is returned if point is on a function-like name or in its arg list. This variable is expected to be made buffer-local by modes (other than Emacs Lisp mode) that support Eldoc.") (2) Five years ago, that is, at the time I wrote 'eldoc-tooltip-mode' we had (defvar eldoc-documentation-function #'ignore "Function to call to return doc string. The function of no args should return a one-line string for displaying doc about a function etc. appropriate to the context around point. It should return nil if there's no doc appropriate for the context. Typically doc is returned if point is on a function-like name or in its arg list. The result is used as is, so the function must explicitly handle the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p'= , and the face `eldoc-highlight-function-argument', if they are to have any= effect. Major modes should modify this variable using `add-function', for example= : (add-function :before-until (local 'eldoc-documentation-function) #'foo-mode-eldoc-function) so that the global documentation function (i.e. the default value of the variable) is taken into account if the major mode specific function does = not return any documentation.") (3) With commit c0fcbd2c119b8418855f0931aceefbef717c5e53 Author: Mark Oteiza Date: Tue Feb 25 17:53:04 2020 -0500 Expose ElDoc functions in a hook (Bug#28257) the definition became (defcustom eldoc-documentation-function #'eldoc-documentation-default "Function to call to return doc string. The function of no args should return a one-line string for displaying doc about a function etc. appropriate to the context around point. It should return nil if there's no doc appropriate for the context. Typically doc is returned if point is on a function-like name or in its arg list. The result is used as is, so the function must explicitly handle the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p'= , and the face `eldoc-highlight-function-argument', if they are to have any= effect." (4) With current master 'eldoc-documentation-function' is not defined any more but has become an alias in a way I can't fathom. C-h v gets me: eldoc-documentation-function is a variable defined in =E2=80=98eldoc.el=E2= =80=99. Its value is =E2=80=98eldoc-documentation-default=E2=80=99 This variable is an alias for =E2=80=98eldoc-documentation-strategy=E2= =80=99. You can customize this variable. Probably introduced at or before Emacs version 22.1. Documentation: How to collect and organize results of =E2=80=98eldoc-documentation-funct= ions=E2=80=99. This variable controls how =E2=80=98eldoc-documentation-functions=E2=80=99= , which specifies the sources of documentation, is queried and how its results are organized before being displayed to the user. The following values are allowed: - =E2=80=98eldoc-documentation-default=E2=80=99: calls functions in the s= pecial hook in order until one is found that produces a doc string value. Display only that value; - =E2=80=98eldoc-documentation-compose=E2=80=99: calls all functions in t= he special hook and displays all of the resulting doc strings together. Wait for all strings to be ready, and preserve their relative as specified by the order of functions in the hook; - =E2=80=98eldoc-documentation-compose-eagerly=E2=80=99: calls all functi= ons in the special hook and display as many of the resulting doc strings as possible, as soon as possibl. Preserving the relative order of doc strings; - =E2=80=98eldoc-documentation-enthusiast=E2=80=99: calls all functions i= n the special hook and displays only the most important resulting docstring one at any given time. A function appearing first in the special hook is considered more important. This variable can also be set to a function of no args that returns something other than a string or nil and allows for some or all of the special hook =E2=80=98eldoc-documentation-functions=E2=80=99= to be run. In that case, the strategy function should follow that other variable=E2=80=99s protocol closely and endeavor to display the resulting doc strings itself. For backward compatibility to the "old" protocol, this variable can also be set to a function that returns nil or a doc string, depending whether or not there is documentation to display at all. Note here the "can also be set to a function of no args that returns something other than a string or nil" and "For backward compatibility to the \"old\" protocol, this variable can also be set to a function that returns nil or a doc string": The former implies that returning a string or nil is the expected behavior. The latter implies that returning a string or nil is the exception. What makes (4) backward incompatible is that "should return a one-line string" is no more mentioned in the doc-string. Consequently, modes defining their support functions do not have to support this part of the original specification any more. In the sequel changes were installed that, for example, have the corresponding function in elisp-mode.el return a value that no more obeys the doc-strings of (1), (2) and (3). It's also possible that the incompatible change is a combination of (3) and (4): (3) changed the implementation in a way that already violated the semantics of 'eldoc-documentation-function' by silently accepting return values that at the time (3) was installed were invalid according to its doc-string. (4) then sanctioned that violation by aliasing the variable and amending the doc-string. > (I've explained at length why, I think) So let's continue to disagree. martin