master ff89d27c07: Merge from origin/emacs-28

[Stefan Kangas]

branch: master
commit ff89d27c07de4ac2efc695b06e8aa1faec5d65d1
Merge: a96f6de544 530c3491e8
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    Merge from origin/emacs-28
    
    530c3491e8 Improve documentation of bookmark default sorting
    11492259b1 ; * doc/lispref/display.texi (Overlay Arrow): More accurat...
---
 doc/lispref/display.texi | 18 ++++++++++--------
 lisp/bookmark.el         | 18 +++++++++++-------
 2 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 95e00e140d..3aec06e13d 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4642,14 +4642,15 @@ about to be executed.  This feature has nothing to do 
with
 @defvar overlay-arrow-string
 This variable holds the string to display to call attention to a
 particular line, or @code{nil} if the arrow feature is not in use.
-On a graphical display the contents of the string are ignored; instead a
-glyph is displayed in the fringe area to the left of the display area.
+On a graphical display the contents of the string are ignored if the
+left fringe is shown; instead a glyph is displayed in the fringe area
+to the left of the display area.
 @end defvar
 
 @defvar overlay-arrow-position
 This variable holds a marker that indicates where to display the overlay
 arrow.  It should point at the beginning of a line.  On a non-graphical
-display the arrow text
+display, or when the left fringe is not shown, the arrow text
 appears at the beginning of that line, overlaying any text that would
 otherwise appear.  Since the arrow is usually short, and the line
 usually begins with indentation, normally nothing significant is
@@ -4681,11 +4682,12 @@ this list.
 
 Each variable on this list can have properties
 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
-specify an overlay arrow string (for text terminals) or fringe bitmap
-(for graphical terminals) to display at the corresponding overlay
-arrow position.  If either property is not set, the default
-@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
-is used.
+specify an overlay arrow string (for text terminals or graphical
+terminals without the left fringe shown) or fringe bitmap
+(for graphical terminals with a left fringe) to display at the
+corresponding overlay arrow position.  If either property is not set,
+the default @code{overlay-arrow-string} or @code{overlay-arrow} fringe
+indicator is used.
 
 
 @node Scroll Bars
diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 80fb1cdfc7..e3baa7607d 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -246,11 +246,13 @@ functions have a binding in this keymap."
 Bookmark functions update the value automatically.
 You probably do NOT want to change the value yourself.
 
-The value is an alist with bookmarks of the form
+The value is an alist whose elements are of the form
 
  (BOOKMARK-NAME . PARAM-ALIST)
 
-or the deprecated form (BOOKMARK-NAME PARAM-ALIST).
+or the deprecated form (BOOKMARK-NAME PARAM-ALIST).  The alist is
+ordered from most recently created bookmark at the front to least
+recently created bookmark at the end.
 
 BOOKMARK-NAME is the name you gave to the bookmark when creating it.
 
@@ -583,10 +585,10 @@ old one."
           ;; Modify using the new (NAME . ALIST) format.
           (setcdr bm alist))
 
-      ;; otherwise just cons it onto the front (either the bookmark
-      ;; doesn't exist already, or there is no prefix arg.  In either
-      ;; case, we want the new bookmark consed onto the alist...)
-
+      ;; Otherwise just put it onto the front of the list.  Either the
+      ;; bookmark doesn't exist already, or there is no prefix arg.
+      ;; In either case, we want the new bookmark on the front of the
+      ;; list, since the list is kept in reverse order of creation.
       (push (cons stripped-name alist) bookmark-alist))
 
     ;; Added by db
@@ -1140,7 +1142,9 @@ it to the name of the bookmark currently being set, 
advancing
 
 (defun bookmark-maybe-sort-alist ()
   "Return `bookmark-alist' for display.
-If `bookmark-sort-flag' is non-nil, then return a sorted copy of the alist."
+If `bookmark-sort-flag' is non-nil, then return a sorted copy of the alist.
+Otherwise, just return `bookmark-alist', which by default is ordered
+from most recently created to least recently created bookmark."
   (if bookmark-sort-flag
       (sort (copy-alist bookmark-alist)
             (lambda (x y) (string-lessp (car x) (car y))))