master 9d4b111 3/3: Clarify docs about line movement

[Lars Ingebrigtsen]

branch: master
commit 9d4b11132b7fb45a5804161e16cb9b71b7ac7d5d
Author: Noam Postavsky <npostavs@gmail.com>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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).
---
 doc/lispref/positions.texi | 3 +++
 lisp/simple.el             | 9 +++++----
 src/editfns.c              | 3 ++-
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index 9141970..751adcf 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 b106d4b..fa6e154 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 cb09ea8..949f382 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,