Re: `C-b' is backward-char, `left' is left-char - why?

[Andy Moreton]

On Wed 01 Jun 2011, Eli Zaretskii wrote:

>> From: Andy Moreton <address@hidden> Date: Wed, 01 Jun 2011
>> 12:48:15 +0100
>> 
>> The help strings for 'left-char and 'backward-char could use some
>> work. It is unclear which moves according to screen display order and
>> which moves according to buffer character order.
>
> I don't feel a need to invest "some work" on the doc string of
> `backward-char', because that function has not changed in ages,
> certainly not now. If its doc string is unclear, then I wonder how did
> we all manage to use it all these years.
>
> Of course, I don't object if someone wants to work on that doc string.

Having not looked at these functions previously, I found the doc strings
to be essentially the same for both of them, which was confusing.

> Regarding `left-char' and `right-char', the doc string says:
>
>   Depending on the bidirectional context, this may move either
>   backward or forward in the buffer.
>
> Believe it or not, but I tried to make it more precise for a long
> time, and this is the best I could come up with. There's a slightly
> different variant in the Emacs manual, maybe you will like it better.
> But both are not 100% accurate, because explaining what exactly it
> does would take a very long text that has no place in a doc string.

Having looked at the manual, I think the description there of <left> and
<right> does a better job of explaining what happens in bidi enabled
text than the doc strings. Given that a negative argument produces
movement in the opposite direction, I understand the difficulty of
explaining things.

> If, after playing with the function in bidirectional context, you have
> suggestions for describing it better, please propose the change in the
> doc string that you think would make it more clear.

If I understand things correctly the for N=1 (or omitted):

 - forward-char moves forward one character in the buffer, which in
   right-to-left text moves backward one position on the screen.

 - right-char moves forward one position on the screen, which in
   right-to-left text moves backward one character in the buffer.

 - backward-char moves backward one character in the buffer, which in
   right-to-left text moves forward one position on the screen.

 - left-char moves backward one position on the screen, which in
   right-to-left text moves forward one character in the buffer.

If so, is this attempt any better ?

--8<---------------cut here---------------start------------->8---
(forward-char &optional N)

Move point N characters forward (backward if N is negative).
On reaching end or beginning of buffer, stop and signal error.

Movement on the screen depends on the bidirectional context. Moving
forward over left-to-right text moves to the right on the screen, but
moving forward over right-to-left text moves _backward_ on the screen.
This is in contrast with right-char, which see.
--8<---------------cut here---------------end--------------->8---

    AndyM