From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: master 2a7488d: Add support for displaying short documentation for function groups Date: Mon, 12 Oct 2020 09:20:42 -0700 (PDT) Message-ID: <5657b8b2-59ee-45e8-b851-5c93da82bd82@default> References: <20201011035127.7723.3256@vcs0.savannah.gnu.org> <20201011035128.E3FD320667@vcs0.savannah.gnu.org> <87k0vxquvo.fsf@gnus.org> <83o8l850v5.fsf@gnu.org> <87k0vwfn99.fsf@gnus.org> <10ee24ac-7f59-437a-bee9-ec6d848d927d@default> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11556"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Lars Ingebrigtsen , Eli Zaretskii , emacs-devel@gnu.org To: Gregory Heytings Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Oct 12 18:24:36 2020 Return-path: Envelope-to: ged-emacs-devel@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 1kS0cm-0002ue-Bm for ged-emacs-devel@m.gmane-mx.org; Mon, 12 Oct 2020 18:24:36 +0200 Original-Received: from localhost ([::1]:43020 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kS0cl-00051b-EX for ged-emacs-devel@m.gmane-mx.org; Mon, 12 Oct 2020 12:24:35 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:40256) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kS0bI-00043c-Tu for emacs-devel@gnu.org; Mon, 12 Oct 2020 12:23:04 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:56860) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kS0b9-0004sS-VO; Mon, 12 Oct 2020 12:23:04 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 09CGMPQI157714; Mon, 12 Oct 2020 16:22:47 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=N5Q/5BmPlT3v9PGq+stlIKZ+kKF8WUk3xoGW7sr56Q4=; b=BZ4RhrQAxtVRZqKTovWKwvQ2BCMA/OywZiGkNNsBUMC0a6oHCadjbwvl2Yw7ZdzTliVq RUhtH6j7Hd4UGGdyQZwWSIEX+x62OnFJgZVQPpkfv697mfrmZYltka+AHJBdLls0JXWN kQzXsdGXgl0SPA9zpLqy7w0/YJPyzFB0SGhNYPKFFkDyyShlkjXnKUiLX821xoUNr9N+ SEzWcZI5ZU0/1hIMliMpV9QfthWYubirPXWl0u/Fr+O5EHAdlxMlJnkuu6vdTDwoEnIL iZShvtfu3dpFjj/KSAEmYinHpKA0wBZHEbRo02CeeJf71pg2P7inq2lZXTHV5Zgu788u LA== Original-Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by userp2120.oracle.com with ESMTP id 343vae4cep-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Mon, 12 Oct 2020 16:22:47 +0000 Original-Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 09CGJTqF059439; Mon, 12 Oct 2020 16:20:46 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userp3020.oracle.com with ESMTP id 344by0xwbq-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 12 Oct 2020 16:20:46 +0000 Original-Received: from abhmp0010.oracle.com (abhmp0010.oracle.com [141.146.116.16]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 09CGKheG019558; Mon, 12 Oct 2020 16:20:44 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5056.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9772 signatures=668681 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxlogscore=999 spamscore=0 suspectscore=0 mlxscore=0 malwarescore=0 adultscore=0 bulkscore=0 phishscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2010120128 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9772 signatures=668681 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxlogscore=999 clxscore=1015 impostorscore=0 phishscore=0 malwarescore=0 bulkscore=0 priorityscore=1501 mlxscore=0 suspectscore=0 spamscore=0 adultscore=0 lowpriorityscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2010120128 Received-SPF: pass client-ip=156.151.31.85; envelope-from=drew.adams@oracle.com; helo=userp2120.oracle.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/12 12:22:48 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:257474 Archived-At: > >> I think the manual gives superior information in most cases, so I'd > >> really like this to link to the manual and not the doc strings. This > >> is also a way to guide users into the manual and read more in-depth > >> about not just the functions described, but the machinery surrounding > >> them, giving them more context. > > > > *Help* should have a link to the relevant manual node. See thread "How > > to make Emacs popular again." That's not hard to do, and it's been don= e > > (e.g. in `help-fns+.el'). > > >=20 > As I already explained repeatedly, this is _not_ the meaning of my > proposal in that thread. The thread is not only about your posts to it. > My proposal is to _manually_ add pointers to the > relevant manual _chapters_ in docstrings. Yes, and I've voiced no objection to that. I was the one who pointed you to an example where we do that already. But you also said that you think we cannot provide such links automatically. And my response to that is that we can. And I have. (And so have others.) We can use that code, or we can use different code. We can do both: we can have manual fiddling to add links override/replace/augment any programmatically provided links, when that's helpful. So far, we have _VERY_ few manually provided links. Nothing is stopping someone from proposing adding this or that link manually. Still, we have very few, so far. Today, you can use `C-h k C-h m' to get the *Help* for `describe-mode', then click its `manuals' link: For more information see the manuals. That gives you an Info Index buffer with two links: Index Matches ************* Index entries that match `describe-mode': * Menu: * describe-mode [elisp]: (elisp)Mode Help. (line 11) * describe-mode [emacs]: (emacs)Misc Help. (line 36) And those take you to these nodes, which provide the doc for `describe-mode': 1. (emacs) Top > Help > Misc Help 2. (elisp) Top > Modes > Major Modes > Mode Help > For example, the docstring of kill-buffer would > have two links, one to (info "(emacs)Buffers") and another one to (info > "(elisp)Buffers"), with some explanation. For example: >=20 > See also the following manual chapters: for interactive use, see `(emacs) > Buffers'; for Emacs Lisp programming use, see `(elisp) Buffers'. And for `kill-buffer' the `manuals' link gives you an Info Index buffer with these two links: * kill-buffer [elisp]: (elisp)Killing Buffers. (line 31) * kill-buffer [emacs]: (emacs)Kill Buffer. (line 22) I think those are more appropriate targets than your `Buffers' nodes. But nothing prevents us from using code that does what you prefer, if that's agreed upon. It's not hard to get to the "chapter" node for a node that the Index takes us to. But there's a good reason why the Index entries for `kill-buffer' take us to the nodes they do: they're specifically about _that command_. > Your proposal is to merge a feature of help-fns+.el in help-fns.el. This > feature adds a link in *Help* buffers, and when the user clicks on that > link the indexes of a (user chosen) list of manuals are checked to see if > they contain pointers to the subject of the *Help* buffer. Doing this is= , > as you said yourself, inefficient. The result of this scan is presented > in another buffer as a list of links, and when the user clicks on these > links the place where the subject of the *Help* buffer is documented in > the manual is displayed. >=20 > These are two very different proposals. They're different, yes, but not profoundly different. And the inefficiency I referred to is likely from my insufficient knowledge of using `info-lookup'. With my code EITHER you can quickly get a direct link to one of the manuals (that's what `info-lookup-symbols' gives you), OR you can get a link that when clicked looks up the symbol in each of the manuals and gives you an Index list of links, as described above. It's a user choice. The former is immediate, but it doesn't give you links to each of the relevant manuals. The latter takes the time to perform index lookups. But I'm sure that someone more familiar with the `info-lookup' code can do better than I, providing links to multiple manuals quickly. And if that possibility isn't yet available from info-lookup, it can likely be coded. My point is not that we need to use the `help-fns+.el' code. And it's not to exclude the addition of links manually. My point is that we can and should provide links to the manuals from *Help*, and we can start doing that today. Improvements are always possible.