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

[Eli Zaretskii <eliz@gnu.org>]

> From: Andy Moreton <andrewjmoreton@gmail.com>
> Date: Thu, 02 Jun 2011 00:26:59 +0100
> 
> Having not looked at these functions previously, I found the doc strings
> to be essentially the same for both of them, which was confusing.

I can understand the confusion, given the deceptively simple idea of
"forward" and "back" in the unidirectional world.

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

Well, we could duplicate the description from the manual in the doc
string, if deemed useful.

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

Not "backward", but to the left.  "Forward" and "backward" are not
well-defined on the screen in bidirectional context.  For someone who
reads the bidirectional text, C-f always moves forward, i.e. in the
reading direction, the direction in which we scan characters while
reading the text.

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

This is misleading.  "Forward one position on the screen" is not well-
defined, so using it will confuse the reader.  Using "to the right"
instead is well-defined, but only _mostly_ correct, because there's no
pure right-to-left or left-to-right text.  Almost always there's some
left-to-right text (e.g., digits) embedded in predominantly
right-to-left text and vice versa.  (That's why the thing is called
"bidirectional".)  When you use right-char to move over left-to-right
characters embedded in otherwise right-to-left text, the cursor will
move to the left.  And that's even before we consider further
complications such as directional overrides (the RLE, RLO,
etc. control characters).

It would be more precise to tell that right-char will advance in the
buffer when used in a paragraph whose direction is left-to-right, but
will move backward in the buffer when used in a paragraph with
right-to-left direction.  But I'm not sure such a description will do
a better job, because explaining a simple idea such as cursor motion
via a much more complex issue of bidi-paragraph-direction doesn't
sound right.  By analogy, if you ask about laws wrt to traffic lights,
you will not be amused to first get a lecture about special relativity
theory that could potentially make the red light look green due to
Doppler effect.

> (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.
                                               ^^^^^^^^^^^
Should be "_to_the_left_"

> This is in contrast with right-char, which see.

I'm okay with this if it helps to make the issue less vague, but you
should realize that it is also inaccurate, because "left-to-right
text" is not well-defined.  There are "weak" and "neutral" characters
whose directionality is defined by surrounding strong directional
characters.  There are directional override control characters that
can override the intrinsic properties of the following characters.
Etc., etc. -- all these can invalidate the simple description above.