master 1737ffd3a83 5/6: Merge from savannah/emacs-29

[Po Lu]

branch: master
commit 1737ffd3a83b0d2fd4a114e9b5187d28d577dc38
Merge: cd263043538 1978b603bc3
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    Merge from savannah/emacs-29
    
    1978b603bc3 Make python-ts-mode's syntax-highlighting more standardized
    99658346d1e ; Improve documentation of desktop.el in user manual
    f7dc0202127 Fix "Text is read-only" on backspacing initial Calc input
    662d54775d5 Add a doc string to simple.el (bug#67355)
    5a5e36d2aad ; Improve function documentation tips
    86016d8ecdb Mention "visual line" in user manual
    4bb65ed77a8 ; * doc/lispref/minibuf.texi (Programmed Completion): Imp...
    dfb3dcb404c Allow listing Emoji from a read-only buffer
    
    # Conflicts:
    #       lisp/calc/calc.el
    #       lisp/international/emoji.el
---
 doc/emacs/basic.texi     | 25 ++++++++++++++-----------
 doc/emacs/display.texi   |  7 ++++---
 doc/emacs/misc.texi      |  5 ++++-
 doc/lispref/minibuf.texi |  3 +++
 doc/lispref/tips.texi    |  7 ++++++-
 lisp/calc/calc.el        |  2 +-
 lisp/progmodes/python.el |  6 +++---
 lisp/simple.el           |  4 ++++
 8 files changed, 39 insertions(+), 20 deletions(-)

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index a271cb65bdc..d41e5f2f16c 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -360,15 +360,15 @@ preserve the horizontal position, as usual.
 
 @vindex line-move-visual
   When a line of text in the buffer is longer than the width of the
-window, Emacs usually displays it on two or more @dfn{screen lines}.
-For convenience, @kbd{C-n} and @kbd{C-p} move point by screen lines,
-as do the equivalent keys @kbd{@key{down}} and @kbd{@key{up}}.  You
-can force these commands to move according to @dfn{logical lines}
-(i.e., according to the text lines in the buffer) by setting the
-variable @code{line-move-visual} to @code{nil}; if a logical line
-occupies multiple screen lines, the cursor then skips over the
-additional screen lines.  For details, see @ref{Continuation Lines}.
-@xref{Variables}, for how to set variables such as
+window, Emacs usually displays it on two or more @dfn{screen lines},
+a.k.a.@: @dfn{visual lines}.  For convenience, @kbd{C-n} and @kbd{C-p}
+move point by screen lines, as do the equivalent keys @kbd{@key{down}}
+and @kbd{@key{up}}.  You can force these commands to move according to
+@dfn{logical lines} (i.e., according to the text lines in the buffer)
+by setting the variable @code{line-move-visual} to @code{nil}; if a
+logical line occupies multiple screen lines, the cursor then skips
+over the additional screen lines.  For details, see @ref{Continuation
+Lines}.  @xref{Variables}, for how to set variables such as
 @code{line-move-visual}.
 
   Unlike @kbd{C-n} and @kbd{C-p}, most of the Emacs commands that work
@@ -596,10 +596,13 @@ lines, if any exists.
 @cindex wrapping
 @cindex line wrapping
 @cindex fringes, and continuation lines
+@cindex logical line
+@cindex screen line
+@cindex visual line
   Sometimes, a line of text in the buffer---a @dfn{logical line}---is
 too long to fit in the window, and Emacs displays it as two or more
-@dfn{screen lines}.  This is called @dfn{line wrapping} or
-@dfn{continuation}, and the long logical line is called a
+@dfn{screen lines}, or @dfn{visual lines}.  This is called @dfn{line
+wrapping} or @dfn{continuation}, and the long logical line is called a
 @dfn{continued line}.  On a graphical display, Emacs indicates line
 wrapping with small bent arrows in the left and right window fringes.
 On a text terminal, Emacs indicates line wrapping by displaying a
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index cc178dbe99f..d9da4c1335c 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -2010,9 +2010,10 @@ line truncation.  @xref{Split Window}, for the variable
 @section Visual Line Mode
 
 @cindex word wrap
-  Another alternative to ordinary line continuation is to use
-@dfn{word wrap}.  Here, each long logical line is divided into two or
-more screen lines, like in ordinary line continuation.  However, Emacs
+  Another alternative to ordinary line continuation
+(@pxref{Continuation Lines}) is to use @dfn{word wrap}.  Here, each
+long logical line is divided into two or more screen lines, or
+``visual lines'', like in ordinary line continuation.  However, Emacs
 attempts to wrap the line at word boundaries near the right window
 edge.  (If the line's direction is right-to-left, it is wrapped at the
 left window edge instead.)  This makes the text easier to read, as
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index d3c5712099d..eb197f738f5 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2851,8 +2851,11 @@ want it to preserve certain buffers, customize the 
variable
 @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
 expression matching the names of buffers not to kill.
 
+@vindex desktop-globals-to-save
   If you want to save minibuffer history from one session to
-another, use the @code{savehist} library.
+another, use the @code{savehist} library.  You can also save selected
+minibuffer-history variables as part of @code{desktop-save-mode} if
+you add those variables to the value of @code{desktop-globals-to-save}.
 
 @node Recursive Edit
 @section Recursive Editing Levels
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index be4d7e37261..ba7f1ca692e 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1985,6 +1985,7 @@ the piece of the prefix and suffix covered by the 
completion
 boundaries.  @xref{Basic Completion}, for the precise expected semantics
 of completion boundaries.
 
+@cindex completion metadata
 @item metadata
 This specifies a request for information about the state of the
 current completion.  The return value should have the form
@@ -2001,6 +2002,8 @@ The following is a list of metadata entries that a 
completion function
 may return in response to a @code{metadata} flag argument:
 
 @table @code
+@cindex @code{category}, in completion
+@cindex completion category
 @item category
 The value should be a symbol describing what kind of text the
 completion function is trying to complete.  If the symbol matches one
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 796eb80e066..4c9dcee37d8 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -631,7 +631,12 @@ first line with a capital letter and end it with a period.
 
 For a function, the first line should briefly answer the question,
 ``What does this function do?''  For a variable, the first line should
-briefly answer the question, ``What does this value mean?''
+briefly answer the question, ``What does this value mean?''  Prefer to
+answer these questions in a way that will make sense to users and
+callers of the function or the variable.  In particular, do @emph{not}
+tell what the function does by enumerating the actions of its code;
+instead, describe the role of these actions and the function's
+contract.
 
 Don't limit the documentation string to one line; use as many lines as
 you need to explain the details of how to use the function or
diff --git a/lisp/calc/calc.el b/lisp/calc/calc.el
index b347cc1da23..41aeb17c252 100644
--- a/lisp/calc/calc.el
+++ b/lisp/calc/calc.el
@@ -2491,7 +2491,7 @@ the United States."
 (defun calcDigit-backspace ()
   (interactive)
   (cond ((eq last-command 'calcDigit-start)
-        (erase-buffer))
+        (delete-minibuffer-contents))
        (t (with-suppressed-warnings ((interactive-only backward-delete-char))
              (backward-delete-char 1))))
   (if (= (calc-minibuffer-size) 0)
diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index 1a797bb1a03..ab3bf1b4ec0 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -1235,7 +1235,7 @@ For NODE, OVERRIDE, START, END, and ARGS, see
   (when (python--treesit-variable-p node)
     (treesit-fontify-with-override
      (treesit-node-start node) (treesit-node-end node)
-     'font-lock-variable-name-face override start end)))
+     'font-lock-variable-use-face override start end)))
 
 
 ;;; Indentation
@@ -6842,8 +6842,8 @@ implementations: `python-mode' and `python-ts-mode'."
                 '(( comment definition)
                   ( keyword string type)
                   ( assignment builtin constant decorator
-                    escape-sequence number property string-interpolation )
-                  ( bracket delimiter function operator variable)))
+                    escape-sequence number string-interpolation )
+                  ( bracket delimiter function operator variable property)))
     (setq-local treesit-font-lock-settings python--treesit-settings)
     (setq-local imenu-create-index-function
                 #'python-imenu-treesit-create-index)
diff --git a/lisp/simple.el b/lisp/simple.el
index 2e2d73e9bf4..02c68912dba 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -11085,6 +11085,10 @@ If the buffer doesn't exist, create it first."
   (pop-to-buffer-same-window (get-scratch-buffer-create)))
 
 (defun kill-buffer--possibly-save (buffer)
+  "Ask the user to confirm killing of a modified BUFFER.
+
+If the user confirms, optionally save BUFFER that is about to be
+killed."
   (let ((response
          (cadr
           (read-multiple-choice