From: Noam Postavsky <npostavs@gmail.com>
Date: Fri, 21 Aug 2020 13:08:27 +0000 (+0200)
Subject: Clarify docs about line movement
X-Git-Tag: emacs-28.0.90~6475
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=9d4b11132b7fb45a5804161e16cb9b71b7ac7d5d;p=emacs.git

Clarify docs about line movement

* doc/lispref/positions.texi (Text Lines, Screen Lines): Add index
entries.
* lisp/simple.el (move-beginning-of-line): Remove incorrect mention of
images, and reference beginning-of-visual-line.
* src/editfns.c (Fline_beginning_position): Reference
`vertical-motion' (bug#35899).
---

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index 91419702ca1..751adcff5a8 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -332,6 +332,8 @@ if provided; otherwise @var{n} defaults to @code{nil}.
 @node Text Lines
 @subsection Motion by Text Lines
 @cindex lines
+@cindex logical lines, moving by
+@cindex physical lines, moving by
 
   Text lines are portions of the buffer delimited by newline characters,
 which are regarded as part of the previous line.  The first text line
@@ -518,6 +520,7 @@ beginning or end of a line.
 @node Screen Lines
 @subsection Motion by Screen Lines
 @cindex screen lines, moving by
+@cindex visual lines, moving by
 
   The line functions in the previous section count text lines, delimited
 only by newline characters.  By contrast, these functions count screen
diff --git a/lisp/simple.el b/lisp/simple.el
index b106d4b0ba7..fa6e154004b 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -7021,15 +7021,16 @@ rests."
 	    (setq done t)))))))
 
 (defun move-beginning-of-line (arg)
-  "Move point to beginning of current line as displayed.
-\(If there's an image in the line, this disregards newlines
-that are part of the text that the image rests on.)
+  "Move point to visible beginning of current logical line.
+This disregards any invisible newline characters.
 
 With argument ARG not nil or 1, move forward ARG - 1 lines first.
 If point reaches the beginning or end of buffer, it stops there.
 \(But if the buffer doesn't end in a newline, it stops at the
 beginning of the last line.)
-To ignore intangibility, bind `inhibit-point-motion-hooks' to t."
+
+To ignore intangibility, bind `inhibit-point-motion-hooks' to t.
+For motion by visual lines, see `beginning-of-visual-line'."
   (interactive "^p")
   (or arg (setq arg 1))
 
diff --git a/src/editfns.c b/src/editfns.c
index cb09ea8a31a..949f3825a3c 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -707,7 +707,8 @@ If the scan reaches the end of the buffer, return that position.
 
 This function ignores text display directionality; it returns the
 position of the first character in logical order, i.e. the smallest
-character position on the line.
+character position on the logical line.  See `vertical-motion' for
+movement by screen lines.
 
 This function constrains the returned position to the current field
 unless that position would be on a different line from the original,