Commit d6dfefe4 authored by Eli Zaretskii's avatar Eli Zaretskii

Fix documentation of forward-line

* src/cmds.c (Fforward_line): Clarify the return value if the line
at end of accessible portion of the buffer has no newline.
* doc/lispref/positions.texi (Text Lines): Document what happens
if the line at end of accessible portion of buffer has no newline.

(Bug#20587)
parent a89ea17b
......@@ -350,10 +350,11 @@ would move to.
@deffn Command forward-line &optional count
@cindex beginning of line
This function moves point forward @var{count} lines, to the beginning of
the line. If @var{count} is negative, it moves point
@minus{}@var{count} lines backward, to the beginning of a line. If
@var{count} is zero, it moves point to the beginning of the current
line. If @var{count} is @code{nil}, that means 1.
the line following that. If @var{count} is negative, it moves point
@minus{}@var{count} lines backward, to the beginning of a line
preceding that. If @var{count} is zero, it moves point to the
beginning of the current line. If @var{count} is @code{nil}, that
means 1.
If @code{forward-line} encounters the beginning or end of the buffer (or
of the accessible portion) before finding that many lines, it sets point
......@@ -362,7 +363,11 @@ there. No error is signaled.
@code{forward-line} returns the difference between @var{count} and the
number of lines actually moved. If you attempt to move down five lines
from the beginning of a buffer that has only three lines, point stops at
the end of the last line, and the value will be 2.
the end of the last line, and the value will be 2. As an explicit
exception, if the last accessible line is non-empty, but has no
newline (e.g., if the buffer ends without a newline), the function
sets point to the end of that line, and the value returned by the
function counts that line as one line successfully moved.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
......
......@@ -110,10 +110,17 @@ DEFUN ("forward-line", Fforward_line, Sforward_line, 0, 1, "^p",
Precisely, if point is on line I, move to the start of line I + N
\("start of line" in the logical order).
If there isn't room, go as far as possible (no error).
Returns the count of lines left to move. If moving forward,
that is N - number of lines moved; if backward, N + number moved.
With positive N, a non-empty line at the end counts as one line
successfully moved (for the return value). */)
that is N minus number of lines moved; if backward, N plus number
moved.
Exception: With positive N, a non-empty line at the end of the
buffer, or of its accessible portion, counts as one line
successfully moved (for the return value). This means that the
function will move point to the end of such a line and will count
it as a line moved across, even though there is no next line to
go to its beginning. */)
(Lisp_Object n)
{
ptrdiff_t opoint = PT, pos, pos_byte, shortage, count;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment