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 Date: Thu, 1 Oct 2020 10:40:26 +0200 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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17289"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 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 Thu Oct 01 10:41:56 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 1kNu9z-0004Me-A6 for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 01 Oct 2020 10:41:55 +0200 Original-Received: from localhost ([::1]:52294 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNu9w-0000DN-Pv for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 01 Oct 2020 04:41:53 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36596) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNu99-0000D1-3v for bug-gnu-emacs@gnu.org; Thu, 01 Oct 2020 04:41:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50683) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kNu98-0003vD-6M for bug-gnu-emacs@gnu.org; Thu, 01 Oct 2020 04:41:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kNu98-0008En-4l for bug-gnu-emacs@gnu.org; Thu, 01 Oct 2020 04:41: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: Thu, 01 Oct 2020 08:41: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.160154163531623 (code B ref 43609); Thu, 01 Oct 2020 08:41:02 +0000 Original-Received: (at 43609) by debbugs.gnu.org; 1 Oct 2020 08:40:35 +0000 Original-Received: from localhost ([127.0.0.1]:33996 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kNu8h-0008Dz-Gb for submit@debbugs.gnu.org; Thu, 01 Oct 2020 04:40:35 -0400 Original-Received: from mout.gmx.net ([212.227.15.19]:53101) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kNu8g-0008Dk-2G for 43609@debbugs.gnu.org; Thu, 01 Oct 2020 04:40:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1601541628; bh=NwXJ821KAtSFlq8QBqdsGjbmnmX+k70j8NzSXLKEtzg=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=EzK0HOB98OeSKpSrwJl82LA7Cy/mmVcjgkhyTLhkldnALFiOOfrpmtFJ16iBZhOGi MSm78EklHhuTIbKs78o8WdlcrKHTf9T7vu7guNG9xa5sO8x8VBpF7Z+LM/SNVnFj7q DrAcWSDCMZIVrCmWGX7kr9gFTOwnMVjdDusukFlg= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [192.168.1.101] ([212.95.5.212]) by mail.gmx.com (mrgmx005 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MMofW-1k5Gn93QKS-00Ine5; Thu, 01 Oct 2020 10:40:27 +0200 In-Reply-To: <87a6x7jf9a.fsf@gmail.com> Content-Language: en-US X-Provags-ID: V03:K1:PGodzaEetLTHY600uT/msBV6/ty2eduWaetbaid+IZJlEF6CqXr 3NEce5lziWQvaKm6J6On6rTqzuvvi6jobwKjn5mtZDKMlWa6SGIStPPt5FRHM1JONw0tTzq wTN6EdW2ledwWnzEqrRmq7Okjh72BEfTsdfp9nq8NWRL9Xl6NUL/8cisFws27NZm2VQ5Ns8 10fhiGjnOv6aNeSgTstUA== X-UI-Out-Filterresults: notjunk:1;V03:K0:iKDd8+1Aryc=:NtsK7SO0zDilXxC/YdaZrw IeEwpezA2XXRanFvSDAZDwsSJx3gFzHokiAiH3fOhJNn4DEgkQ8vkxRgVmuf3tFBN7FpRsDTu mDaPa++UKsciKw3ko/Kv4rHKt1i28gtcKmFjlbH7zIACSB0KCOF9GkIfzTNBcdrQMi0/49mKh bZYBFYrlCGZurbDLldSutlYRntgI7NjKWNxrRpQ0ozkuxS64Kp55cO2LC5u5y/6ux/Hsa31ZA yHxexy1qCUQHiaHuriqAhr3RuzoAHikM8At9tG5Gj2k0Z9pva1ZkdtMahIHqGGuFsg2Z0Ef5E XqX+qHrL4PsfyyUCXlb6XpByuiYlqFfeqrdBGgnhYiH21GO+wn/4pRlvEx/iIULYNTG7Dgxqb fU7YKJDSDw/noTd+ED7V3OH3UiQN3CgByQrp5n51IFJWESMN2rXHyPkKxv7Mxzjn7ZCaPU8dr YgXnblsz1Y9p2q3OEjevsipELyPjpIMx/ScJxCm4dS0c38hwinGo68LPgeUqnrlMcxl2D/zbi nztz4CUWP/GMOG+IvXeMPIoVYPKlNDYBv/YUhPxVfJh0QBlWyf/iV1nre+ZZQ8v8tGHHnu2qs eLLbkWZzM6znXmO+uMe4MKBkfBKcZNS+d9RFP2TjX1aJxk8fM+YE982teLoAVmaN0n1hPc6e8 K8HZ1tXuoA6ePGmMFCRtL73XBUSv7goJF4c9wWfLGvRwEv1U4dn9QGMYpx35LOCpiQAKFpYap y5F4Ily4wedoIovBKHf5Xr+QwjSrCvlJ+i9AFXHSnRvHWLItY4Q3jo4Dmubz368wix5L3KE+ 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:189476 Archived-At: > Maybe there are examples but I can't find a single example of a user > variable ending in "-function" that's supposed to work like you describe > or that explicitly advocates for it/against it. If libraries establish > these variable indirections in the first place, it's because they expect > to be able to call them in the contexts of their choosing. So it never > crossed my mind, or my eyes that one would be expecting to use it like > that, neither did anyone specifically call attention to this and/or > provided an example. We probably should be more defensive when writing doc-strings for such variables. >> And as far as the former is concerned, I now cannot use even >> 'elisp-eldoc-documentation-function' directly either because you >> changed its return value too. > > I looked up uses of that function in the Emacs source tree and couldn't > find any. Because of the reasoning explained above, I also expected > Elisp mode to be its sole reasonable user. Agreed if you meant to say that eldoc-mode would be the sole reasonable user of 'elisp-eldoc-documentation-function'. > 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). I won't insist if I have something that substitutes it. And if you can provide that something within eldoc.el, a simple cross reference from the doc-string of 'eldoc-documentation-function(s)' would be enough. >>> If you need a direct call, "give me the string" entry point to the >>> eldoc.el library, one can be added. >> >> I think we should do that and provide it as compatibility layer for >> people like me who need it. > > OK. Do you know very many of those? No. Do you know anyone who displays eldoc outside of the echo area? >>> - Do you want to have a return value handy for the docstrings that are >>> immediately available from the sources that respond synchronously? >> >> Definitely. > > That would be very close to the `martin` function I gave you earlier. Yes. >>> - Do you want to wait actively until all sources have reported back and >>> then get a return value? In this case, do you need a timeout? >> >> If we can provide an option for that, yes. > > It's easy to do (Eldoc's current version has to do it already). OK. >>> - Independent of your choice above, or do you want to get the return >>> value as list of strings? Or as a single string, maybe concatenated >>> and propertized, exactly the way it is display[ed in the echo area]. >> >> I'd prefer a list of strings. > > What about a slightly more complex type? (but not much) No objections. > As of now, "enriched" docstrings can be seen as the association of a > string with a number of properties, say the "thing" being documented, or > the preferred "face" to do it in. Later on, a piece of documentation > can have, for example, other optional meta-hints about it, such as the > language or variations on itself for displaying under a very limiting > context (such as the echo area), or very permissive context (such as a > spacious Help-like buffer). I certainly would not mind a buffer (like *eldoc-latest*) that I could consult to obtain the latest information eldoc caught about the symbol at point of the selected window either. Maybe together with some status indicator about how much of that information has been retrieved already. > So I think it the return value of such a function should thus be: > > ...a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2 > VALUE2 ...). STRING is the a possibly propertized string > containing the documentation's text and the remainder of DOC is > an optional list of keyword-value pairs, described in > `eldoc-documentation-functions'. > > This will make the return value of the desired function match the values > given to eldoc-display-functions, which could come in advantageious. What, in a nutshell, would these 'eldoc-display-functions' be (sorry but my master on this system is in an inconsistent state and I don't want to resolve conflicts when pulling anything into it)? martin