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

[Eli Zaretskii]

> Date: Sat, 16 May 2015 00:23:56 +0100 (BST)
> From: Vivek Dasmohapatra <vivek@etla.org>
> 
> In the elisp manual, (forward-line X) is described as returning
> the number of lines left to move if it cannot satisfy the caller's
> request to move forward X lines.
> 
> However, calling (forward-line 1) at the start of a line with
> no terminating newline (ie the incomplete final line in a buffer,
> if it is incomplete) returns 0.
> 
> Calling (forward-line 1) at the _end_ of such a line returns 1.
> 
> The docstring for forward line does say the following at the end:
> 
> “With positive N, a non-empty line at the end counts as one line
>   successfully moved (for the return value).”
> 
> I think this is surprising and inconsistent behaviour.

Why do you think it's inconsistent?  In the first case, the command
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 doesn't seem reasonable to me, especially given that the
> documentation starts with:
> 
> “Move N lines forward (backward if N is negative).
>   Precisely, if point is on line I, move to the start of line I + N
>   ("start of line" in the logical order).”

Again, the documentation could be made more accurate, but let's first
agree on the desirable behavior, okay?