* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
@ 2012-02-19 9:19 Lars Ingebrigtsen
2012-02-19 15:25 ` Drew Adams
2012-02-20 17:30 ` Stefan Monnier
0 siblings, 2 replies; 10+ messages in thread
From: Lars Ingebrigtsen @ 2012-02-19 9:19 UTC (permalink / raw)
To: 10844
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-19 9:19 bug#10844: 24.0.93; Slightly unclear help text about remapped commands Lars Ingebrigtsen
@ 2012-02-19 15:25 ` Drew Adams
2012-02-20 8:25 ` Phil Sainty
2012-02-20 17:30 ` Stefan Monnier
1 sibling, 1 reply; 10+ messages in thread
From: Drew Adams @ 2012-02-19 15:25 UTC (permalink / raw)
To: 'Lars Ingebrigtsen', 10844
> 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-19 15:25 ` Drew Adams
@ 2012-02-20 8:25 ` Phil Sainty
2012-02-20 16:03 ` Drew Adams
0 siblings, 1 reply; 10+ messages in thread
From: Phil Sainty @ 2012-02-20 8:25 UTC (permalink / raw)
To: Drew Adams; +Cc: 'Lars Ingebrigtsen', 10844
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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-20 8:25 ` Phil Sainty
@ 2012-02-20 16:03 ` Drew Adams
0 siblings, 0 replies; 10+ messages in thread
From: Drew Adams @ 2012-02-20 16:03 UTC (permalink / raw)
To: 'Phil Sainty'; +Cc: 'Lars Ingebrigtsen', 10844
> >> 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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-19 9:19 bug#10844: 24.0.93; Slightly unclear help text about remapped commands Lars Ingebrigtsen
2012-02-19 15:25 ` Drew Adams
@ 2012-02-20 17:30 ` Stefan Monnier
2012-02-20 17:36 ` Lars Ingebrigtsen
2012-02-20 17:37 ` Drew Adams
1 sibling, 2 replies; 10+ messages in thread
From: Stefan Monnier @ 2012-02-20 17:30 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 10844
> 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
^ permalink raw reply [flat|nested] 10+ messages in thread* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-20 17:30 ` Stefan Monnier
@ 2012-02-20 17:36 ` Lars Ingebrigtsen
2012-02-20 17:37 ` Drew Adams
1 sibling, 0 replies; 10+ messages in thread
From: Lars Ingebrigtsen @ 2012-02-20 17:36 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 10844
Stefan Monnier <monnier@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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-20 17:30 ` Stefan Monnier
2012-02-20 17:36 ` Lars Ingebrigtsen
@ 2012-02-20 17:37 ` Drew Adams
2012-02-25 3:43 ` Chong Yidong
1 sibling, 1 reply; 10+ messages in thread
From: Drew Adams @ 2012-02-20 17:37 UTC (permalink / raw)
To: 'Stefan Monnier', 'Lars Ingebrigtsen'; +Cc: 10844
> > 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-20 17:37 ` Drew Adams
@ 2012-02-25 3:43 ` Chong Yidong
2012-02-25 4:05 ` Lars Magne Ingebrigtsen
2012-02-25 5:53 ` Drew Adams
0 siblings, 2 replies; 10+ messages in thread
From: Chong Yidong @ 2012-02-25 3:43 UTC (permalink / raw)
To: Drew Adams; +Cc: 'Lars Ingebrigtsen', 10844
"Drew Adams" <drew.adams@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?
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-25 3:43 ` Chong Yidong
@ 2012-02-25 4:05 ` Lars Magne Ingebrigtsen
2012-02-25 5:53 ` Drew Adams
1 sibling, 0 replies; 10+ messages in thread
From: Lars Magne Ingebrigtsen @ 2012-02-25 4:05 UTC (permalink / raw)
To: Chong Yidong; +Cc: 10844
Chong Yidong <cyd@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/
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#10844: 24.0.93; Slightly unclear help text about remapped commands
2012-02-25 3:43 ` Chong Yidong
2012-02-25 4:05 ` Lars Magne Ingebrigtsen
@ 2012-02-25 5:53 ` Drew Adams
1 sibling, 0 replies; 10+ messages in thread
From: Drew Adams @ 2012-02-25 5:53 UTC (permalink / raw)
To: 'Chong Yidong'; +Cc: 'Lars Ingebrigtsen', 10844
> > 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.)
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2012-02-25 5:53 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-02-19 9:19 bug#10844: 24.0.93; Slightly unclear help text about remapped commands Lars Ingebrigtsen
2012-02-19 15:25 ` Drew Adams
2012-02-20 8:25 ` Phil Sainty
2012-02-20 16:03 ` Drew Adams
2012-02-20 17:30 ` Stefan Monnier
2012-02-20 17:36 ` Lars Ingebrigtsen
2012-02-20 17:37 ` Drew Adams
2012-02-25 3:43 ` Chong Yidong
2012-02-25 4:05 ` Lars Magne Ingebrigtsen
2012-02-25 5:53 ` Drew Adams
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).