From d6dfefe40528a6a9ab6d0cbc5f1a450075241141 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 23 May 2015 11:03:30 +0300 Subject: [PATCH] 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) --- doc/lispref/positions.texi | 15 ++++++++++----- src/cmds.c | 13 ++++++++++--- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index e7c79d58241..c972bbb2e43 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -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 diff --git a/src/cmds.c b/src/cmds.c index b590805ea8a..6f9982eebb2 100644 --- a/src/cmds.c +++ b/src/cmds.c @@ -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; -- 2.39.2