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: How to make Emacs popular again. Date: Fri, 9 Oct 2020 15:50:08 -0700 (PDT) Message-ID: References: <20200926163008.GS1349@protected.rcdrun.com> <749c3394-ec9a-43a5-aad6-942a5583d072@default> <39e60177-7d71-489a-a39c-38b3cf291266@default> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="30108"; mail-complaints-to="usenet@ciao.gmane.io" Cc: bobnewell@bobnewell.net, =?iso-8859-1?B?Sm/jbyBU4XZvcmE=?= , Robert Pluim , Richard Stallman , emacs-devel@gnu.org To: Gregory Heytings Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Oct 10 00:51:22 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 1kR1EP-0007iN-O2 for ged-emacs-devel@m.gmane-mx.org; Sat, 10 Oct 2020 00:51:21 +0200 Original-Received: from localhost ([::1]:59970 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kR1EO-0008FF-O5 for ged-emacs-devel@m.gmane-mx.org; Fri, 09 Oct 2020 18:51:20 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59362) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kR1DW-0007np-Ss for emacs-devel@gnu.org; Fri, 09 Oct 2020 18:50:26 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:46504) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kR1DU-0000yf-Lq; Fri, 09 Oct 2020 18:50:26 -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 099MnZHL085145; Fri, 9 Oct 2020 22:50:20 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=OPLGgysfSd346Pxnjo/kAK/tF4i2YbF0Yit5DPXTVWI=; b=yIQNOg0E1aJs+ebH7j64t6QC1JeeqcpE/ZR+Lshu8WmJBk4Sk6S24x0IQNhNAvJP4pVZ qha6Mb6FWkn90vGv75vkgy8TWinZxwdxAqf/b5YBvXOoUvaB6UONsJTRvy2fl3qolR5k ED5/BuaXelanQYO4iWRE2IEJnaDPzgA76PP+MNyK6lL1cFrHSrfAY3rkjuc+LD0WwZ1x bnfLmQygXZ2L+sxeFZLg6KIRYgGXhf8lOqhGCka3zxmT/+XZpsYAoyayNX9BInUfYoKy LJl/ePqU+iadRwBV6D1oHq84+FRqlPWzdoQUF8VFnwhk8IWq1UsE0CpP9Rmh8sxO1kG6 /A== Original-Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80]) by userp2120.oracle.com with ESMTP id 3429jmnt5r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 09 Oct 2020 22:50:19 +0000 Original-Received: from pps.filterd (userp3030.oracle.com [127.0.0.1]) by userp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 099MoJbb178067; Fri, 9 Oct 2020 22:50:19 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userp3030.oracle.com with ESMTP id 3429k1my5u-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 09 Oct 2020 22:50:19 +0000 Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 099Mo9nD012403; Fri, 9 Oct 2020 22:50:09 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=9769 signatures=668681 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 phishscore=0 malwarescore=0 mlxlogscore=999 bulkscore=0 suspectscore=0 adultscore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2010090171 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9769 signatures=668681 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 spamscore=0 suspectscore=0 clxscore=1015 phishscore=0 lowpriorityscore=0 impostorscore=0 malwarescore=0 mlxlogscore=999 priorityscore=1501 mlxscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2010090171 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/09 18:50:22 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:257285 Archived-At: > > That one should be covered by an explicit sentence with a link to the > > manual. I already mentioned that (and said I do that in help-fns+.el). >=20 > Sorry, I did not know you already do that in help-fns+.el when I answered > RMS' email a few hours ago. >=20 > As I mentioned earlier, there are however two important difference betwee= n > what you do in help-fns+ (which I just tried) and what I proposed: >=20 > 1. I do not think this can be done programmatically, the meaning of the > proposal was to do this by adding information in docstrings manually. I don't know what "this" is. Programmatically adding a link to the manuals for the symbol that's the subject of the *Help* is already done (with `help-fns+.el'). Just what do you think can't be done programmatically? > 2. I do think that a link to the place where the function/variable/... is > being defined in the manual is the best solution, a link to the chapter > would be better. I just tried it with "kill-buffer", the additional > information (additional wrt to the docstring) I get by entering the two > manual sections is nil. I don't understand. If I click the `manuals' link in the *Help* output (from `help-fns+.el') for `C-h f kill-buffer' I go to the manual for that command. By default you go to the manual per `info-lookup-symbol'. But you can optionally instead have the link search the indexes of any set of manuals and show you an Info Index buffer with links to a hit in each relevant manual. > > But even that one could be handled instead, or also, the same way. > > It's not quoted (`...'), but it's easy to find where it is and give it > > go-to-manual behavior. >=20 > IMO this would not be optimal. I think an explicit link (like the one at > the end of the docstring of defcustom) makes it clear that if you follow > it you leave the "built-in" documentation and open a "manual" (in another > window). It need not be only an either/or. Links at `...' naturally go to `*Help*' for their symbols. But it doesn't hurt to have `help-echo' tell you that, in addition, `C-h S' takes you to the relevant part of the Emacs or Elisp manual. > > Both would be useful: > > > > 1. Link(s) to manual(s) for the name that is the subject of the help. > > This can be in an explicit sentence that makes clear what it does - as > > mentioned earlier. >=20 > Yes. >=20 > > 2. Links to manuals for each quoted, linked name in the buffer (or each > > known to be doc'd in a manual, if that's known when the buffer is > > created). > > > > For #2, such names already have inline links where they occur. It > > suffices to (1) give users an easy way to get to the manual(s) from tha= t > > location, preferably by both mouse and key, and (2) let users know abou= t > > this possibility. >=20 > Perhaps I don't understand what you mean, but I don't see why this would > be useful. It would be useful for the same reason that `C-h S' is useful anywhere. All this is, is reminding users (and telling those who would be unaware) that `C-h S' takes you to the coverage of a symbol in the manual. As someone else said earlier in this thread, that's maybe not known widely enough. It's like the question of why we quote and highlight defined symbols: `...'. We do so to let you recognize that they're defined symbols. This is so, independent of the fact that we might also put a link on the symbol (and we don't always succeed in putting a link on every relevant occurrence, unfortunately). > The current system (docstrings with links to other docstrings) > works well. If links to manual chapters are added at the end of each > docstring, why would it be necessary to duplicate that information after > the docstrings that refer to a given docstring? See above. > For example, why would it be useful to add a link (info > "(elisp)Processes") in kill-buffer because it mentions 'process-buffer', > when following the link on 'process-buffer' already opens (or rather, > would open) a help buffer with a link to (info "(elisp)Processes")? It's useful for the reason given above. The fact that you can instead, or in addition, visit the *Help* for that symbol, and then click its "...manual" link to get to its doc in the manual, doesn't preclude the usefulness of getting there directly while keeping the same *Help* open. The two are orthogonal, even if they both give you a way to get to the manual. ___ What's still missing, AFAIK: 1. Ability for `info-lookup-symbol' to use an arbitrary set of manuals. Eli has said this is possible, but it's not clear to me how. (I haven't looked for it, though.) 2. Ability to get access to matches in multiple manuals. `help-fns+.el' lets you do that: you can be shown an Info Index buffer with a link for each manual with a match. However: a. Only one match is used per manual. b. It's not performant: the indexes of a manual are searched when you click the link. Still useful, but not very handy. If `info-lookup-symbol' (or some other function) could do both of those things in a performant way, that would be great.