GNU bug report logs - #23236
25.0.90; Document command remapping in Emacs manual, not just Elisp manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 23236 in the body.
You can then email your comments to 23236 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.90; Document command remapping in Emacs manual, not just Elisp
 manual
Date: Thu, 7 Apr 2016 08:04:19 -0700 (PDT)

Search the Emacs manual for "remap".  You will find nothing about
command remapping.

(global-set-key [remap foo] 'bar) is something that _users_ do.
Likewise (define-key some-map [remap foo] 'bar).

This is not something that is only for Elisp code.


In GNU Emacs 25.0.90.4 (i686-w64-mingw32)
 of 2016-03-20
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-w64-mingw32 --without-dbus
 --without-compress-install CFLAGS=-static'

Message #8 received at 23236 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 23236 <at> debbugs.gnu.org
Subject: Re: bug#23236: 25.0.90;
 Document command remapping in Emacs manual, not just Elisp manual
Date: Thu, 07 Apr 2016 18:30:22 +0300

> Date: Thu, 7 Apr 2016 08:04:19 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> Search the Emacs manual for "remap".  You will find nothing about
> command remapping.

Because it's not a user-level feature.

> (global-set-key [remap foo] 'bar) is something that _users_ do.
> Likewise (define-key some-map [remap foo] 'bar).

It doesn't matter who does it.  What matters is that these are Lisp
expressions, and those are usually documented in the ELisp manuals.
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.

> This is not something that is only for Elisp code.

I think it is.

Message #11 received at 23236 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 23236 <at> debbugs.gnu.org
Subject: RE: 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)

> > Search the Emacs manual for "remap".  You will find nothing about
> > command remapping.
> 
> 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).
> 
> 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.
> 
> > This is not something that is only for Elisp code.
> 
> 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.

Message #14 received at 23236 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 23236 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#23236: 25.0.90;	Document command remapping in Emacs manual,
 not just Elisp manual
Date: Thu, 07 Apr 2016 19:49:48 +0300

> Date: Thu, 7 Apr 2016 08:58:24 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 23236 <at> debbugs.gnu.org
> 
> > > Search the Emacs manual for "remap".  You will find nothing about
> > > command remapping.
> > 
> > Because it's not a user-level feature.
> 
> I disagree.  Why do you say it is not?  Are users not supposed to
> remap commands?

Users that code in Lisp are.  Users that don't aren't.

> If they are, then what could you possibly mean
> by saying that doing so is not "user-level"?

It's not for users who don't write Lisp code.

> 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.)

And it is virtually impossible without writing Lisp.

Message #17 received at 23236 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 23236 <at> debbugs.gnu.org
Subject: RE: bug#23236: 25.0.90;	Document command remapping in Emacs manual,
 not just Elisp manual
Date: Thu, 7 Apr 2016 10:44:59 -0700 (PDT)

> > > > Search the Emacs manual for "remap".  You will find nothing about
> > > > command remapping.
> > >
> > > Because it's not a user-level feature.
> >
> > I disagree.  Why do you say it is not?  Are users not supposed to
> > remap commands?
> 
> Users that code in Lisp are.  Users that don't aren't.
> 
> > If they are, then what could you possibly mean
> > by saying that doing so is not "user-level"?
> 
> It's not for users who don't write Lisp code.
> 
> > 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.)
> 
> And it is virtually impossible without writing Lisp.

You seem to be being quite dogmatic here.

This bug is about users who customize keys.  That includes maybe
99% of Emacs users, I'd guess.  Maybe 90% if you're skeptical.

And a good number of those are end users who do not otherwise
use Emacs Lisp, or use it very little - maybe 50%?  My guess is
that the vast majority of Emacs users who know little or nothing
about Emacs Lisp customize keys.

It doesn't take a Lisp pro to learn to use `global-set-key' in
your init file.  And the proof of that, I'm guessing, is in the
many, many, init files of users who barely know the first thing
about Lisp.  I see this daily in questions posed by end users.

The point is that:

1. End users DO customize keys.  They want to and need to,
   in general.  There is nothing non-end userish about the users
   who customize Emacs keys.  Perhaps the most common customization
   by non-Lisper Emacs end users is key customization.  So yes,
   this is a tiny exception to their non-Lisperness.  By force,
   because there is no alternative to using Lisp to customize keys.

2. As long as they do, which means as long as there is no
   alternative to Lisp for customizing keys, it would be silly
   for Emacs developers to adopt the ostrich-head-in-sand cop-out
   that customizing keys is not for end users, and so it should
   be documented only in the Elisp manual.  And with mention of
   the FACT that they can customize keys and to the FACT that how
   to do this is documented in the Elisp manual - NO POINTER.
   That cop-out does not help anyone, IMO.

IOW, point end users reading the _Emacs_ manual to the relevant
parts of the Elisp manual that tell them how to customize keys.
Please.  Including for command remapping.

Message #20 received at 23236 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 23236 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#23236: 25.0.90;
 Document command remapping in Emacs manual, not just Elisp manual
Date: Sun, 01 May 2016 01:10:13 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Search the Emacs manual for "remap".  You will find nothing about
>> command remapping.
>
> Because it's not a user-level feature.

I agree.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.