Merge from savannah/emacs-29

1978b603bc Make python-ts-mode's syntax-highlighting more standardized
99658346d1 ; Improve documentation of desktop.el in user manual
f7dc020212 Fix "Text is read-only" on backspacing initial Calc input
662d54775d Add a doc string to simple.el (bug#67355)
5a5e36d2aa ; Improve function documentation tips
86016d8ecd Mention "visual line" in user manual
4bb65ed77a ; * doc/lispref/minibuf.texi (Programmed Completion): Imp...
dfb3dcb404 Allow listing Emoji from a read-only buffer

# Conflicts:
#	lisp/calc/calc.el
#	lisp/international/emoji.el

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

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

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

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

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

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)

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)

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