--- Begin Message ---
Subject: |
24.1 forward-line docs inconsistent/surprising return value |
Date: |
Sat, 16 May 2015 00:23:56 +0100 (BST) |
User-agent: |
Alpine 2.02 (DEB 1266 2009-07-14) |
In GNU Emacs 24.1.1 (x86_64-pc-linux-gnu, GTK+ Version 2.24.10)
of 2012-08-23 on noise, modified by Debian
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. 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).”
In any case, even if forward-line is not altered (I suppose it is
possible that this behaviour has been around for a long time, and
many things may depend on forward-line behaving in this manner),
the Info manual should be updated to match the docstring.
I also think the surprising behaviour is not clearly flagged: It is
part of a single lump of docstring text, and not flagged or highlighted
in any way (a simple extra blank line before its description, or a
"NOTE:" or similar would make it much easier to spot).
--- End Message ---
--- Begin Message ---
Subject: |
Re: bug#20587: 24.1 forward-line docs inconsistent/surprising return value |
Date: |
Sat, 23 May 2015 11:05:43 +0300 |
> From: Eric Hanchrow <address@hidden>
> Date: Sat, 23 May 2015 03:26:45 +0000
>
> For what it's worth, my reaction was just the same as Vivek's:
>
> * The behavior of forward-line surprised me;
> * The docstring describes that behavior, albeit without IMHO drawing
> sufficient
> attention to its oddness;
> * The Elisp reference is clearly wrong.
I fixed the ELisp manual and tried to clarify in the doc string the
return value in this case.
Thanks.
--- End Message ---