all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* org-mode, please change the name of function org-metaleft etc
@ 2007-10-30 21:16 Lennart Borgman (gmail)
  2007-10-30 23:49 ` Bastien
  2007-10-31  7:47 ` Richard Stallman
  0 siblings, 2 replies; 16+ messages in thread
From: Lennart Borgman (gmail) @ 2007-10-30 21:16 UTC (permalink / raw)
  To: Emacs Devel, Carsten Dominik

In org-mode the functions that are bound to some keys are named after 
the key binding, for example:

   <M-left>        org-metaleft

It might be helpful when developing, but it is not very helpful to the 
user. It would be nice of the name of those commands where changed to 
something with a different mnemonic (ie what the command does).

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-30 23:49 ` Bastien
@ 2007-10-30 23:03   ` Lennart Borgman (gmail)
  2007-10-31  2:29     ` Bastien
  0 siblings, 1 reply; 16+ messages in thread
From: Lennart Borgman (gmail) @ 2007-10-30 23:03 UTC (permalink / raw)
  To: Bastien; +Cc: help-gnu-emacs

Bastien wrote:
> "Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:
> 
>> In org-mode the functions that are bound to some keys are named after
>> the key binding, for example:
>>
>>   <M-left>        org-metaleft
>>
>> It might be helpful when developing, but it is not very helpful to the
>> user. It would be nice of the name of those commands where changed to
>> something with a different mnemonic (ie what the command does).
> 
> This kind of functions take different actions depending on the context.
> So picking up more readable names for them is tricky.
> 
> See the docstring of `org-metaleft':
> 
> ,----[ (org-metaleft &optional arg) ]
> | Promote heading or move table column to left.
> | Calls `org-do-promote' or `org-table-move-column', depending on context.
> | With no specific context, calls the Emacs default `backward-word'.
> | See the individual commands for more information.
> `----
> 
> I cannot think of a better name.  What would you propose?

It does not have to be short. It should rather be descriptive IMO.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-30 21:16 org-mode, please change the name of function org-metaleft etc Lennart Borgman (gmail)
@ 2007-10-30 23:49 ` Bastien
  2007-10-30 23:03   ` Lennart Borgman (gmail)
  2007-10-31  7:47 ` Richard Stallman
  1 sibling, 1 reply; 16+ messages in thread
From: Bastien @ 2007-10-30 23:49 UTC (permalink / raw)
  To: help-gnu-emacs

"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:

> In org-mode the functions that are bound to some keys are named after
> the key binding, for example:
>
>   <M-left>        org-metaleft
>
> It might be helpful when developing, but it is not very helpful to the
> user. It would be nice of the name of those commands where changed to
> something with a different mnemonic (ie what the command does).

This kind of functions take different actions depending on the context.
So picking up more readable names for them is tricky.

See the docstring of `org-metaleft':

,----[ (org-metaleft &optional arg) ]
| Promote heading or move table column to left.
| Calls `org-do-promote' or `org-table-move-column', depending on context.
| With no specific context, calls the Emacs default `backward-word'.
| See the individual commands for more information.
`----

I cannot think of a better name.  What would you propose?

-- 
Bastien

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-30 23:03   ` Lennart Borgman (gmail)
@ 2007-10-31  2:29     ` Bastien
  0 siblings, 0 replies; 16+ messages in thread
From: Bastien @ 2007-10-31  2:29 UTC (permalink / raw)
  To: help-gnu-emacs

"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:

>> See the docstring of `org-metaleft':
>>
>> ,----[ (org-metaleft &optional arg) ]
>> | Promote heading or move table column to left.
>> | Calls `org-do-promote' or `org-table-move-column', depending on context.
>> | With no specific context, calls the Emacs default `backward-word'.
>> | See the individual commands for more information.
>> `----
>>
>> I cannot think of a better name.  What would you propose?
>
> It does not have to be short. It should rather be descriptive IMO.

org-do-promote-or-table-move-left-or-backward-word ?!

I do understand the current name of the function is not very helpful,
but if a user want to know more about this defun, it's likely he will
look for the docstring instead, no?

-- 
Bastien

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-30 21:16 org-mode, please change the name of function org-metaleft etc Lennart Borgman (gmail)
  2007-10-30 23:49 ` Bastien
@ 2007-10-31  7:47 ` Richard Stallman
  2007-10-31 14:57   ` Lennart Borgman (gmail)
                     ` (2 more replies)
  1 sibling, 3 replies; 16+ messages in thread
From: Richard Stallman @ 2007-10-31  7:47 UTC (permalink / raw)
  To: Lennart Borgman (gmail); +Cc: dominik, emacs-devel

    In org-mode the functions that are bound to some keys are named after 
    the key binding, for example:

       <M-left>        org-metaleft

M-left is a basic cursor motion key which runs backward-word.
It is not good for any major mode to rebind such keys,
unless the new binding is a sort of extension or adaptation
of the standard binding.  It is hard to see how backward-word
could require any adaptation to a given major mode.

What's up here?

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31  7:47 ` Richard Stallman
@ 2007-10-31 14:57   ` Lennart Borgman (gmail)
  2007-10-31 15:37     ` Andreas Schwab
                       ` (3 more replies)
  2007-10-31 16:25   ` Bastien
  2007-11-04  7:29   ` Carsten Dominik
  2 siblings, 4 replies; 16+ messages in thread
From: Lennart Borgman (gmail) @ 2007-10-31 14:57 UTC (permalink / raw)
  To: rms; +Cc: dominik, emacs-devel

Richard Stallman wrote:
>     In org-mode the functions that are bound to some keys are named after 
>     the key binding, for example:
> 
>        <M-left>        org-metaleft
> 
> M-left is a basic cursor motion key which runs backward-word.
> It is not good for any major mode to rebind such keys,
> unless the new binding is a sort of extension or adaptation
> of the standard binding.  It is hard to see how backward-word
> could require any adaptation to a given major mode.
> 
> What's up here?

Several things it seems to me.

* First your remark that M-left runs backward-word. I have never noticed 
that, since backward-word is also on C-left. C-left is what is used for 
backward word moving on w32 in virtually all applications.

So if you have experience from w32 you expect C-left to run 
backward-word. I do not know about other systems, but what be glad to 
learn. Can someone comment, please?

Personally I see no reason to have backward-word on M-left too, but I 
guess it is there for historical reason. However it takes up a valuable 
binding.

* Second, the (info "(elisp) Key Binding Conventions") says nothing 
about the arrow keys.

* Then it was my proposal to change the name of functions like 
org-metaleft. The description of org-metaleft is

   (org-metaleft &optional arg)

   Promote heading or move table column to left.
   Calls `org-do-promote' or `org-table-move-column', depending on
   context.
   With no specific context, calls the Emacs default `backward-word'.
   See the individual commands for more information.

The function name does not describe what it does. It is of course, as 
Bastien pointed out, quite hard to name this function after that ...

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 14:57   ` Lennart Borgman (gmail)
@ 2007-10-31 15:37     ` Andreas Schwab
  2007-10-31 16:32     ` Jason Rumney
                       ` (2 subsequent siblings)
  3 siblings, 0 replies; 16+ messages in thread
From: Andreas Schwab @ 2007-10-31 15:37 UTC (permalink / raw)
  To: Lennart Borgman (gmail); +Cc: emacs-devel, rms, dominik

"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:

> Personally I see no reason to have backward-word on M-left too, but I
> guess it is there for historical reason. However it takes up a valuable
> binding.

M-left is the traditional binding.  C-left is not available on many
terminals.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31  7:47 ` Richard Stallman
  2007-10-31 14:57   ` Lennart Borgman (gmail)
@ 2007-10-31 16:25   ` Bastien
  2007-11-04  7:29   ` Carsten Dominik
  2 siblings, 0 replies; 16+ messages in thread
From: Bastien @ 2007-10-31 16:25 UTC (permalink / raw)
  To: emacs-devel

Richard Stallman <rms@gnu.org> writes:

>     In org-mode the functions that are bound to some keys are named
>     after the key binding, for example:
>
>        <M-left>        org-metaleft
>
> M-left is a basic cursor motion key which runs backward-word.
> It is not good for any major mode to rebind such keys,
> unless the new binding is a sort of extension or adaptation
> of the standard binding.  It is hard to see how backward-word
> could require any adaptation to a given major mode.
>
> What's up here?

Just a few remarks:

1. `org-metaleft' falls back on `backward-word' in the vaste majority of
   cases.  It calls the two other commands only when the point is at a
   table or a subtree -- so no surprise for the user.

2. the historical key for `backward-word' (M-b) remains unchanged.

3. this rebinding doesn't seem conceptually different to the one
   affecting the C-a key in message-mode: `message-beginning-of-line'
   redefines `beginning-of-line' so that the command is aware of the
   implicit field the line may contain.

4. the way Org handles all the commands associated with the arrow keys
   is very coherent; changing one binding among arrow keys commands may
   affect the whole equilibrum.

-- 
Bastien

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 14:57   ` Lennart Borgman (gmail)
  2007-10-31 15:37     ` Andreas Schwab
@ 2007-10-31 16:32     ` Jason Rumney
  2007-10-31 18:34       ` Bastien
  2007-10-31 16:47     ` Bastien
  2007-10-31 23:58     ` Richard Stallman
  3 siblings, 1 reply; 16+ messages in thread
From: Jason Rumney @ 2007-10-31 16:32 UTC (permalink / raw)
  To: Lennart Borgman (gmail); +Cc: emacs-devel, rms, dominik

Lennart Borgman (gmail) wrote:
> The function name does not describe what it does. It is of course, as
> Bastien pointed out, quite hard to name this function after that ...

I'd suggest org-electric-left as better than org-metaleft. The word
electric is used in other commands that act differently according to
context, and it does not tie it to a specific key binding.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 14:57   ` Lennart Borgman (gmail)
  2007-10-31 15:37     ` Andreas Schwab
  2007-10-31 16:32     ` Jason Rumney
@ 2007-10-31 16:47     ` Bastien
  2007-10-31 23:58     ` Richard Stallman
  3 siblings, 0 replies; 16+ messages in thread
From: Bastien @ 2007-10-31 16:47 UTC (permalink / raw)
  To: emacs-devel

"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:

>   (org-metaleft &optional arg)
>
>   Promote heading or move table column to left.
>
> The function name does not describe what it does. It is of course, as
> Bastien pointed out, quite hard to name this function after that ...

What does this function really?  It operates the action bound to
M-<left> according to the context.  So an appropriate name might 
be something like `org-contextual-metaleft'.

I think using `org-metaleft' instead of `org-contextual-metaleft'
is not that confusing, especially because the docstring is clear.

Finding the right level of "description" when naming contextual
commands is tricky, `org-metaleft' isn't a bad trade-off.

-- 
Bastien

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 18:34       ` Bastien
@ 2007-10-31 17:43         ` Lennart Borgman (gmail)
  0 siblings, 0 replies; 16+ messages in thread
From: Lennart Borgman (gmail) @ 2007-10-31 17:43 UTC (permalink / raw)
  To: Bastien; +Cc: emacs-devel, dominik, Jason Rumney

Bastien wrote:
> Jason Rumney <jasonr@gnu.org> writes:
> 
>> Lennart Borgman (gmail) wrote:
>>> The function name does not describe what it does. It is of course, as
>>> Bastien pointed out, quite hard to name this function after that ...
>> I'd suggest org-electric-left as better than org-metaleft. The word
>> electric is used in other commands that act differently according to
>> context, and it does not tie it to a specific key binding.
> 
> A simple M-x occur on org.el gives:
> 
>   25151:(defun org-shiftmetaleft ()
>   25198:(defun org-metaleft (&optional arg)
>   25283:(defun org-shiftleft ()
>   25301:(defun org-shiftcontrolleft ()
> 
> I guess `org-electric-left' won't be descriptive enough, even if it is a
> good start.

Maybe I should explain my original concern a bit better. If you do

   C-h f org-mode RET

you will see a long list of key bindings and function names like those 
we are discussing. If the function names where written with `', like

   <M-left>        `org-metaleft'

then you could at least click on the function names directly to get more 
information. How about that?

(The list of key bindings is inserted through \\{org-mode-map} in 
org-mode doc string.)

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 16:32     ` Jason Rumney
@ 2007-10-31 18:34       ` Bastien
  2007-10-31 17:43         ` Lennart Borgman (gmail)
  0 siblings, 1 reply; 16+ messages in thread
From: Bastien @ 2007-10-31 18:34 UTC (permalink / raw)
  To: Jason Rumney; +Cc: dominik, Lennart Borgman (gmail), emacs-devel

Jason Rumney <jasonr@gnu.org> writes:

> Lennart Borgman (gmail) wrote:
>> The function name does not describe what it does. It is of course, as
>> Bastien pointed out, quite hard to name this function after that ...
>
> I'd suggest org-electric-left as better than org-metaleft. The word
> electric is used in other commands that act differently according to
> context, and it does not tie it to a specific key binding.

A simple M-x occur on org.el gives:

  25151:(defun org-shiftmetaleft ()
  25198:(defun org-metaleft (&optional arg)
  25283:(defun org-shiftleft ()
  25301:(defun org-shiftcontrolleft ()

I guess `org-electric-left' won't be descriptive enough, even if it is a
good start.

-- 
Bastien

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 14:57   ` Lennart Borgman (gmail)
                       ` (2 preceding siblings ...)
  2007-10-31 16:47     ` Bastien
@ 2007-10-31 23:58     ` Richard Stallman
  2007-11-01  1:08       ` Jason Rumney
  2007-11-03 20:48       ` Stephen J. Turnbull
  3 siblings, 2 replies; 16+ messages in thread
From: Richard Stallman @ 2007-10-31 23:58 UTC (permalink / raw)
  To: Lennart Borgman (gmail); +Cc: emacs-devel, dominik

    Personally I see no reason to have backward-word on M-left too, but I 
    guess it is there for historical reason. However it takes up a valuable 
    binding.

It is there because of the Emacs convention that word commands use M-.

    * Then it was my proposal to change the name of functions like 
    org-metaleft. The description of org-metaleft is

       (org-metaleft &optional arg)

       Promote heading or move table column to left.
       Calls `org-do-promote' or `org-table-move-column', depending on
       context.

Maybe it is valid to consider that a variant of backward-word.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 23:58     ` Richard Stallman
@ 2007-11-01  1:08       ` Jason Rumney
  2007-11-03 20:48       ` Stephen J. Turnbull
  1 sibling, 0 replies; 16+ messages in thread
From: Jason Rumney @ 2007-11-01  1:08 UTC (permalink / raw)
  To: rms; +Cc: dominik, Lennart Borgman (gmail), emacs-devel

Richard Stallman wrote:
> Maybe it is valid to consider that a variant of backward-word.
>   

In that case, perhaps org-electric-backward-word is a good name for the
command.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31 23:58     ` Richard Stallman
  2007-11-01  1:08       ` Jason Rumney
@ 2007-11-03 20:48       ` Stephen J. Turnbull
  1 sibling, 0 replies; 16+ messages in thread
From: Stephen J. Turnbull @ 2007-11-03 20:48 UTC (permalink / raw)
  To: rms; +Cc: dominik, Lennart Borgman (gmail), emacs-devel

Richard Stallman writes:

 >     Personally I see no reason to have backward-word on M-left too, but I 
 >     guess it is there for historical reason. However it takes up a valuable 
 >     binding.
 > 
 > It is there because of the Emacs convention that word commands use M-.

 >     * Then it was my proposal to change the name of functions like 
 >     org-metaleft. The description of org-metaleft is
 > 
 >        (org-metaleft &optional arg)
 > 
 >        Promote heading or move table column to left.
 >        Calls `org-do-promote' or `org-table-move-column', depending on
 >        context.
 > 
 > Maybe it is valid to consider that a variant of backward-word.

I disagree.  Motion commands move the cursor, whatever "cursor" means
in the context.  They don't change the appearance of the document.

Consider: how many people do you think will type C-h a back RET to
find commands that promote headers or move columns?  I think it will
be much easier to document this as an exception to the rule that if a
key invokes a character command, meta-izing the key invokes an
analogous word command.

(Speaking as an Emacs user, not as an XEmacs developer; I have no idea
what my colleagues will think.)

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: org-mode, please change the name of function org-metaleft etc
  2007-10-31  7:47 ` Richard Stallman
  2007-10-31 14:57   ` Lennart Borgman (gmail)
  2007-10-31 16:25   ` Bastien
@ 2007-11-04  7:29   ` Carsten Dominik
  2 siblings, 0 replies; 16+ messages in thread
From: Carsten Dominik @ 2007-11-04  7:29 UTC (permalink / raw)
  To: rms; +Cc: Lennart Borgman (gmail), emacs-devel


On  31Oct2007, at 8:47 AM, Richard Stallman wrote:

>     In org-mode the functions that are bound to some keys are named  
> after
>     the key binding, for example:
>
>        <M-left>        org-metaleft
>
> M-left is a basic cursor motion key which runs backward-word.
> It is not good for any major mode to rebind such keys,
> unless the new binding is a sort of extension or adaptation
> of the standard binding.  It is hard to see how backward-word
> could require any adaptation to a given major mode.
>
> What's up here?

The are context-sensitive commands in Org-mode.  In normal text, they
fall back to the default functionality of these keys, in this case  
backward-word.
In special contexts they do other things.  These commands are  
essential to
the functionality of Org-mode.

While I fully agree that a name telling what the command does would  
be very
useful, I cannot think of a good way to create one here.  Since there  
are
several contexts where the command behaves specially, a long name  
would be
needed to capture all of it.  Moreover, if I think of a new context  
where the command
should behave specially, I would have to change the name of the  
command to reflect
this.

- Carsten

^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2007-11-04  7:29 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-10-30 21:16 org-mode, please change the name of function org-metaleft etc Lennart Borgman (gmail)
2007-10-30 23:49 ` Bastien
2007-10-30 23:03   ` Lennart Borgman (gmail)
2007-10-31  2:29     ` Bastien
2007-10-31  7:47 ` Richard Stallman
2007-10-31 14:57   ` Lennart Borgman (gmail)
2007-10-31 15:37     ` Andreas Schwab
2007-10-31 16:32     ` Jason Rumney
2007-10-31 18:34       ` Bastien
2007-10-31 17:43         ` Lennart Borgman (gmail)
2007-10-31 16:47     ` Bastien
2007-10-31 23:58     ` Richard Stallman
2007-11-01  1:08       ` Jason Rumney
2007-11-03 20:48       ` Stephen J. Turnbull
2007-10-31 16:25   ` Bastien
2007-11-04  7:29   ` Carsten Dominik

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.