From 502a7800319b468df7c6bfeac66498d44fcba390 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 7 Jul 2023 09:26:58 +0300 Subject: [PATCH] ; Improve documentation of 'vertical-motion' in ELisp manual * doc/lispref/positions.texi (Screen Lines): Improve the documentation of 'vertical-motion'. --- doc/lispref/positions.texi | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index d8115ac3ad3..e74a165b9ed 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -560,16 +560,23 @@ improve the performance of your code. @xref{Truncation, cache-long-scans}. @defun vertical-motion count &optional window cur-col This function moves point to the start of the screen line @var{count} screen lines down from the screen line containing point. If @var{count} -is negative, it moves up instead. - -The @var{count} argument can be a cons cell, @code{(@var{cols} -. @var{lines})}, instead of an integer. Then the function moves by -@var{lines} screen lines, and puts point @var{cols} columns from the -visual start of that screen line. Note that @var{cols} are counted -from the @emph{visual} start of the line; if the window is scrolled -horizontally (@pxref{Horizontal Scrolling}), the column on which point -will end is in addition to the number of columns by which the text is -scrolled. +is negative, it moves up instead. If @var{count} is zero, point moves +to the visual start of the current screen line. + +The @var{count} argument can be a cons cell, @w{@code{(@var{cols} +. @var{lines})}}, instead of an integer. Then the function moves by +@var{lines} screen lines, as described for @var{count} above, and puts +point @var{cols} columns from the visual start of that screen line. +The value of @var{cols} can be a float, and is interpreted in units of +the frame's canonical character width (@pxref{Frame Font}); this +allows specifying accurate horizontal position of point when the +target screen line uses variable fonts. Note that @var{cols} are +counted from the @emph{visual} start of the line; if the window is +scrolled horizontally (@pxref{Horizontal Scrolling}), the column where +point will end is in addition to the number of columns by which the +text is scrolled, and if the target line is a continuation line, its +leftmost column is considered column zero (unlike column-oriented +functions, @pxref{Columns}). The return value is the number of screen lines over which point was moved. The value may be less in absolute value than @var{count} if -- 2.39.2