GNU bug report logs - #10844
24.0.93; Slightly unclear help text about remapped commands

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 10844 in the body.
You can then email your comments to 10844 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: Lars Ingebrigtsen <larsi <at> gnus.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.0.93; Slightly unclear help text about remapped commands
Date: Sun, 19 Feb 2012 10:19:32 +0100

If I type `C-h f kill-buffer', I currently get the following help text:

----
kill-buffer is an interactive built-in function in `C source code'.

It is remapped to `ido-kill-buffer', which is bound to C-x k.

(kill-buffer &optional BUFFER-OR-NAME)
----

I was puzzled what this meant.  Had `kill-buffer' been redefined?  What
does "remapped" mean?  If I try to use `kill-buffer', will I be using
`ido-kill-buffer' instead?

So I looked at a different function to compare:

----
compose-mail is an interactive compiled Lisp function in `simple.el'.

It is bound to C-x m, <menu-bar> <tools> <compose-mail>.
----

Oh, so the "remapped" means something like "this command is usually
bound to `C-x k', but currently `C-x k' is bound to `ido-kill-buffer'
instead" or something.

So I think the help text here could be clearer.


In GNU Emacs 24.0.93.34 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.6)
 of 2012-02-19 on rusty
Windowing system distributor `The X.Org Foundation', version 11.0.11004000
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t


-- 
(domestic pets only, the antidote for overdose, milk.)
  http://lars.ingebrigtsen.no  *  Sent from my Rome

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Ingebrigtsen'" <larsi <at> gnus.org>, <10844 <at> debbugs.gnu.org>
Subject: RE: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Sun, 19 Feb 2012 07:25:36 -0800

> kill-buffer is an interactive built-in function in `C source code'.
> It is remapped to `ido-kill-buffer', which is bound to C-x k.
> 
> I was puzzled [by] what this meant.

Remapping: the "mapping" is between commands and keys.  It should be sufficient
to add only a couple of words here to make things clearer.  E.g.

Its keys have been remapped to `ido-kill-buffer': `C-x k', `C-M-whatever',...
^^^^^^^^

It is fine for the regular doc, which explains things more precisely and at more
length, to speak of one _command_ being remapped to another _command_.  But here
it might be better to speak of one command's key bindings being remapped to
another command.

That said, I don't have a problem with the current help in this context.  I
mainly want us to avoid becoming verbose here just in order to make clear what
admittedly could be confusing.

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 'Lars Ingebrigtsen' <larsi <at> gnus.org>, 10844 <at> debbugs.gnu.org
Subject: Re: bug#10844: 24.0.93; Slightly unclear help text about remapped
	commands
Date: Mon, 20 Feb 2012 21:25:50 +1300

On 20/02/2012 04:25, Drew Adams wrote:
>> kill-buffer is an interactive built-in function in `C source code'.
>> It is remapped to `ido-kill-buffer', which is bound to C-x k.
>>
>> I was puzzled [by] what this meant.
>
> Remapping: the "mapping" is between commands and keys.  It should be sufficient
> to add only a couple of words here to make things clearer.  E.g.
>
> Its keys have been remapped to `ido-kill-buffer': `C-x k', `C-M-whatever',...
> ^^^^^^^^
>
> It is fine for the regular doc, which explains things more precisely and at more
> length, to speak of one _command_ being remapped to another _command_.  But here
> it might be better to speak of one command's key bindings being remapped to
> another command.
>
> That said, I don't have a problem with the current help in this context.  I
> mainly want us to avoid becoming verbose here just in order to make clear what
> admittedly could be confusing.

What if the wording were kept the same, but the word "remapped"
was linked to the relevant page in the info manual?

That keeps it concise for people who know what it means, and
provides all the details for anyone who doesn't.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Phil Sainty'" <psainty <at> orcon.net.nz>
Cc: 'Lars Ingebrigtsen' <larsi <at> gnus.org>, 10844 <at> debbugs.gnu.org
Subject: RE: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Mon, 20 Feb 2012 08:03:42 -0800

> >> It is remapped to `ido-kill-buffer', which is bound to C-x k.
> >
> > Its keys have been remapped to `ido-kill-buffer': `C-x k', 
> > `C-M-whatever',...
>
> What if the wording were kept the same, but the word "remapped"
> was linked to the relevant page in the info manual?
> 
> That keeps it concise for people who know what it means, and
> provides all the details for anyone who doesn't.

Do whatever you want.  But:

1. I don't find "It is" much more concise than "Its keys have been" (or "Its
keys are").

2. Does the current text list all of the keys for the remapping?

3. Linking to the manual is good.  I've suggested that be done more in the past,
but the idea has not been taken up.  I even provided a general facility for
doing that: 

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8900

http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 10844 <at> debbugs.gnu.org
Subject: Re: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Mon, 20 Feb 2012 12:30:56 -0500

> kill-buffer is an interactive built-in function in `C source code'.
> It is remapped to `ido-kill-buffer', which is bound to C-x k.

Indeed, it's a bit confusing.  I'm thinking of something along the lines of:

   ...
   It is normally bound to C-x k,
   tho the command is remapped to `ido-kill-buffer'.

but I'm not satisfied yet.  Can someone help out find a wording that's
sufficiently concise for those who know what's going on without being
confusing for those who don't?


        Stefan

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: 10844 <at> debbugs.gnu.org
Subject: Re: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Mon, 20 Feb 2012 18:36:11 +0100

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:

> Indeed, it's a bit confusing.  I'm thinking of something along the lines of:
>
>    ...
>    It is normally bound to C-x k,
>    tho the command is remapped to `ido-kill-buffer'.
>
> but I'm not satisfied yet.  Can someone help out find a wording that's
> sufficiently concise for those who know what's going on without being
> confusing for those who don't?

It is normally bound to C-x k,
but this keystroke is currently remapped to `ido-kill-buffer'.

"Command" is ambiguous, since `kill-buffer' is a command, and we want to
avoid saying the `kill-buffer' is "remapped", which is what confused me
in the first place.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
  http://lars.ingebrigtsen.no  *  Sent from my Rome

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> IRO.UMontreal.CA>,
	"'Lars Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 10844 <at> debbugs.gnu.org
Subject: RE: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Mon, 20 Feb 2012 09:37:54 -0800

> > kill-buffer is an interactive built-in function in `C source code'.
> > It is remapped to `ido-kill-buffer', which is bound to C-x k.
> 
> Indeed, it's a bit confusing.  I'm thinking of something 
> along the lines of:
>    It is normally bound to C-x k,
>    tho the command is remapped to `ido-kill-buffer'.
> 
> but I'm not satisfied yet.  Can someone help out find a wording that's
> sufficiently concise for those who know what's going on without being
> confusing for those who don't?

What is wrong with "Its keys are remapped to..." (instead of "It is remapped
to...")?  Seems concise and clear, to me.

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

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 'Lars Ingebrigtsen' <larsi <at> gnus.org>,
	'Stefan Monnier' <monnier <at> IRO.UMontreal.CA>, 10844 <at> debbugs.gnu.org
Subject: Re: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Sat, 25 Feb 2012 11:43:19 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> What is wrong with "Its keys are remapped to..." (instead of "It is remapped
> to...")?  Seems concise and clear, to me.

Nothing.  I propose this:

  Its keys are remapped to `ido-kill-buffer'.  Without this remapping, it
  would be bound to C-x k.

Any objections?

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Chong Yidong <cyd <at> gnu.org>
Cc: 10844 <at> debbugs.gnu.org, 'Stefan Monnier' <monnier <at> IRO.UMontreal.CA>,
	Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Sat, 25 Feb 2012 05:05:02 +0100

Chong Yidong <cyd <at> gnu.org> writes:

> Nothing.  I propose this:
>
>   Its keys are remapped to `ido-kill-buffer'.  Without this remapping, it
>   would be bound to C-x k.
>
> Any objections?

Looks good to me.

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> gnu.org>
Cc: 'Lars Ingebrigtsen' <larsi <at> gnus.org>,
	'Stefan Monnier' <monnier <at> IRO.UMontreal.CA>, 10844 <at> debbugs.gnu.org
Subject: RE: bug#10844: 24.0.93;
	Slightly unclear help text about remapped commands
Date: Fri, 24 Feb 2012 21:53:55 -0800

> > What is wrong with "Its keys are remapped to..." (instead 
> > of "It is remapped to...")?  Seems concise and clear, to me.
> 
> Nothing.  I propose this:
> 
>   Its keys are remapped to `ido-kill-buffer'.  Without this 
>   remapping, it would be bound to C-x k.
> 
> Any objections?

As long as all of the keys are mentioned, it's fine.  That was part of the
discussion: to be sure that all of the keys are listed.  (I don't know that they
are not already, but let's be sure they are.)

Previous Next

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