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 10:29:48 -0700 (PDT) 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> 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="30591"; 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 19:30:47 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 1kS1ep-0007pz-4m for ged-emacs-devel@m.gmane-mx.org; Mon, 12 Oct 2020 19:30:47 +0200 Original-Received: from localhost ([::1]:44126 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kS1eo-0002Y6-1b for ged-emacs-devel@m.gmane-mx.org; Mon, 12 Oct 2020 13:30:46 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55196) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kS1e1-000217-1U for emacs-devel@gnu.org; Mon, 12 Oct 2020 13:29:57 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:50084) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kS1dy-0005NF-RX; Mon, 12 Oct 2020 13:29:56 -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 09CHNhm7068815; Mon, 12 Oct 2020 17:29:52 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=cblEtGGLANIUI6WwVXLjUGFGx0ymO0WFGnfrAbRweec=; b=LhRrLbt/7tlniWzpTx8ZtCr4rDL6OvLKYfGgCjQS3wKeRMfplb60aQYZeSvAt1kL5W9L A+M4qY1CYITXyMwEQXGzQ6t006fottB7q7Y3kendfqROENO/Y7i/CUxFJv0ugv5DZ0RM AVseZUVbRbnAVFyfHx0AVf/Dya57z+nVxBsMytPEZfsojM4Ttt/AYZw+eCS9rrv3BfU6 r6tzK6q97yHCuynVlnFNqaDWq8GXigfryOEQUpFD5LXiEW7HAkWbW2BrjU5qztgDYVSL M3ecgXCm9DMMLrLNsxS52/ClQvhO6MfSs5RrnNoGKCgfNm1SUYLO2Qx7v6499Vkuqahv SQ== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 343vae4nn2-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Mon, 12 Oct 2020 17:29:52 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 09CHTaML160211; Mon, 12 Oct 2020 17:29:51 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserp3030.oracle.com with ESMTP id 343phm3y9q-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 12 Oct 2020 17:29:51 +0000 Original-Received: from abhmp0010.oracle.com (abhmp0010.oracle.com [141.146.116.16]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 09CHTmpS015013; Mon, 12 Oct 2020 17:29:50 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 phishscore=0 spamscore=0 adultscore=0 bulkscore=0 mlxlogscore=999 malwarescore=0 mlxscore=0 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2010120135 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-2010120134 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:257488 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. >=20 > 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. That's not what happens. The default behavior is to use `info-lookup-symbol'. That's immediate. It produces the link in *Help* immediately, and when you click the link it immediately goes to one of the manuals. An alternative behavior also immediately produces the link in *Help*. But when you click the link it accesses the Indexes of the manuals and takes you to an Info Index with links to the manuals. This alternative can give you a link to more than one manual. That's its advantage, but at the cost of index lookups when you click the link. Again, that's not the default behavior. > >> See also the following manual chapters: for interactive use, see > >> `(emacs) Buffers'; for Emacs Lisp programming use, see `(elisp) > >> Buffers'. > > > > 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. >=20 > 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. We disagree about what manual pages the *Help* on a command should link to. And so far, at least, the manual Indexes agree with me about this. And if the Indexes are ever changed to take you to the chapter and not the more specific node, then the same solution I proposed will do what you want. IOW, the link should reflect our indexing. > > And the inefficiency I referred to is likely from my insufficient > > knowledge of using `info-lookup'. >=20 > 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. With `help-fns+.el' users can control which manuals to use. And so can any library code: pick the manuals to use according to some context etc. `info-lookup-symbol' is _very_ quick. Assuming it can be made to work well with additional manuals, which some have said is the case, and assuming it can be made to return links to multiple manuals, there would presumably be no naive index-lookup such as what my code currently does.