From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#46627: [PATCH] Add new help command 'describe-command' Date: Tue, 23 Feb 2021 21:28:13 -0600 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="24766"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 46627@debbugs.gnu.org To: rms@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Feb 24 04:29:11 2021 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 1lEkrP-0006KT-1g for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 24 Feb 2021 04:29:11 +0100 Original-Received: from localhost ([::1]:55182 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lEkrO-0006H5-3x for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 23 Feb 2021 22:29:10 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39172) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lEkrG-0006Gw-Je for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2021 22:29:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:49702) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lEkrG-0007Io-CU for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2021 22:29:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lEkrG-0001S5-90 for bug-gnu-emacs@gnu.org; Tue, 23 Feb 2021 22:29:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 24 Feb 2021 03:29:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 46627 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 46627-submit@debbugs.gnu.org id=B46627.16141373025526 (code B ref 46627); Wed, 24 Feb 2021 03:29:02 +0000 Original-Received: (at 46627) by debbugs.gnu.org; 24 Feb 2021 03:28:22 +0000 Original-Received: from localhost ([127.0.0.1]:33015 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lEkqb-0001R4-Qz for submit@debbugs.gnu.org; Tue, 23 Feb 2021 22:28:22 -0500 Original-Received: from mail-pj1-f44.google.com ([209.85.216.44]:51114) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lEkqZ-0001Qr-Io for 46627@debbugs.gnu.org; Tue, 23 Feb 2021 22:28:20 -0500 Original-Received: by mail-pj1-f44.google.com with SMTP id b15so406171pjb.0 for <46627@debbugs.gnu.org>; Tue, 23 Feb 2021 19:28:19 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to:cc; bh=poV/xsazyT2A7MSnEcjorOzfm2t0LYHEIhgMfyzYSwU=; b=tGLQwQfPffJZERzI0QCo5e7av2/nQxqw4KxycfwSap6DiBEUYJLhc5q+VKRtzNwgJj gRfbhGox1g+CnRiWwCi6O8l8UIbdKDKpYD0EbI+QuFhkbbXc9Pe88d2Eaui5UdE/ULJc mtPSE6wcxz2MNgqYsBebqMrs+PaIxru7/JbkOC5R7fBHkysOgsWFLXhOlXb9L+wcQL93 7dPRMzKAGxdEzi8t0O+Pfb3cj5x+EK9vaWoslOPbuiUx6GGhzjUT0AqXVI2AjfVdkiGy pBB3chp4gjULKGnyfXKoQHiH5SjPD5cYWJq62RiTk91mMD4fbT5NyfZdSUuXYTV14nKk a6CQ== X-Gm-Message-State: AOAM531aWuF+PGUqIL1HILE7twSeZZ6rq642RVRA8FGgsnagfEFjILoN a4C2Vs44gpIWEntZO+7RIXoFUcHBWLgEOjQjHXxxgFvl X-Google-Smtp-Source: ABdhPJw6E3OXDXW2S3WZMpiflGYDV1SYWYc5w5O8GUXr+EQUCJnZdbigLd/woEeRdD7MV7bVSkM5UX7BHpq3HZ8FAwA= X-Received: by 2002:a17:90a:ea88:: with SMTP id h8mr2111291pjz.175.1614137293678; Tue, 23 Feb 2021 19:28:13 -0800 (PST) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Tue, 23 Feb 2021 21:28:13 -0600 In-Reply-To: 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:200700 Archived-At: Richard Stallman writes: > I will explain why I see it the way I do. Thank you, I will add my thoughts below. > > - `C-h f' for any function > > - `C-h x' for commands > > This is yet one more specific command one needs to remember. For a > beginner, or even a not-quite-beginner, learning hundreds of other > commands is the hard part. And it is easy to forget them. This is an important point when we add any command. I agree that in general we must be careful to not unduly add to the cognitive load of using Emacs. Note first that the `C-h f' command has never been that hard to learn, because it is just exactly the help key "C-h" and then "f" for "function" -- arguably one of the most mnemonic keybindings we have. (`C-h x' is a bit less mnemonic, indeed.) Here is how I approach this problem: - Most users do not need to see Emacs Lisp functions when starting out. They need to be able to find help for editor commands. - They should be using `C-h x', `describe-command'. That actually concludes what I expect a beginning Emacs user will have to learn. :-) - Emacs Lisp "literate" users often (but not always, see below) do want to see all functions. - Such users will hopefully already be familiar with `C-h x' from the tutorial, and its general use. - They will have to learn that you can see all functions, including commands, with this new command `C-h f'. This does add some cognitive load, I agree, as does any new command, but I think it is justified (see below). > By contrast, what TAB TAB TAB... does inside completion for commands > is a general feature, not similar to any other. > > Users will forget commands that they learned, but I think they will > hardly forget this. In general, I think the general idea behind the proposal is good. But in this case I think it is the wrong tool for the job. Let's think about the case with experienced users, because if I'm correct then newbies are not at first interested in functions. More experienced users will OTOH sometimes want to complete commands, and sometimes all functions. With the suggested TAB behavior, there is indeed an interface to switch between different completions. But which you prefer to see first is highly situationally bound: I myself would strongly prefer "all functions" when writing ELisp and "all commands" when, e.g. sending email or for general writing. So when writing ELisp, in comparison to today there is one more key to press if you want to complete on functions. This would mean that some users would likely want to turn this behavior off. (I would probably end up in that camp.) Doing that would unfortunately leave them with no way of completing on commands only--unless they again change the option to enable the feature. Now, if you are a bit smart, you would of course say: well, let's just use the correct default depending on mode! And perhaps that would help. But really, I do want to sometimes want to find the documentation for a function even when writing email (perhaps I want to quote it to someone, or perhaps I am just in the wrong window when trying to write some ELisp in *scratch*, ugh). So I think any model we find here really just leaves us with a sub-optimal user interface, merely to save us the cost of one command. Now, with the new `describe-command' command, a user could instead just press the correct key to get the exact completion she is looking for. In the same way, you would press `C-h v' for variables, etc. It is dead simple, but yes, one more command to learn (when you need it). One final point: the need to learn a new command by heart is at least somewhat offset by the `help-for-help' screen, conveniently available on `C-h C-h'. Not all commands have their keybindings this readily available: on a screen that looks the same in all modes, and which users will therefore hopefully learn to find and scan quicker than most other help screens.