master 6c367f0ad4b 7/9: Merge from origin/emacs-29

[Eli Zaretskii]

branch: master
commit 6c367f0ad4bc77152b50644933b1169f0f62bd03
Merge: 703b9c8d24e 232a57a3e32
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge from origin/emacs-29
    
    232a57a3e32 ; * doc/lispref/debugging.texi (Debugging): Add cross-ref...
    c65ddf26a33 ; doc/lispref/debugging.texi: Add reference to Profiler d...
    6f884d3aed9 Add 5 docstrings to abbrev.el (bug#67153)
    b4d990bd637 ; Clarify wording about arguments in doc strings
    c20ae7a30fb ; Improve cross-references in description of 'pcase'
    42181b65df1 ; * src/editfns.c (Fline_beginning_position): Doc fix.
    5f3309f6b0f ; Improve indexing in ELisp manual
    4e406bb4208 Fix CBZ file detection in doc-view-mode
---
 doc/lispref/control.texi   |  7 ++++++-
 doc/lispref/debugging.texi |  6 ++++--
 doc/lispref/tips.texi      | 19 ++++++++++++++-----
 lisp/abbrev.el             | 39 ++++++++++++++++++++++++++++++++++++---
 lisp/doc-view.el           |  2 +-
 src/editfns.c              |  1 +
 6 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 2d2b8da7325..d4bd8c14ae3 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -598,6 +598,10 @@ Two symbols to avoid are @code{t}, which behaves like 
@code{_}
 Likewise, it makes no sense to bind keyword symbols
 (@pxref{Constant Variables}).
 
+@item `@var{qpat}
+A backquote-style pattern.  @xref{Backquote Patterns}, for the
+details.
+
 @item (cl-type @var{type})
 Matches if @var{expval} is of type @var{type}, which is a type
 descriptor as accepted by @code{cl-typep} (@pxref{Type Predicates,,,cl,Common
@@ -1236,7 +1240,8 @@ The first three clauses use backquote-style patterns.
 @code{`(add ,x ,y)} is a pattern that checks that @code{form}
 is a three-element list starting with the literal symbol @code{add},
 then extracts the second and third elements and binds them
-to symbols @code{x} and @code{y}, respectively.
+to symbols @code{x} and @code{y}, respectively.  This is known as
+@dfn{destructuring}, see @ref{Destructuring with pcase Patterns}.
 The clause body evaluates @code{x} and @code{y} and adds the results.
 Similarly, the @code{call} clause implements a function call,
 and the @code{fn} clause implements an anonymous function definition.
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 1246b3ff57a..57ed5806855 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -13,11 +13,12 @@ Lisp program.
 @itemize @bullet
 @item
 If a problem occurs when you run the program, you can use the built-in
-Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or
-alter its internal state.
+Emacs Lisp debugger (@pxref{Debugger}) to suspend the Lisp evaluator,
+and examine and/or alter its internal state.
 
 @item
 You can use Edebug, a source-level debugger for Emacs Lisp.
+@xref{Edebug}.
 
 @item
 @cindex tracing Lisp programs
@@ -47,6 +48,7 @@ You can use the ERT package to write regression tests for the 
program.
 
 @item
 You can profile the program to get hints about how to make it more efficient.
+@xref{Profiling}.
 @end itemize
 
   Other useful tools for debugging input and output problems are the
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 81a5e1688fd..796eb80e066 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -43,6 +43,7 @@ in batch mode, e.g., with a command run by @kbd{@w{M-x compile
 @section Emacs Lisp Coding Conventions
 
 @cindex coding conventions in Emacs Lisp
+@cindex conventions for Emacs Lisp programs
   Here are conventions that you should follow when writing Emacs Lisp
 code intended for widespread use:
 
@@ -264,6 +265,7 @@ which are lists of directory names.
 @node Key Binding Conventions
 @section Key Binding Conventions
 @cindex key binding, conventions for
+@cindex conventions for key bindings
 
 @itemize @bullet
 @item
@@ -345,6 +347,7 @@ after @key{ESC}.  In these states, you should define 
@kbd{@key{ESC}
 @node Programming Tips
 @section Emacs Programming Tips
 @cindex programming conventions
+@cindex conventions for Emacs programming
 
   Following these conventions will make your program fit better
 into Emacs when it runs.
@@ -477,6 +480,7 @@ buffer and let the user switch back at will.  
@xref{Recursive Editing}.
 @section Tips for Making Compiled Code Fast
 @cindex execution speed
 @cindex speedups
+@cindex tips for faster Lisp code
 
   Here are ways of improving the execution speed of byte-compiled
 Lisp programs.
@@ -531,6 +535,7 @@ the speed.  @xref{Inline Functions}.
 @node Warning Tips
 @section Tips for Avoiding Compiler Warnings
 @cindex byte compiler warnings, how to avoid
+@cindex warnings from byte compiler
 
 @itemize @bullet
 @item
@@ -585,6 +590,8 @@ is to put it inside @code{with-no-warnings}.  
@xref{Compiler Errors}.
 @node Documentation Tips
 @section Tips for Documentation Strings
 @cindex documentation strings, conventions and tips
+@cindex tips for documentation strings
+@cindex conventions for documentation strings
 
 @findex checkdoc-minor-mode
   Here are some tips and conventions for the writing of documentation
@@ -638,11 +645,11 @@ include before the first blank line so as to make this 
display useful.
 
 @item
 The first line should mention all the important arguments of the
-function, and should mention them in the order that they are written
-in a function call.  If the function has many arguments, then it is
-not feasible to mention them all in the first line; in that case, the
-first line should mention the first few arguments, including the most
-important arguments.
+function (in particular, the mandatory arguments), and should mention
+them in the order that they are written in a function call.  If the
+function has many arguments, then it is not feasible to mention them
+all in the first line; in that case, the first line should mention the
+first few arguments, including the most important arguments.
 
 @item
 When a function's documentation string mentions the value of an argument
@@ -915,6 +922,7 @@ versions, there is no need for this work-around.
 @node Comment Tips
 @section Tips on Writing Comments
 @cindex comments, Lisp convention for
+@cindex conventions for Lisp comments
 
   We recommend these conventions for comments:
 
@@ -1030,6 +1038,7 @@ semicolons.
 @section Conventional Headers for Emacs Libraries
 @cindex header comments
 @cindex library header comments
+@cindex conventions for library header comments
 
   Emacs has conventions for using special comments in Lisp libraries
 to divide them into sections and give information such as who wrote
diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index 1a665efb0a5..e916cf25bf0 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -122,6 +122,9 @@ Otherwise display all the abbrevs."
     found))
 
 (defun prepare-abbrev-list-buffer (&optional local)
+  "Return buffer listing abbreviations and expansions for each abbrev table.
+
+If LOCAL is non-nil, include in the buffer only the local abbrevs."
   (let ((local-table local-abbrev-table))
     (with-current-buffer (get-buffer-create "*Abbrevs*")
       (erase-buffer)
@@ -333,6 +336,20 @@ Don't use this function in a Lisp program; use 
`define-abbrev' instead."
   (add-abbrev global-abbrev-table "Global" arg))
 
 (defun add-abbrev (table type arg)
+  "Define abbrev in TABLE, whose expansion is ARG words before point.
+Read the abbreviation from the minibuffer, with prompt TYPE.
+
+ARG of zero means the entire region is the expansion.
+
+A negative ARG means to undefine the specified abbrev.
+
+TYPE is an arbitrary string used to prompt user for the kind of
+abbrev, such as \"Global\", \"Mode\".  (This has no influence on the
+choice of the actual TABLE).
+
+See `inverse-add-abbrev' for the opposite task.
+
+Don't use this function in a Lisp program; use `define-abbrev' instead."
   (let ((exp
          (cond
           ((or (and (null arg) (use-region-p))
@@ -353,7 +370,7 @@ Don't use this function in a Lisp program; use 
`define-abbrev' instead."
     (if (or (null exp)
            (not (abbrev-expansion name table))
            (y-or-n-p (format "%s expands into \"%s\"; redefine? "
-                             name (abbrev-expansion name table))))
+                              name (abbrev-expansion name table))))
        (define-abbrev table (downcase name) exp))))
 
 (defun inverse-add-mode-abbrev (n)
@@ -393,6 +410,19 @@ to define an abbrev by specifying the abbreviation in the 
minibuffer."
   (inverse-add-abbrev global-abbrev-table "Global" n))
 
 (defun inverse-add-abbrev (table type arg)
+  "Define the word before point as an abbrev in TABLE.
+Read the expansion from the minibuffer, using prompt TYPE, define
+the abbrev, and then expand the abbreviation in the current
+buffer.
+
+ARG means use the ARG-th word before point as the abbreviation.
+Negative ARG means use the ARG-th word after point.
+
+TYPE is an arbitrary string used to prompt user for the kind of
+abbrev, such as \"Global\", \"Mode\".  (This has no influence on the
+choice of the actual TABLE).
+
+See also `add-abbrev', which performs the opposite task."
   (let (name exp start end)
     (save-excursion
       (forward-word (1+ (- arg)))
@@ -1102,6 +1132,8 @@ Presumes that `standard-output' points to 
`current-buffer'."
   (insert ")\n"))
 
 (defun abbrev--describe (sym)
+  "Describe abbrev SYM.
+Print on `standard-output' the abbrev, count of use, expansion."
   (when (symbol-value sym)
     (prin1 (symbol-name sym))
     (if (null (abbrev-get sym :system))
@@ -1243,11 +1275,12 @@ which see."
   (setq font-lock-multiline nil))
 
 (defun abbrev--possibly-save (query &optional arg)
+  "Hook function for use by `save-some-buffer-functions'.
+
+Maybe save abbrevs, and record whether we either saved them or asked to."
   ;; Query mode.
   (if (eq query 'query)
       (and save-abbrevs abbrevs-changed)
-    ;; Maybe save abbrevs, and record whether we either saved them or
-    ;; asked to.
     (and save-abbrevs
          abbrevs-changed
          (prog1
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index fb51661caac..2fdb49f3e42 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -2133,7 +2133,7 @@ GOTO-PAGE-FN other than `doc-view-goto-page'."
             ;; zip-archives, so that this same association is used for
             ;; cbz files. This is fine, as cbz files should be handled
             ;; like epub anyway.
-            ((looking-at "PK") '(epub odf))))))
+            ((looking-at "PK") '(epub odf cbz))))))
     (setq-local
      doc-view-doc-type
      (car (or (nreverse (seq-intersection name-types content-types #'eq))
diff --git a/src/editfns.c b/src/editfns.c
index 1ea7931a3a7..49d552c4a75 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -727,6 +727,7 @@ This function does not move point.  Also see 
`line-beginning-position'.  */)
 DEFUN ("line-beginning-position",
        Fline_beginning_position, Sline_beginning_position, 0, 1, 0,
        doc: /* Return the position of the first character in the current 
line/field.
+With optional argument N non-nil, move forward N - 1 lines first.
 This function is like `pos-bol' (which see), but respects fields.
 
 This function constrains the returned position to the current field