From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Gregory Heytings via "Emacs development discussions." Newsgroups: gmane.emacs.devel Subject: RE: master 2a7488d: Add support for displaying short documentation for function groups Date: Mon, 12 Oct 2020 16:50:44 +0000 Message-ID: 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> <5657b8b2-59ee-45e8-b851-5c93da82bd82@default> Reply-To: Gregory Heytings Mime-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16418"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Alpine 2.22 (NEB 394 2020-01-19) Cc: Lars Ingebrigtsen , Eli Zaretskii , emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Oct 12 18:52:02 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 1kS13K-000497-GQ for ged-emacs-devel@m.gmane-mx.org; Mon, 12 Oct 2020 18:52:02 +0200 Original-Received: from localhost ([::1]:41994 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kS13J-0001ZN-JH for ged-emacs-devel@m.gmane-mx.org; Mon, 12 Oct 2020 12:52:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46756) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kS12H-0000E0-FC for emacs-devel@gnu.org; Mon, 12 Oct 2020 12:50:58 -0400 Original-Received: from mx.sdf.org ([205.166.94.24]:60439) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kS12D-0000Kz-FN; Mon, 12 Oct 2020 12:50:57 -0400 Original-Received: from sdf.org (IDENT:ghe@otaku.sdf.org [205.166.94.8]) by mx.sdf.org (8.15.2/8.14.5) with ESMTPS id 09CGolLp027226 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Mon, 12 Oct 2020 16:50:48 GMT Original-Received: (from ghe@localhost) by sdf.org (8.15.2/8.12.8/Submit) id 09CGolRE019150; Mon, 12 Oct 2020 16:50:47 GMT In-Reply-To: <5657b8b2-59ee-45e8-b851-5c93da82bd82@default> Received-SPF: pass client-ip=205.166.94.24; envelope-from=ghe@sdf.org; helo=mx.sdf.org X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/12 11:41:42 X-ACL-Warn: Detected OS = ??? X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, 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:257480 Archived-At: > > 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. > We can in theory, but it would be too inefficient, as you said yourself. I think that checking the indexes of the sixty info files whenever a *Help* buffer is opened is not feasible. > > 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. > It was the meaning of my proposal. Now it has to be done, of course. But for this there needs to be an agreement that it's a good thing to do. >> 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: >> >> 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. > I do not think so. Remember that what triggered my proposal was a question by RMS: how to make manuals easier to access by newcomers. If you provide these newcomers with three similar versions of the same information (the docstring of kill-buffer, the documentation of kill-buffer in the Emacs manual, the documentation of kill-buffer in the Emacs Lisp manual), they will not see the point of reading the manuals. If you point them to the beginning of a chapter, they will see something different, in which they can expect to (and will) find information about the context of the command or function, for example, what the related concepts are, and what other related functions can do. A manual is a manual, not a dictionary. > > They're different, yes, but not profoundly different. > It depends how you define profound ;-) > > And the inefficiency I referred to is likely from my insufficient > knowledge of using `info-lookup'. > I do not think so, but I would be happy to be proven wrong. It seems to me that searching the indexes of sixty info files takes time.