From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#23236: 25.0.90; Document command remapping in Emacs manual, not just Elisp manual Date: Thu, 7 Apr 2016 08:58:24 -0700 (PDT) Message-ID: References: <<24ddcbf0-337e-401f-a539-4d957030236b@default>> <<83h9fdl9m9.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1460044812 22048 80.91.229.3 (7 Apr 2016 16:00:12 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 7 Apr 2016 16:00:12 +0000 (UTC) Cc: 23236@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Apr 07 17:59:58 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aoCLd-00049f-UF for geb-bug-gnu-emacs@m.gmane.org; Thu, 07 Apr 2016 17:59:58 +0200 Original-Received: from localhost ([::1]:50863 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoCLd-0001ok-Fd for geb-bug-gnu-emacs@m.gmane.org; Thu, 07 Apr 2016 11:59:57 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58329) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoCKo-0000OW-46 for bug-gnu-emacs@gnu.org; Thu, 07 Apr 2016 11:59:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aoCKk-0003vl-3r for bug-gnu-emacs@gnu.org; Thu, 07 Apr 2016 11:59:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:40751) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoCKj-0003vg-Vw for bug-gnu-emacs@gnu.org; Thu, 07 Apr 2016 11:59:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1aoCKj-0002nQ-RE for bug-gnu-emacs@gnu.org; Thu, 07 Apr 2016 11:59:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 07 Apr 2016 15:59:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 23236 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 23236-submit@debbugs.gnu.org id=B23236.146004471310710 (code B ref 23236); Thu, 07 Apr 2016 15:59:01 +0000 Original-Received: (at 23236) by debbugs.gnu.org; 7 Apr 2016 15:58:33 +0000 Original-Received: from localhost ([127.0.0.1]:53088 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1aoCKH-0002mg-6V for submit@debbugs.gnu.org; Thu, 07 Apr 2016 11:58:33 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:44751) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1aoCKF-0002mT-Hm for 23236@debbugs.gnu.org; Thu, 07 Apr 2016 11:58:31 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u37FwPfw031462 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 7 Apr 2016 15:58:25 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0022.oracle.com (8.13.8/8.13.8) with ESMTP id u37FwPHB017576 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 7 Apr 2016 15:58:25 GMT Original-Received: from abhmp0005.oracle.com (abhmp0005.oracle.com [141.146.116.11]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id u37FwPMb019154; Thu, 7 Apr 2016 15:58:25 GMT In-Reply-To: <<83h9fdl9m9.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6744.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 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.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:116162 Archived-At: > > Search the Emacs manual for "remap". You will find nothing about > > command remapping. >=20 > Because it's not a user-level feature. I disagree. Why do you say it is not? Are users not supposed to remap commands? If they are, then what could you possibly mean by saying that doing so is not "user-level"? Until Emacs provides an easy Customize interface for customizing key bindings, users will use `define-key' and `global-set-key' to customize key bindings. They always have, and they still must. > > (global-set-key [remap foo] 'bar) is something that _users_ do. > > Likewise (define-key some-map [remap foo] 'bar). >=20 > It doesn't matter who does it. What matters is that these are Lisp > expressions, and those are usually documented in the ELisp manuals. I have no problem with them being documented in the Elisp manual. This bug does not request that they be removed from the Elisp manual. I think they - at least their existence - should also be documented in the Emacs manual. It may be enough to point users (from the Emacs manual) to the Elisp manual. But certainly users reading the Emacs manual should be able to find the answers to questions about _how to customize_ key bindings. And that includes command remapping. Binding keys is an extremely common end-user task. (Yes, it is. It is 100% "user-level", in addition to being something that is done in non-user files.) Not pointing end users, in the Emacs manual, to the information about _how they do this_ is a cop-out, I think. They will find that pointer only by googling etc. The Emacs manual should be their friend in this regard, by pointing them to the info they need to get the job done, whether or not the details of that info might be in the Elisp manual. If users need to use Lisp to customize key bindings, then so be it. And if they therefore need to read some of the Elisp manual, to learn how to do that, so be it. But the _fact_ that they _can_ do it, and the _fact_ that info about _how_ to do it is in the Elisp manual, should be in the Emacs manual. At a minimum. * You can bind keys to commands of your choosing. See (elisp) XXXX. * You can remap a command A to another command B's key bindings, so that using any of those keys invokes command A instead of command B. See (elisp) YYYY. > global-set-key is only documented in the user manual as a command, not > as a function. We only show a few examples of using it as a function. >=20 > > This is not something that is only for Elisp code. >=20 > I think it is. It is not something that is only for Lisp libraries. Is that clearer for you? It is something that is in thousands of end-user init files, including users who otherwise know little or nothing about Lisp. If you really think that using `define-key' and `global-set-key' in an end-user init file is inappropriate then please provide a Customize replacement for `define-key' and `global-set-key' immediately, and then update the Emacs manual to tell users how to customize key bindings using Customize. Until then, users have only `define-key' and `global-set-key' for key customization. The Emacs manual should help them in this regard. It should not be silent on command remapping.