org-mode, please change the name of function org-metaleft etc

org-mode, please change the name of function org-metaleft etc

[Lennart Borgman (gmail)]

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

Re: org-mode, please change the name of function org-metaleft etc

[Lennart Borgman (gmail)]

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.

Re: org-mode, please change the name of function org-metaleft etc

[Bastien]

"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

Re: org-mode, please change the name of function org-metaleft etc

[Bastien]

"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

Re: org-mode, please change the name of function org-metaleft etc

[Richard Stallman]

    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?

Re: org-mode, please change the name of function org-metaleft etc

[Lennart Borgman (gmail)]

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

Re: org-mode, please change the name of function org-metaleft etc

[Andreas Schwab]

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

Re: org-mode, please change the name of function org-metaleft etc

[Bastien]

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

Re: org-mode, please change the name of function org-metaleft etc

[Jason Rumney]

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.

Re: org-mode, please change the name of function org-metaleft etc

[Bastien]

"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

Re: org-mode, please change the name of function org-metaleft etc

[Lennart Borgman (gmail)]

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

Re: org-mode, please change the name of function org-metaleft etc

[Bastien]

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

Re: org-mode, please change the name of function org-metaleft etc

[Richard Stallman]

    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.

Re: org-mode, please change the name of function org-metaleft etc

[Jason Rumney]

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.

Re: org-mode, please change the name of function org-metaleft etc

[Stephen J. Turnbull]

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

Re: org-mode, please change the name of function org-metaleft etc

[Carsten Dominik]

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