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

[Vivek Dasmohapatra <vivek@etla.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.

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.

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, so now I must check for end-of-buffer
explicitly to see if this case has occurred.

> moved; in the second one it didn't.  So the return value looks OK to
> me, and I see that the implementation goes to some length to catch the
> first case and return zero.  (The doc string indeed is inaccurate.)

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.

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.