bug#20587: 24.1 forward-line docs inconsistent/surprising return value

[Eli Zaretskii]

> Date: Sat, 16 May 2015 11:07:03 +0100 (BST)
> From: Vivek Dasmohapatra <vivek@etla.org>
> cc: 20587@debbugs.gnu.org
> 
> > Why do you think it's inconsistent?  In the first case, the command
> 
> It strikes me as inconsistent because of this:
> 
> >>   Precisely, if point is on line I, move to the start of line I + N
>                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> And it is precisely this which it has not been able to do.

You are again talking about the doc string.  Let's first talk about
what it should return in this case.  If it returns 1, it would mean it
didn't move, and you'd expect it to be at the beginning of the last
line, not at its end.

IOW, the function moved as far as it could, since there's no next line
in this case.

> Take the example of a case where I wish to move N lines forward
> to leave a gap of N lines before I insert some text, and I use
> the return value of forward-line to check how far I have moved.

You can always test eob to see if this is the case.  It's a special
case anyway.

> On an incomplete last line with an N of 1, forward-line will return 0,
> indicating that it has satisfied my request to move to the start of
> line I + 1, when in fact it has not

But it did move.  Returning zero would mean it didn't, or would be
indistinguishable from the case it didn't.

> It did not do that. It moved to the end of line I, not the start of
> line I + 1.
> 
> That's the part I find surprising.

That's the only logical thing to do in that case.

> It may be that the behaviour is so ancient that it cannot be altered 
> without breaking things: I wouldn't push for the behaviour change in
> that case. But I think the special case should be more clearly flagged
> and stated.

If we agree about the behavior, I can change the doc string.  That's
easy enough.