Merge from origin/emacs-29

5fbd12ff494 Adapt manual names in emacs-news-mode
b36bc692671 ; * etc/NEWS: Fix typos.
f626b9f3856 ; * doc/misc/use-package.texi: Fix indexing.
56a6712bd6f ; * lisp/erc/erc.el (erc-default-target): Fix comment.
dcf69a1da4a Respect some spaces in auth-source-pass--match-regexp
acd462b0306 ; Improve the use-package manual
801c1c22de8 ; Prefer HTTPS to HTTP in some URLs
74a009dd96a Eglot: Handle LSP progress with Emacs progress reporters ...
0cfeb1c2bc9 Eglot: cleanup whitespace and indentation
465a9e78b96 Better test-custom-opts diagnostics
bdbb7099784 ; Fix groff warnings in man pages
d3d9676bf88 New script admin/check-man-pages
c2aea9d1323 ; Mention flush-lines in kill-matching-lines docstring
f5c3585e4dd ; Fix typos
58a483960dd ; Improve use-package-autoload-keymap docstring

# Conflicts:
#	etc/NEWS

19 files changed, 722 insertions, 345 deletions

diff --git a/admin/check-man-pages b/admin/check-man-pages
new file mode 100755
index 00000000000..c7d781ba3d2
--- /dev/null
+++ b/admin/check-man-pages
@@ -0,0 +1,56 @@
+#!/bin/bash
+### check-man-pages - check man pages for errors
+
+## Copyright (C) 2022 Free Software Foundation, Inc.
+
+## Author: Stefan Kangas <stefankangas@gmail.com>
+
+## This file is part of GNU Emacs.
+
+## GNU Emacs is free software: you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+
+## GNU Emacs is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+
+## You should have received a copy of the GNU General Public License
+## along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+### Commentary:
+
+## Check Emacs man pages for errors using `man'.
+
+### Code:
+
+source "${0%/*}/emacs-shell-lib"
+
+exit_status=0
+
+cd "$PD"/../doc/man
+for page in *.1; do
+    # ctags.1 just includes the man page etags.1, which AFAICT will
+    # default to the one installed on the system (!), instead of the
+    # one in the repository.  So checking it is pointless, and we will
+    # in any case already check etags.1 separately.
+    if [ "$page" == "ctags.1" ]; then
+        continue
+    fi
+    log=$(emacs_mktemp)
+    LC_ALL=C.UTF-8 MANROFFSEQ='' MANWIDTH=80 \
+        man --warnings=all,mac -E UTF-8 -l -Tutf8 -Z "$page" >/dev/null 2> "$log"
+    log_size=$(stat --format=%s "$log")
+    if [ "$log_size" -ne 0 ]; then
+        echo "doc/man/$page:"
+        # Point to the correct file for *compilation* buffers.
+        cat "$log" \
+            | sed 's/troff: man1\/\([^ ]\+\)\.1/troff: doc\/man\/\1.1/' \
+            | sed "s/<standard input>/doc\/man\/$page/"
+        exit_status=1
+    fi
+done
+
+exit $exit_status
diff --git a/admin/cus-test.el b/admin/cus-test.el
index 7e73f2e44aa..44897cd1060 100644
--- a/admin/cus-test.el
+++ b/admin/cus-test.el
@@ -145,7 +145,8 @@ Names should be as they appear in loaddefs.el.")
 (require 'cus-load)
 
 (defvar cus-test-errors nil
-  "List of problematic variables found by `cus-test-apropos'.")
+  "List of problematic variables found by `cus-test-apropos'.
+Each element is (VARIABLE . PROBLEM); see `cus-test--format-problem'.")
 
 (defvar cus-test-tested-variables nil
   "List of options tested by last call of `cus-test-apropos'.")
@@ -181,6 +182,15 @@ Set by `cus-test-noloads'.")
 ;; (defvar cus-test-vars-cus-loaded nil
 ;;   "A list of options loaded by `custom-load-symbol'.")
 
+(defun cus-test--format-error (err)
+  "Format an element of `cus-test-errors'."
+  (pcase err
+    (`(,var :type-error ,value ,type)
+     (format "variable: %s\n   value: %S\n    type: %S" var value type))
+    (`(,var :other-error ,e)
+     (format "variable: %s\n   error: %S" var e))
+    (_ (format "%S" err))))
+
 (defun cus-test-apropos (regexp)
   "Check the options matching REGEXP.
 The detected problematic options are stored in `cus-test-errors'."
@@ -200,8 +210,7 @@ The detected problematic options are stored in `cus-test-errors'."
          (let* ((type (custom-variable-type symbol))
                 (conv (widget-convert type))
                 (get (or (get symbol 'custom-get) 'default-value))
-                values
-                mismatch)
+                values)
            (when (default-boundp symbol)
              (push (funcall get symbol) values)
              (push (eval (car (get symbol 'standard-value)) t) values))
@@ -215,7 +224,9 @@ The detected problematic options are stored in `cus-test-errors'."
                    ;; TODO for booleans, check for values that can be
                    ;; evaluated and are not t or nil.  Usually a bug.
                    (unless (widget-apply conv :match value)
-                     (setq mismatch 'mismatch)))
+                     (let ((err (list symbol :type-error value type)))
+                       (unless (member err cus-test-errors)
+                         (push err cus-test-errors)))))
                  values)
 
            ;; Store symbols with a custom-get property.
@@ -231,13 +242,12 @@ The detected problematic options are stored in `cus-test-errors'."
              (and (consp c-value)
                   (boundp symbol)
                   (not (equal (eval (car c-value) t) (symbol-value symbol)))
-                  (add-to-list 'cus-test-vars-with-changed-state symbol)))
-
-           (if mismatch
-               (push symbol cus-test-errors)))
+                  (add-to-list 'cus-test-vars-with-changed-state symbol))))
 
        (error
-        (push symbol cus-test-errors)
+        (let ((err (list symbol :other-error alpha)))
+          (unless (member err cus-test-errors)
+            (push err cus-test-errors)))
         (message "Error for %s: %s" symbol alpha))))
    (cus-test-get-options regexp))
   (message "%s options tested"
@@ -292,7 +302,7 @@ currently defined groups."
         (insert "No errors found by cus-test.")
       (insert "The following variables seem to have problems:\n\n")
       (dolist (e cus-test-errors)
-        (insert (symbol-name e) "\n")))))
+        (insert (cus-test--format-error e) "\n")))))
 
 (defun cus-test-load-custom-loads ()
   "Call `custom-load-symbol' on all atoms."
@@ -399,7 +409,7 @@ Returns a list of variables with suspicious types."
         (message "No problems found")
         nil)
     (message "The following options might have problems:")
-    (cus-test-message cus-test-errors)
+    (cus-test-message (mapcar #'cus-test--format-error cus-test-errors))
     cus-test-errors))
 
 (defun cus-test-deps ()
diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index d881b816125..45da3ed6be5 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -150,6 +150,12 @@ General steps (for each step, check for possible errors):
 4.    autoreconf -i -I m4 --force
       make bootstrap
 
+      ./admin/check-man-pages
+
+    The above script checks for any mistakes in the source text of
+    manual pages.  Fix any errors and re-run the script to verify.
+    Then do this:
+
       make -C etc/refcards
       make -C etc/refcards clean
 
diff --git a/doc/man/etags.1 b/doc/man/etags.1
index 8dbea25c4cf..d3d58b82123 100644
--- a/doc/man/etags.1
+++ b/doc/man/etags.1
@@ -209,7 +209,7 @@ otherwise.  This is particularly useful when storing many predefined
 regexps in a file.
 .br
 In its second form, \fIregexfile\fP is the name of a file that contains
-a number of arguments to the \fI\-\-regex\=\fP option,
+a number of arguments to the \fI\-\-regex=\fP option,
 one per line.  Lines beginning with a space or tab are assumed
 to be comments, and ignored.
 
@@ -220,22 +220,22 @@ from shell interpretation.
 
 Tag the DEFVAR macros in the emacs source files:
 .br
-\fI\-\-regex\='/[ \\t]*DEFVAR_[A-Z_ \\t(]+"\\([^"]+\\)"/'\fP
+\fI\-\-regex='/[ \\t]*DEFVAR_[A-Z_ \\t(]+"\\([^"]+\\)"/'\fP
 .\"" This comment is to avoid confusion to Emacs syntax highlighting
 .br
 
 Tag VHDL files (this example is a single long line, broken here for
 formatting reasons):
 .br
-\fI\-\-language\=none\ \-\-regex='/[\ \\t]*\\(ARCHITECTURE\\|\\
-CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex\='/[\ \\t]*\\
+\fI\-\-language=none\ \-\-regex='/[\ \\t]*\\(ARCHITECTURE\\|\\
+CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex='/[\ \\t]*\\
 \\(ATTRIBUTE\\|ENTITY\\|FUNCTION\\|PACKAGE\\(\ BODY\\)?\\
 \\|PROCEDURE\\|PROCESS\\|TYPE\\)[\ \\t]+\\([^\ \\t(]+\\)/\\3/'\fP
 .br
 
 Tag Tcl files (this last example shows the usage of a \fItagregexp\fP):
 .br
-\fI\-\-lang\=none \-\-regex\='/proc[\ \\t]+\\([^\ \\t]+\\)/\\1/'\fP
+\fI\-\-lang=none \-\-regex='/proc[\ \\t]+\\([^\ \\t]+\\)/\\1/'\fP
 
 .br
 A regexp can be preceded by {\fIlang\fP}, thus restricting it to match
diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index b76f8bdfd71..2aff038b9ab 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -955,6 +955,13 @@ Note that you can still configure the excluded Emacs features manually
 to use Eglot in your @code{eglot-managed-mode-hook} or via some other
 mechanism.
 
+@vindex eglot-report-progress
+@cindex progress
+@item eglot-report-progress
+Set this variable to true if you'd like progress notifications coming
+from the LSP server to be handled as Emacs's progress reporting
+facilities.
+
 @vindex eglot-workspace-configuration
 @cindex server workspace configuration
 @item eglot-workspace-configuration
diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 4561b760c04..80e1bceb8ec 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -847,7 +847,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
 @findex flymake-proc-legacy-flymake
 The backend @code{flymake-proc-legacy-flymake} was originally designed
 to be extended for supporting new syntax check tools and error message
-patterns.  It is also controlled by its own set of customization variables
+patterns.  It is also controlled by its own set of customization variables.
 
 @node Proc customization variables
 @section Customization variables for the Proc backend
diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 4f0f8a26773..daf27ec5bbc 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -47,9 +47,9 @@ modify this GNU manual.''
 @node Top
 @top use-package User Manual
 
-The @code{use-package} macro allows you to isolate package
+The @code{use-package} macro allows you to set up package
 customization in your init file in a declarative way.  It takes care
-of a lot of things for you that would otherwise require a lot of
+of many things for you that would otherwise require a lot of
 repetitive boilerplate code.  It can help with common customization,
 such as binding keys, setting up hooks, customizing user options and
 faces, autoloading, and more.  It also helps you keep Emacs startup
@@ -57,8 +57,9 @@ fast, even when you use many (even hundreds) of packages.
 
 Note that use-package is not a package manager.  Although use-package
 does have the useful capability to interface with the Emacs package
-manager, its primary purpose is for the configuration and loading of
-packages.
+manager, its primary purpose is help with the configuration and
+loading of packages, not with managing their download, upgrades, and
+installation.
 
 @insertcopying
 
@@ -75,6 +76,8 @@ Appendices
 * Keyword extensions::          Adding new use-package keywords.
 * History::                     History and acknowledgments.
 * GNU Free Documentation License::  The license for this manual.
+
+Index
 * Index::
 @end menu
 @end ifnottex
@@ -88,52 +91,58 @@ customization and use of packages in Emacs.  It was created for a few
 basic reasons, each of which drove the design.  Understanding these
 reasons may help make some of those decisions clearer:
 
+@cindex reasons for developing use-package
 @enumerate
 @item
-To gather all configuration details of a package into one place,
-making it easier to copy, disable, or move it elsewhere in the init
-file.
+Allow gathering all the configuration details of a package into one
+place, making it easier to copy, disable, or move it elsewhere in the
+init file.
 
 @item
-To reduce duplication and boilerplate, capturing several common
-practices as mere keywords both easy and intuitive to use.
+Reduce duplication and repetitive boilerplate, capturing several
+common practices as mere keywords both easy and intuitive to use.
 
 @item
-To make startup time of Emacs as quick as possible, without
-sacrificing the quantity of add-on packages used.
+Make startup time of Emacs as short as possible, without sacrificing
+the quantity of add-on packages used.
 
 @item
-To make it so errors encountered during startup disable only the
-package raising the error, and as little else as possible, leaving as
-close to a functional Emacs as possible.
+Ensure that errors encountered during startup disable only the
+package(s) raising the error(s), and as little else as possible,
+leaving Emacs as close to fully functional as possible.
 
 @item
-To allow byte-compilation of one's init file so that any warnings or
-errors seen are meaningful.  In this way, even if byte-compilation is
-not used for speed (reason 3), it can still be used as a sanity check.
+Allow byte-compiling your init file, so that any warnings or errors
+you see at startup are meaningful.  In this way, even if
+byte-compilation is not used for speed (see item 3 above), it can
+still be used as a sanity check.
 @end enumerate
 
 It is worth noting that use-package is not intended to replace the
-standard @w{@code{M-x customize}}.  On the contrary, it is designed to
-work together with it, for things that customize cannot do.
+standard customization command @w{@kbd{M-x customize}} (@pxref{Easy
+Customization,,, emacs, GNU Emacs Manual}).  On the contrary, it is
+designed to work together with it, for things that Customize cannot
+do.
 
 @c ----------------------------------------------------------------------------
 @node Getting Started
 @chapter Getting Started
+@cindex quick-start instructions
 
 This chapter provides instructions and examples for quickly getting
 started with use-package.  The first thing you need to do is make sure
-that @samp{use-package} itself is loaded.  To do that, put this at the
+that @file{use-package} itself is loaded.  To do that, put this at the
 top of your init file:
 
 @lisp
 (require 'use-package)
 @end lisp
 
-The above makes the @code{use-macro} for in the rest of your init
-file.  In this manual, we call each call to @code{use-macro} a
-@dfn{declaration}, to highlight the declarative nature of its
-semantic.
+@cindex declaration
+The above makes the @code{use-macro} available for us in the rest of
+your init file.  In this manual, we say that each call to
+@code{use-macro} is a @dfn{declaration}, to highlight the declarative
+nature of its syntax.
 
 To unconditionally load a package named @samp{foo}, add the following
 declaration to your init file:
@@ -143,62 +152,70 @@ declaration to your init file:
 @end lisp
 
 @noindent
-This declaration is equivalent to using @code{require}, with some
-use-package specific error handling added in.  Just like require, it
-needs the package @samp{foo} to be installed and available in your
-@code{load-path} (@pxref{Installing packages}).
+This declaration is equivalent to using @code{require} (@pxref{Named
+Features,,, elisp, GNU Emacs Lisp Reference Manual}), with some
+use-package specific error handling added in.  Just like
+@code{require}, it needs the package @samp{foo} to be installed and
+available via your @code{load-path} (@pxref{Installing packages}).
 
-To evaluate Lisp code @emph{before} the @samp{foo} package is loaded,
+To evaluate some Lisp @emph{before} the @samp{foo} package is loaded,
 use the @code{:init} keyword:
 
 @lisp
+@group
 (use-package foo
   :init
   (setq foo-variable t))
+@end group
 @end lisp
 
 Similarly, @code{:config} can be used to execute code @emph{after} a
 package is loaded.  In cases where loading is done lazily
 (@pxref{Loading Packages}), this execution is deferred until after the
-autoload occurs.  As you might expect, you can use @code{:init} and
-@code{:config} together:
+loading actually occurs.  As you might expect, you can use
+@code{:init} and @code{:config} together:
 
 @lisp
+@group
 (use-package foo
   :init
   (setq foo-variable t)
   :config
   (foo-mode 1))
+@end group
 @end lisp
 
-The above declarations will all load the @samp{foo} package
+The above declarations will load the @samp{foo} package
 immediately.  In most cases, this is not necessary or desirable, as
 that will slow down Emacs startup.  Instead, you should try to set
 things up so that packages are only loaded when they are actually
-needed (autoloading).  If you have installed a package from
+needed (a.k.a. ``autoloading'').  If you have installed a package from
 @acronym{GNU ELPA} that provides it's own autoloads, it is often
 enough to say:
 
 @lisp
+@group
 (use-package foo
   :defer t)
+@end group
 @end lisp
 
 @noindent
 This will avoid loading the package.  Now, when you run any autoloaded
-command, the package @samp{foo} is loaded automatically.  Package
-authors will make their own decisions about which commands are marked
-to autoload by default.
+command, the package @samp{foo} is loaded automatically.  (Which
+commands from a package are marked to auto-load by default is the
+decision of the package authors.)
 
 In some cases, you might need or want to provide your own autoloads.
-The below more complex example autoloads the commands
-@code{isearch-moccur} and @code{isearch-all} from
+The more complex example below autoloads the commands
+@code{isearch-moccur} and @code{isearch-all} from the package
 @file{color-moccur.el}, and binds keys both globally and in
-@code{isearch-mode-map}.  When one of these commands are used, the
-package is loaded.  At that point, @code{moccur-edit} is also loaded,
+@code{isearch-mode-map}.  When one of these two commands are used, the
+package will be loaded.  At that point, @code{moccur-edit} is also loaded,
 to allow editing of the @code{moccur} buffer.
 
 @lisp
+@group
 (use-package color-moccur
   :commands (isearch-moccur isearch-all)
   :bind (("M-s O" . moccur)
@@ -209,6 +226,7 @@ to allow editing of the @code{moccur} buffer.
   (setq isearch-lazy-highlight t)
   :config
   (use-package moccur-edit))
+@end group
 @end lisp
 
 Some packages will suggest ready-made @code{use-package} declarations
@@ -220,8 +238,8 @@ That should be enough to get you started!
 @c ----------------------------------------------------------------------------
 @node Loading Packages
 @chapter Loading Packages
+@cindex loading packages with use-package
 
-@cindex loading packages
 Before use-package can load an Emacs Lisp package, it must be
 available in a directory on your @code{load-path}.  When you install
 packages using the built-in @code{install-package} command, it will do
@@ -230,15 +248,15 @@ packages) are always available.
 
 If you install packages manually, you must make sure they are
 available on your @code{load-path}.  @xref{Lisp Libraries,,, emacs,
-GNU Emacs Manual} for details.
+GNU Emacs Manual}, for details.
 
 Some packages have more than one library.  In those cases, you might
-need more than one @code{use-package} declaration to make sure it is
-properly loaded.  For complex configurations, you might also need more
-than one declaration for a package with the same name.
+need more than one @code{use-package} declaration to make sure the
+package is properly loaded.  For complex configurations, you might
+also need more than one declaration for a package with the same name.
 
 use-package can interface with @samp{package.el} to install packages
-on Emacs start.  @xref{Installing packages} for details.
+on Emacs start.  @xref{Installing packages}, for details.
 
 @menu
 * Loading basics::              How and when packages are loaded.
@@ -254,32 +272,38 @@ on Emacs start.  @xref{Installing packages} for details.
 @node Loading basics
 @section How and when use-package loads packages
 
-The @code{use-package} macro either will either load a package
-immediately, or when they are first used (autoloading).  In the
+The call to the @code{use-package} macro will load a package either
+immediately, or when the package is first used (via autoloading).  In the
 simplest case, a @code{use-package} declaration loads a package when
 it is evaluated.@footnote{This happens both at run-time and at
 compile-time.  @xref{Byte-compiling}.}  If the declaration is in your
 init file, this happens automatically each time Emacs is started.
 
-For example, the below declaration immediately loads the library
-@code{foo}, just like @code{require} would.  If the library @samp{foo}
-is not available in your @code{load-path}, it logs a warning to the
-@samp{*Messages*} buffer:
+For example, the declaration below immediately loads the library
+@code{foo}, just like @code{require} would:
 
 @lisp
 (use-package foo)
 @end lisp
 
+@noindent
+If the library @samp{foo} is not available in your @code{load-path},
+the declaration logs a warning to the @samp{*Messages*} buffer.
+
+@cindex package vs library
+@c So, confusingly, (use-package foo) actually means to use the
+@c _library_ foo.el, not all of the _package_ foo's libraries?
+@c Should this be explicitly explained here?
 Note that a ``package'' is different from an Emacs Lisp ``library''.
 The above declaration tells use-package to load the @emph{library}
-@file{foo.el}, which the overwhelming majority of cases also resides
-in a @emph{package} named @code{foo}.  But the @code{foo} package
-might also contain a library named @file{foo-extra.el}.  If that
-library is not loaded automatically, you will need a separate
-@code{use-package} declaration to make sure that it is.  This manual
-will often use these terms interchangeably, as this distinction does
-not usually matter, but you should keep it in mind for the cases when
-it does.
+@file{foo.el}, which in the overwhelming majority of cases also
+resides in a @emph{package} named @code{foo}.  But the package
+@code{foo} might also contain a library named @file{foo-extra.el}.  If
+that library is not loaded automatically, you will need a separate
+@code{use-package} declaration to make sure that it is loaded when
+needed.  This manual will often use the terms ``package'' and
+``library'' interchangeably, as this distinction does not usually
+matter, but you should keep it in mind for the cases when it does.
 
 The details of how and when you should load a package might differ
 from one package to another.  When in doubt, refer to the package
@@ -287,17 +311,19 @@ documentation for details.
 
 @node Deferring loading
 @section Deferring package loading
+@cindex deferring loading of package
 
 @cindex autoloading packages
 @cindex loading lazily
+@cindex lazy loading of packages
 In the examples we have seen so far, use-package loads packages every
 time you start Emacs, even if that package is never used.  That will
-make starting Emacs slower.  use-package therefore tries to set things
-up in such a way that it only loads packages when a command is first
-used (either with @kbd{M-x} or some key binding).  This is based on
-autoloading, a full description of which is outside the scope of this
-manual.  @xref{Autoload,,, elisp, GNU Emacs Lisp Reference Manual} for
-the full story.
+make starting Emacs slower.  use-package therefore allows setting
+things up in such a way that packages are only loaded when some of the
+package's commands is first used (either with @kbd{M-x} or via some key
+binding).  This is based on autoloading, a full description of which
+is outside the scope of this manual.  @xref{Autoload,,, elisp, GNU
+Emacs Lisp Reference Manual}, for the full story.
 
 @cindex triggers, for loading packages
 Some @code{use-package} keywords provide autoload @dfn{triggers} that
@@ -320,8 +346,10 @@ this package from being immediately loaded.  Here is an example of
 using @code{:defer} to postpone loading the package @samp{foo}:
 
 @lisp
+@group
 (use-package foo
   :defer t)
+@end group
 @end lisp
 
 Using @code{:defer t} by itself like this is rarely useful.
@@ -331,21 +359,25 @@ Typically, you would only use it together with a keyword like
 
 @subheading Defer loading until idle for N seconds
 
-You can also give a numeric argument @var{N} to @w{@code{:defer}} to
+@findex :defer@r{, with a numeric argument}
+You can also give a numeric argument @var{n} to @w{@code{:defer}} to
 specify that a package should be loaded (if it hasn't already) after
-Emacs has been idle for @var{N} seconds.  For example, use this to
-make use-package load @samp{foo} after 30 seconds of idle time:
+Emacs has been idle for @var{n} seconds.  For example, use the
+following to make use-package load @samp{foo} after 30 seconds of idle
+time:
 
 @lisp
+@group
 (use-package foo
   :defer 30)
+@end group
 @end lisp
 
 @subheading When to use @code{:defer}
 
 When using autoloading keywords, there is no need to also use
-@code{:defer}.  It doesn't hurt anything to add it in this case,
-perhaps for extra clarity, but it is redundant.
+@code{:defer}.  It doesn't hurt to add it in this case, perhaps for
+extra clarity, but it is redundant.
 
 You should use @code{:defer} to force deferred loading, in cases when
 use-package isn't creating any autoloads for you.  For example, you
@@ -357,6 +389,8 @@ autoloads already set up.
 
 @subheading Making @w{@code{:defer t}} the default
 
+@cindex defer loading by default
+@cindex lazy loading by default
 @vindex use-package-always-defer
 If you customize the user option @code{use-package-always-defer} to
 non-@code{nil}, the @code{use-package} macro will behave as if
@@ -366,6 +400,7 @@ individual declarations using either @w{@code{:defer nil}} or
 
 @node Forcing loading
 @section Forcing package to load immediately
+@cindex forcing immediate loading
 
 @findex :demand
 The presence of autoloading trigger keywords can be overridden using
@@ -380,6 +415,8 @@ If you specify both @w{@code{:demand t}} and @w{@code{:defer t}}, the
 
 @node Conditional loading
 @section Loading packages conditionally
+@cindex conditional loading
+@cindex loading conditions
 
 @findex :if
 @findex :when
@@ -398,8 +435,10 @@ For example, if you only want to load @samp{foo} in graphical Emacs
 sessions, you could use the following:
 
 @lisp
+@group
 (use-package foo
   :if (display-graphic-p))
+@end group
 @end lisp
 
 @subheading Some common use cases
@@ -407,39 +446,46 @@ sessions, you could use the following:
 Here are some common cases for conditional loading, and how to achieve
 them.
 
+@c FIXME: Too many redundant examples?  E.g., why do we need both an
+@c example for system-type and window-system? or both of the last 2
+@c examples?
 @itemize
 
-@item Operating system
+@item
+Operating system
 
-This example loads a package only on GNU/Linux.  See the
-@code{system-type} docstring for other valid values.
+The following example loads a package only on GNU/Linux.  See the
+docstring of @code{system-type} for other valid values.
 
 @lisp
 :if (eq system-type 'gnu/linux)
 @end lisp
 
-@item Window system
+@item
+Window system
 
-This example loads a package only on macOS and X.  See the
-@code{window-system} docstring for valid values.
+The example below loads a package only on macOS and X.  See the
+docstring of @code{window-system} for valid values.
 
 @lisp
 :if (memq window-system '(ns x))
 @end lisp
 
-@item Installed package
+@item
+Installed package
 
-This example loads a package only when the @samp{foo} package is
-installed.
+The following example loads a package only when the @samp{foo} package
+is installed.
 
 @lisp
 :if (package-installed-p 'foo)
 @end lisp
 
-@item Libraries in @code{load-path}
+@item
+Libraries in @code{load-path}
 
-This example loads a package only when @file{foo.el} is available in
-your @code{load-path} (for example, if you installed that file
+The example below loads a package only when @file{foo.el} is available
+in your @code{load-path} (for example, if you installed that file
 manually):
 
 @lisp
@@ -450,38 +496,45 @@ manually):
 @subheading Making conditional loading affect @code{:preface} and @code{:ensure}
 
 @cindex conditional loading before @code{:preface} or @code{:ensure}
-If you need to conditionalize a use-package form so that the condition
-occurs before even @code{:ensure} or @code{:preface}, use @code{when}
-around the use-package form itself.  For example:
+If you need to make a use-package form conditional so that the condition
+occurs before even @code{:ensure} (@pxref{Install package}) or
+@code{:preface} (@pxref{Preface keyword}), use @code{when}
+around the @code{use-package} form itself.  For example:
 
 @lisp
+@group
 (when (memq window-system '(mac ns))
   (use-package foo
     :ensure t))
+@end group
 @end lisp
 
 @node Loading sequentially
 @section Loading packages in sequence
+@cindex loading a package after other packages
 
 @findex :after
 Sometimes it only makes sense to configure a package after another one
 has been loaded, because certain variables or functions are not in
-scope until that time.  This can achieved with the @code{:after}
+scope until that time.  This can be achieved with the @code{:after}
 keyword, which allows a fairly rich description of the exact
-conditions when loading should occur.  It takes either a symbol
-indicating the package name, a list of such symbols, or a list of
-selectors (see below).
+conditions when loading should occur.  The @code{:after} keyword takes
+as argument either a symbol indicating the package name, a list of
+such symbols, or a list of selectors (see below).
 
-Here is an example of using the @acronym{GNU ELPA} packages hydra,
-ivy, and ivy-hydra.  Note that ivy-hydra will always be loaded last:
+Here is an example of using the @acronym{GNU} @acronym{ELPA} packages
+@file{hydra}, @file{ivy}, and @file{ivy-hydra}.  Note that
+@file{ivy-hydra} will always be loaded last:
 
 @lisp
 (use-package hydra)
 
 (use-package ivy)
 
+@group
 (use-package ivy-hydra
   :after (ivy hydra))
+@end group
 @end lisp
 
 In this case, because the declarations are evaluated in the order they
@@ -494,11 +547,12 @@ moving things around in your init file is less likely to break things.
 
 @subheading Using @code{:after} selectors
 
-@findex :all (with :after)
-@findex :any (with :after)
+@findex :all@r{, (with @code{:after})}
+@findex :any@r{, (with @code{:after})}
+@cindex list of selectors, for @code{:after}
 The @code{:after} keyword also accepts a list of selectors.  By
-default, @code{:after (foo bar)} is the same as @w{@code{:after (:all
-foo bar)}}, meaning that loading of the given package will not happen
+default, @w{@code{:after (foo bar)}} is the same as @w{@code{:after
+(:all foo bar)}}, meaning that loading of the given package will not happen
 until both @code{foo} and @code{bar} have been loaded.  Here are some
 of the other possibilities:
 
@@ -510,22 +564,25 @@ of the other possibilities:
 :after (:any (:all foo bar) (:all baz quux))
 @end verbatim
 
-When you nest selectors, such as @code{(:any (:all foo bar) (:all baz
-quux))}, it means that the package will be loaded when either both
-@code{foo} and @code{bar} have been loaded, or when both @code{baz}
-and @code{quux} have been loaded.
+When you nest selectors, such as in @w{@code{(:any (:all foo bar)
+(:all baz quux))}}, it means that the package will be loaded when
+either both @code{foo} and @code{bar} have been loaded, or when both
+@code{baz} and @code{quux} have been loaded.
 
+@cindex @code{use-package-always-defer}, with @code{:after}
 Pay attention when setting @code{use-package-always-defer} to a
 non-@code{nil} value, and also using the @code{:after} keyword.  In
-this case, you will need to specify how the declared package is to be
-loaded: for example, by some @code{:bind}.  If you are not using one
-of the keywords that registers autoloads, such as @code{:bind} or
-@code{:hook}, and your package manager does not provide autoloads, it
-is possible that your package will never be loaded if you do not add
-@code{:demand t} to those declarations.
+that case, you will need to specify how the declared package is to be
+loaded: for example, by some @code{:bind} (@pxref{Global
+keybindings}).  If you are not using one of the keywords that
+registers autoloads, such as @code{:bind} or @code{:hook}
+(@pxref{Hooks}), and your package manager does not provide autoloads,
+it is possible that your package will never be loaded if you do not
+add @code{:demand t} to those declarations.
 
 @node Load dependencies
 @section Prevent loading if dependencies are missing
+@cindex prevent loading package if dependencies are missing
 
 @findex :requires
 While the @code{:after} keyword delays loading until the dependencies
@@ -536,22 +593,29 @@ loads the package if the dependencies are not available when the
 'foo)}} evaluates to a non-@code{nil} value.  For example:
 
 @lisp
+@group
 (use-package abbrev
   :requires foo)
+@end group
 @end lisp
 
+@noindent
 This is the same as:
 
 @lisp
+@group
 (use-package abbrev
   :if (featurep 'foo))
+@end group
 @end lisp
 
 As a convenience, a list of such packages may be specified:
 
 @lisp
+@group
 (use-package abbrev
   :requires (foo bar baz))
+@end group
 @end lisp
 
 For more complex logic, such as that supported by @code{:after},
@@ -559,64 +623,81 @@ simply use @code{:if} and the appropriate Lisp expression.
 
 @node Load path
 @section Setting a custom @code{load-path}
+@cindex custom @code{load-path} for loading a package
+@cindex @code{load-path}, add directories for loading a package
 
 @findex :load-path
 If a package resides in some directory that is not in your
 @code{load-path}, use the @code{:load-path} keyword to add it.  It
-takes a symbol, a function, a string or a list of strings.  If the
-path is relative, it is expanded within @code{user-emacs-directory}.
+takes as argument a symbol, a function, a string or a list of strings.
+If a directory is specified as a relative file name, it is expanded
+relative to @code{user-emacs-directory}.
 
 For example:
 
 @lisp
+@group
 (use-package ess-site
   :load-path "site-lisp/ess/lisp/"
   :commands R)
+@end group
 @end lisp
 
 Note that when using a symbol or a function to provide a dynamically
-generated list of paths, you must inform the byte-compiler of this
+generated list of directories, you must inform the byte-compiler of this
 definition so that the value is available at byte-compilation time.
 This is done by using the special form @code{eval-and-compile} (as
-opposed to @code{eval-when-compile}).  Further, this value is fixed at
+opposed to @code{eval-when-compile}, @pxref{Eval During Compile,,,
+elisp, GNU Emacs Lisp Reference Manual}).  Further, this value is fixed at
 whatever was determined during compilation, to avoid looking up the
 same information again on each startup.  For example:
 
+@c FIXME: the below should use shell-command-to-string, surely?
 @lisp
+@group
 (eval-and-compile
   (defun ess-site-load-path ()
     (shell-command "find ~ -path ess/lisp")))
+@end group
 
+@group
 (use-package ess-site
   :load-path (lambda () (list (ess-site-load-path)))
   :commands R)
+@end group
 @end lisp
 
 @node Manual autoloads
 @section Setting up autoloads manually
+@cindex autoloads for packages, setting up manually
+@cindex package autoloads, setting up manually
 
 @findex :commands
 @findex :autoload
 To autoload an interactive command, use the @code{:commands} keyword.
 When you use the @code{:commands} keyword, it creates autoloads for
-those commands (which defers loading of the module until they are
+those commands (which defers loading of the module until those commands are
 used).  The @code{:commands} keyword takes either a symbol or a list
-of symbols.
+of symbols as its argument.
 
 The @code{:autoload} keyword works like @code{:commands}, but is used
 to autoload non-interactive functions.  Here is an example:
 
 @lisp
+@group
 (use-package org-crypt
   :autoload org-crypt-use-before-save-magic)
+@end group
 @end lisp
 
 @c ----------------------------------------------------------------------------
 @node Configuring Packages
 @chapter Configuring Packages
+@cindex configure packages using @code{use-package}
+@cindex customize package configuration
 
 This chapter describes the various keywords provided by
-@code{use-package} that helps you configure packages.
+@code{use-package} that help you configure packages.
 
 @menu
 * Lisp Configuration::          Using Lisp to configure packages.
@@ -631,6 +712,7 @@ This chapter describes the various keywords provided by
 
 @node Lisp Configuration
 @section Using Lisp code for configuring packages
+@cindex configure package using Lisp forms
 
 The most general way to add customizations are the @code{:preface},
 @code{:init}, and @code{:config} keywords.  They all accept one or
@@ -657,19 +739,22 @@ function and variable definitions that will:
 
 @enumerate
 @item
-Make the byte-compiler happy.  It will not complain about functions
+@c FIXME: ``within a guard block''? what's that??
+Make the byte-compiler happy: it will not complain about functions
 whose definitions are unknown because you have them within a guard
 block.
 
 @item
-Define code that can be used in an @code{:if} test.
+Define functions and variables that will be used in an @code{:if}
+test.
 @end enumerate
 
 Note that whatever is specified within @code{:preface} is evaluated
 both at load time and at byte-compilation time, in order to ensure
 that definitions are seen by both the Lisp evaluator and the
 byte-compiler.  Therefore, you should avoid having any side-effects in
-your preface, and restrict it to symbol declarations and definitions.
+your @code{:preface} forms, and restrict them to symbol declarations
+and definitions.
 
 @node Init keyword
 @subsection @code{:init} is evaluated before loading package
@@ -677,10 +762,11 @@ your preface, and restrict it to symbol declarations and definitions.
 @findex :init
 The @code{:init} section is evaluated just before the package is
 loaded.  Note that the @code{:init} form is run unconditionally --
-even if the @code{foo} package happens to not exist on your system.
-You must therefore remember to restrict @code{:init} code to only what
-would succeed either way.  @code{:init} also always happens before
-package load, whether @code{:config} has been deferred or not.
+even if the package happens to not exist on your system.  You must
+therefore remember to restrict @code{:init} code to what would succeed
+either way; put the rest in the @code{:config} section.  @code{:init}
+also always happens before package load, whether @code{:config} has
+been deferred or not.
 
 @node Config keyword
 @subsection @code{:config} is evaluated after loading package
@@ -698,58 +784,68 @@ Emacs start as quickly as possible.
 
 @node Best practices
 @subheading When to use @code{:preface}, @code{:config} and @code{:init}?
+@cindex tips for using @code{:preface}, @code{:config}, @code{:init}
 
 Where possible, it is better to avoid @code{:preface}, @code{:config}
 and @code{:init}.  Instead, prefer autoloading keywords such as
-@code{:bind}, @code{:hook}, and @code{:mode}, as they will take care
+@code{:bind} (@pxref{Key bindings}), @code{:hook} (@pxref{Hooks}), and
+@code{:mode} (@pxref{Modes and interpreters}), as they will take care
 of setting up autoloads for you without any need for boilerplate code.
 For example, consider the following declaration:
 
 @lisp
+@group
 (use-package foo
   :init
   (add-hook 'some-hook 'foo-mode))
+@end group
 @end lisp
 
+@noindent
 This has two problems.  First, it will unconditionally load the
 package @samp{foo} on startup, which will make things slower.  You can
-fix this by adding @code{:defer t}:
+fix this by adding @w{@code{:defer t}}:
 
 @lisp
+@group
 (use-package foo
   :defer t
   :init
   (add-hook 'some-hook 'foo-mode))
+@end group
 @end lisp
 
+@noindent
 This is better, as @samp{foo} is now only loaded when it is actually
 needed (that is, when the hook @samp{some-hook} is run).
 
 The second problem is that there is a lot of boilerplate that you have
 to write.  In this case, it might not be so bad, but avoiding that was
-what use-package was made to avoid.  The better option in this case is
-therefore to use @code{:hook} (@xref{Hooks}), which also implies
+what use-package was made to allow.  The better option in this case is
+therefore to use @code{:hook} (@pxref{Hooks}), which also implies
 @w{@code{:defer t}}.  The above is thereby reduced down to:
 
 @lisp
+@group
 (use-package foo
   :hook some-hook)
+@end group
 @end lisp
 
-use-package will set up autoloading for you, and your Emacs startup
-time will not suffer one bit.
+Now use-package will set up autoloading for you, and your Emacs
+startup time will not suffer one bit.
 
 @node Key bindings
 @section Key bindings
 
-@cindex :bind
-@cindex binding keys
-@cindex key bindings
-One common thing to do when loading a package is to bind a key to
+@cindex binding keys for package commands
+@cindex key bindings for package commands
+One common thing to do when loading a package is to bind keys to
 commands within that module.  Without use-package, this would be done
 using a combination of @code{keymap-local-set},
 @code{keymap-global-set} and various autoloads.  With use-package, you
-can simplify this using the @code{:bind} keyword.
+can simplify this using the @code{:bind} keyword, as described in this
+section.
 
 @menu
 * Global keybindings::          Bindings you can use anywhere.
@@ -761,25 +857,29 @@ can simplify this using the @code{:bind} keyword.
 
 @node Global keybindings
 @subsection Global keybindings
+@cindex global keybindings
 
 @findex :bind
-To bind keys globally, the @code{:bind} keyword takes either a single
-cons or a list of conses.  Every cons has the form @code{(@var{key}
-. @var{command}}, where @var{key} is a string indicating the key to
-bind, and @var{command} is the name of a command (a symbol).  The
-syntax for the keys is similar to the syntax used by the @code{kbd}
-function (@pxref{Init Rebinding,,, emacs, GNU Emacs Manual} for more
-information).
+To bind keys globally, the @code{:bind} keyword takes as its argument
+either a single cons or a list of conses.  Each cons has the form
+@w{@code{(@var{key} . @var{command})}}, where @var{key} is a string
+indicating the key to bind, and @var{command} is the name of a command
+(a symbol).  The syntax for the keys is similar to the syntax used by
+the @code{kbd} function (see @ref{Init Rebinding,,, emacs, GNU Emacs
+Manual}, for more information).
 
 @subheading Using @code{:bind} with a single cons
 
 Here is an example of using a single cons:
 
 @lisp
+@group
 (use-package ace-jump-mode
   :bind ("C-." . ace-jump-mode))
+@end group
 @end lisp
 
+@noindent
 This does two things: first, it creates an autoload for the
 @code{ace-jump-mode} command and defers loading of the
 @code{ace-jump-mode} package until you actually use it.  Second, it
@@ -790,73 +890,100 @@ binds the key @code{C-.} to that command globally.
 Here is an example of using @code{:bind} with a list of conses:
 
 @lisp
+@group
 (use-package hi-lock
   :bind (("M-o l" . highlight-lines-matching-regexp)
          ("M-o r" . highlight-regexp)
          ("M-o w" . highlight-phrase)))
+@end group
 @end lisp
 
+@noindent
+This binds the three key sequences to the corresponding commands.
+
 @subheading Using special keys
+@cindex binding function keys with @code{:bind}
+@cindex @code{:bind}, and function keys
 
+@c FIXME: TAB vs [tab] -- is letter-case important?  In general, these
+@c are two different keys: one is an ASCII character, the other a
+@c function key on GUI frames.
 Inside key strings, special keys like @kbd{TAB} or @kbd{F1}--@kbd{F12}
-have to be written inside angle brackets, e.g.  @code{"C-<up>"}.
+have to be written inside angle brackets, e.g., @code{"C-<up>"}.
+@c FIXME: ``Some combinations''? which ones?
 Standalone special keys (and some combinations) can be written in
 square brackets, e.g.@ @code{[tab]} instead of @code{"<tab>"}.
 
 Examples:
 
 @lisp
+@group
 (use-package helm
   :bind (("M-x" . helm-M-x)
          ("M-<f5>" . helm-find-files)
          ([f10] . helm-buffers-list)
          ([S-f10] . helm-recentf)))
+@end group
 @end lisp
 
 @subheading Remapping commands
+@cindex remapping commands with @code{:bind}
+@cindex @code{:bind}, and remapping of commands
 
-Remapping commands with @code{:bind} and @code{bind-key} works as
+Remapping of commands with @code{:bind} and @code{bind-key} works as
 expected, because when the binding is a vector, it is passed straight
 to @code{define-key}.  @xref{Remapping Commands,,, elisp, GNU Emacs
-Lisp Reference Manual}) for more information about command remapping.
+Lisp Reference Manual}), for more information about command remapping.
 For example, the following declaration will rebind
 @code{fill-paragraph} (bound to @kbd{M-q} by default) to
 @code{unfill-toggle}:
 
 @lisp
+@group
 (use-package unfill
   :bind ([remap fill-paragraph] . unfill-toggle))
+@end group
 @end lisp
 
+@c FIXME: Should the below be an Appendix?
 @subheading What @code{:bind} does behind the scenes
+@cindex @code{:bind}, internals
 
 To understand what @code{:bind} does behind the scenes, it might be
 useful to consider an example:
 
 @lisp
+@group
 (use-package ace-jump-mode
   :bind ("C-." . ace-jump-mode))
+@end group
 @end lisp
 
+@noindent
 This could be expressed in a much more verbose way with the
-@code{:commands} and @code{:init} keywords.
+@code{:commands} and @code{:init} keywords:
 
 @lisp
+@group
 (use-package ace-jump-mode
   :commands ace-jump-mode
   :init
   (bind-key "C-." 'ace-jump-mode))
+@end group
 @end lisp
 
+@noindent
 Without using even the @code{:commands} keyword, we could also write
 the above like so:
 
 @lisp
+@group
 (use-package ace-jump-mode
   :defer t
   :init
   (autoload 'ace-jump-mode "ace-jump-mode" nil t)
   (bind-key "C-." 'ace-jump-mode))
+@end group
 @end lisp
 
 Although these three forms are all equivalent, the first form is
@@ -864,28 +991,33 @@ usually the best, as it will save some typing.
 
 @node Binding in keymaps
 @subsection Key bindings in local keymaps
+@cindex local keybindings
 
-@findex :map, inside :bind
+@findex :map@r{, inside} :bind
 Slightly different from binding a key to a keymap, is binding a key
 @emph{within} a local keymap that only exists after the package is
 loaded.  @code{use-package} supports this with a @code{:map} modifier,
 taking the local keymap to bind to:
 
 @lisp
+@group
 (use-package helm
   :bind (:map helm-command-map
          ("C-c h" . helm-execute-persistent-action)))
+@end group
 @end lisp
 
-The effect of this statement is to wait until @code{helm} has loaded,
-and then to bind the key @code{C-c h} to
+@noindent
+The effect of this is to wait until @code{helm} has loaded, and then
+to bind the key sequence @kbd{C-c h} to
 @code{helm-execute-persistent-action} within Helm's local keymap,
 @code{helm-command-map}.
 
-Multiple uses of @code{:map} may be specified. Any binding occurring
+Multiple uses of @code{:map} may be specified.  Any binding occurring
 before the first use of @code{:map} are applied to the global keymap:
 
 @lisp
+@group
 (use-package term
   :bind (("C-c t" . term)
          :map term-mode-map
@@ -895,21 +1027,23 @@ before the first use of @code{:map} are applied to the global keymap:
          ("M-o" . other-window)
          ("M-p" . term-send-up)
          ("M-n" . term-send-down)))
+@end group
 @end lisp
 
 @node Binding to a keymap
 @subsection Binding to keymaps
+@cindex binding keys to keymaps
 
-@findex :bind-keymap, inside :bind
+@findex :bind-keymap
 Normally @code{:bind} expects that commands are functions that will be
-autoloaded from the given package. However, this does not work if one of
+autoloaded from the given package.  However, this does not work if one of
 those commands is actually a keymap, since keymaps are not functions,
 and cannot be autoloaded using the built-in @code{autoload} function.
 
 To handle this case, @code{use-package} offers a special, limited
-variant of @code{:bind} called @code{:bind-keymap}. The only difference
+variant of @code{:bind} called @code{:bind-keymap}.  The only difference
 is that the ``commands'' bound to by @code{:bind-keymap} must be keymaps
-defined in the package, rather than command functions. This is handled
+defined in the package, rather than interactive functions.  This is handled
 behind the scenes by generating custom code that loads the package
 containing the keymap, and then re-executes your keypress after the
 first load, to reinterpret that keypress as a prefix key.
@@ -917,31 +1051,35 @@ first load, to reinterpret that keypress as a prefix key.
 For example:
 
 @lisp
+@group
 (use-package foo
   :bind-keymap ("C-c p" . foo-command-map))
+@end group
 @end lisp
 
 @node Binding to repeat-maps
 @subsection Binding to repeat-maps
+@cindex keybinding for @code{repeat-mode} keymaps
 
-@findex :repeat-map, inside :bind
-@cindex repeat-mode and use-package, using
+@findex :repeat-map@r{, inside} :bind
+@cindex @code{repeat-mode} and use-package, using
 A special case of binding within a local keymap is when that keymap is
-used by @code{repeat-mode} @pxref{Repeating,,, emacs, GNU Emacs
-Manual}.  These keymaps are usually defined specifically for
+used by @code{repeat-mode} (@pxref{Repeating,,, emacs, GNU Emacs
+Manual}).  These keymaps are usually defined specifically for
 this.  Using the @code{:repeat-map} keyword, and passing it a name for
-the map it defines, will bind all following keys inside that map, and
+the map it defines, will bind all the following keys inside that map, and
 (by default) set the @code{repeat-map} property of each bound command
 to that map.
 
 The following example creates a keymap called
-@code{git-gutter+-repeat-map}, makes four bindings in it as above,
-then sets the @code{repeat-map} property of each bound command
-(@code{git-gutter+-next-hunk} @code{git-gutter+-previous-hunk},
-@code{git-gutter+-stage-hunks} and @code{git-gutter+-revert-hunk}) to
+@code{git-gutter+-repeat-map}, makes four bindings in it, then sets
+the @code{repeat-map} property of each bound command
+(@code{git-gutter+-next-hunk}, @code{git-gutter+-previous-hunk},
+@code{git-gutter+-stage-hunks}, and @code{git-gutter+-revert-hunk}) to
 that keymap.
 
 @lisp
+@group
 (use-package git-gutter+
   :bind
   (:repeat-map git-gutter+-repeat-map
@@ -949,16 +1087,19 @@ that keymap.
    ("p" . git-gutter+-previous-hunk)
    ("s" . git-gutter+-stage-hunks)
    ("r" . git-gutter+-revert-hunk)))
+@end group
 @end lisp
 
-@findex :exit, inside :repeat-map and :bind
+@findex :exit@r{, inside} :repeat-map@r{ and} :bind
+@cindex binding commands used at end of repeat series
 Specifying @code{:exit} inside the scope of @code{:repeat-map} will
-prevent the @code{repeat-map} property being set, so that the command
-can be used from within the repeat map, but after it using it the repeat
+prevent the @code{repeat-map} property from being set, so that the command
+can be used from within the repeat map, but after using it the repeat
 map will no longer be available.  This is useful for commands often used
-at the end of a series of repeated commands:
+at the end of a series of repeated commands.  Example:
 
 @lisp
+@group
 (use-package git-gutter+
   :bind
   (:repeat-map my/git-gutter+-repeat-map
@@ -970,14 +1111,16 @@ at the end of a series of repeated commands:
    ("c" . magit-commit-create)
    ("C" . magit-commit)
    ("b" . magit-blame)))
+@end group
 @end lisp
 
-@findex :continue, inside :repeat-map and :bind
+@findex :continue@r{, inside} :repeat-map@r{ and} :bind
 Specifying @code{:continue} @emph{forces} setting the
 @code{repeat-map} property (just like @emph{not} specifying
 @code{:exit}), so the above snippet is equivalent to:
 
 @lisp
+@group
 (use-package git-gutter+
   :bind
   (:repeat-map my/git-gutter+-repeat-map
@@ -990,10 +1133,12 @@ Specifying @code{:continue} @emph{forces} setting the
    ("p" . git-gutter+-previous-hunk)
    ("s" . git-gutter+-stage-hunks)
    ("r" . git-gutter+-revert-hunk)))
+@end group
 @end lisp
 
 @node Displaying keybindings
-@subsection Displaying personal keybinding
+@subsection Displaying personal keybindings
+@cindex display your keybindings
 
 @findex describe-personal-keybindings
 The @code{:bind} keyword uses the @code{bind-keys} macro from the
@@ -1001,7 +1146,7 @@ The @code{:bind} keyword uses the @code{bind-keys} macro from the
 all keybindings you make, so that you can display them separately from
 the default keybindings.
 
-Use @w{@code{M-x describe-personal-keybindings}} to see all
+Use @w{@kbd{M-x describe-personal-keybindings}} to see all
 keybindings you've set using either the @code{:bind} keyword or the
 @code{bind-keys} macro.
 
@@ -1010,7 +1155,8 @@ keybindings you've set using either the @code{:bind} keyword or the
 
 @cindex hooks
 @findex :hook
-The @code{:hook} keyword allows adding functions onto hooks.  It takes
+The @code{:hook} keyword allows adding functions to hooks.  It takes
+@c FIXME: The actual forms accepted by :hook are different, see below!
 one argument of the form @var{hooks}, specifying one or more functions
 to add to one or more hooks.  For the purposes of @code{:hook}, the
 name of hook variables should always exclude the @samp{-hook} suffix.
@@ -1021,17 +1167,21 @@ that sets up autoloads for @code{company-mode} from the @samp{company}
 package, and adds @samp{company-mode} to @code{prog-mode-hook}:
 
 @lisp
+@group
 (use-package company
   :commands company-mode
   :init
   (add-hook 'prog-mode-hook #'company-mode))
+@end group
 @end lisp
 
 Using @code{:hook}, this can be simplified to:
 
 @lisp
+@group
 (use-package company
   :hook (prog-mode . company-mode))
+@end group
 @end lisp
 
 Here, @code{:hook} will automatically set up autoloads for the
@@ -1044,8 +1194,10 @@ function you want to add is the same as the package name with
 simplify the above to the equivalent:
 
 @lisp
+@group
 (use-package company
   :hook prog-mode)
+@end group
 @end lisp
 
 @cindex multiple hooks
@@ -1053,21 +1205,29 @@ You can also provide a list of hooks.  When multiple hooks should be
 applied, the following examples are all equivalent:
 
 @lisp
+@group
 (use-package company
   :hook (prog-mode text-mode))
+@end group
 
+@group
 (use-package company
   :hook ((prog-mode text-mode) . company-mode))
+@end group
 
+@group
 (use-package company
   :hook ((prog-mode . company-mode)
          (text-mode . company-mode)))
+@end group
 
+@group
 (use-package company
   :commands company-mode
   :init
   (add-hook 'prog-mode-hook #'company-mode)
   (add-hook 'text-mode-hook #'company-mode))
+@end group
 @end lisp
 
 One common mistake when using @code{:hook} is to forget to omit the
@@ -1076,9 +1236,11 @@ automatically.  Therefore, the following will not work, as it attempts
 to add a function to non-existent @code{prog-mode-hook-hook}:
 
 @lisp
+@group
 ;; DOES NOT WORK
 (use-package ace-jump-mode
   :hook (prog-mode-hook . ace-jump-mode))
+@end group
 @end lisp
 
 @vindex use-package-hook-name-suffix
@@ -1095,12 +1257,16 @@ implied by @code{:hook}.
 
 @node Modes and interpreters
 @section Modes and interpreters
+@cindex @code{auto-mode-alist} customization
+@cindex @code{interpreter-mode-alist} customization
+@cindex setting up major modes
 
 @findex :mode
 @findex :interpreter
 Similar to @code{:bind}, you can use @code{:mode} and
 @code{:interpreter} to establish a deferred binding within the
-@code{auto-mode-alist} and @code{interpreter-mode-alist} variables.
+@code{auto-mode-alist} and @code{interpreter-mode-alist} variables
+(@pxref{Auto Major Mode,,, elisp, GNU Emacs Lisp Reference Manual}).
 The specifier to either keyword can be a cons cell, a list of cons
 cells, or a string or regexp.
 
@@ -1112,51 +1278,63 @@ first line of the file (known as the ``shebang'') matches the string
 @code{"ruby"}:
 
 @lisp
+@group
 (use-package ruby-mode
   :mode "\\.rb\\'"
   :interpreter "ruby")
+@end group
 @end lisp
 
 The default @code{python-mode} configuration can be reproduced using
-the below declaration.  Note that the package that should be loaded
+the declaration below.  Note that the package that should be loaded
 differs from the mode name in this case, so we must use a cons:
 
 @lisp
+@group
 ;; The package is "python" but the mode is "python-mode":
 (use-package python
   :mode ("\\.py\\'" . python-mode)
   :interpreter ("python" . python-mode))
+@end group
 @end lisp
 
 Both the @code{:mode} and @code{:interpreter} keywords also accept a
 list of regexps:
 
 @lisp
+@group
 (use-package foo
   ;; Equivalent to "\\(ba[rz]\\)\\'":
   :mode ("\\.bar\\'" "\\.baz\\'")
   ;; Equivalent to "\\(foo[ab]\\)":
   :interpreter ("fooa" "foob"))
+@end group
 @end lisp
 
 @node Magic handlers
 @section Magic handlers
+@cindex @code{magic-mode-alist} customization
 
 @findex :magic
 @findex :magic-fallback
 Similar to @code{:mode} and @code{:interpreter}, you can also use
 @code{:magic} and @code{:magic-fallback} to cause certain function to
-be run if the beginning of a file matches a given regular expression.
-The difference between @code{:magic} and @code{:magic-fallback}, is
-that the latter has a lower priority than @code{:mode}.
+be run if the beginning of a file matches a given regular expression,
+as if these regular expressions were added to @code{magic-mode-alist}
+and @code{magic-fallback-mode-alist} (@pxref{Auto Major Mode,,, elisp,
+GNU Emacs Lisp Reference Manual}).  The difference between
+@code{:magic} and @code{:magic-fallback}, is that the latter has a
+lower priority than @code{:mode}.
 
 Here is an example:
 
 @lisp
+@group
 (use-package pdf-tools
   :magic ("%PDF" . pdf-view-mode)
   :config
   (pdf-tools-install :no-query))
+@end group
 @end lisp
 
 This registers an autoloaded command for @code{pdf-view-mode}, defers
@@ -1165,53 +1343,67 @@ beginning of a buffer matches the string @code{"%PDF"}.
 
 @node User options
 @section User options
+@cindex customization of variables
+@cindex variable customizations
+@cindex user options, setting
 
 @findex :custom
 In Emacs, you normally set customizable variables (user options) using
 the @code{M-x customize} interface (@pxref{Easy Customization,,,
-emacs, GNU Emacs Manual}).  We recommended this method for most users.
+emacs, GNU Emacs Manual}).  We recommend this method for most users.
 However, it is also possible to set them in your @code{use-package}
 declarations by using the @code{:custom} keyword.
 
 @lisp
+@group
 (use-package comint
   :defer t
   :custom
   (comint-buffer-maximum-size 20000 "Increase comint buffer size.")
   (comint-prompt-read-only t "Make the prompt read only."))
+@end group
 @end lisp
 
 This is better than using @code{setq} in a @code{:config} block, as
 customizable variables might have some code associated with it that
-Emacs will execute when you assign values to them.  In Emacs 29, there
-is also the new @code{setopt} macro that does this for you.
-
-Note that the values customized using this keyword are @emph{not}
-saved in the standard Emacs @code{custom-file}.  You should therefore
-set each user option using either the @code{:custom} keyword @emph{or}
-@w{@code{M-x customize-option}}, which will save customized values in
-the Emacs @code{custom-file}.  Do not use both for the same variable,
-as this risk having conflicting values in your use-package declaration
-and your @code{custom-file}.  This can lead to problems that are both
-tricky and tedious to debug.
+Emacs will execute when you assign values to them.  (In Emacs 29 and
+later, there is also the new @code{setopt} macro that does this for
+you.)
+
+Note that the values customized using @code{:custom} are @emph{not}
+saved in the standard Emacs @code{custom-file} (@pxref{Saving
+Customizations,,, emacs, GNU Emacs Manual}).  You should therefore set
+each user option using either the @code{:custom} keyword @emph{or}
+@w{@kbd{M-x customize-option}} command; the latter will save
+customized values in the Emacs @code{custom-file}.  Do not use both
+for the same variable, as this risks having conflicting values in your
+use-package declaration and your @code{custom-file}, which can lead to
+problems that are both tricky and tedious to debug.
 
 @node Faces
 @section Faces
+@cindex faces, setting
+@cindex customization of faces
 
 @findex :custom-face
-The @code{:custom-face} keyword allows customization of package custom
-faces.
+The @code{:custom-face} keyword allows customization of package's
+faces.  Example:
 
 @lisp
+@group
 (use-package eruby-mode
   :custom-face
   (eruby-standard-face ((t (:slant italic)))))
+@end group
 
+@group
 (use-package example
   :custom-face
   (example-1-face ((t (:foreground "LightPink"))))
   (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
+@end group
 
+@group
 (use-package zenburn-theme
   :preface
   (setq my/zenburn-colors-alist
@@ -1220,17 +1412,19 @@ faces.
   (region ((t (:background ,(alist-get my/zenburn-colors-alist 'cyan)))))
   :config
   (load-theme 'zenburn t))
+@end group
 @end lisp
 
 @node Hiding minor modes
 @section Hiding minor modes with diminish and delight
+@cindex hiding minor modes
 
-@code{use-package} supports the diminish and delight packages, both of
-which make it possible remove or change minor mode strings in your
-mode-line.  Which one to use is up to you, but you should normally
-only use one or the other -- never both.@footnote{When in doubt, you
-might as well use diminish.}  To use either of them, you must first
-install the corresponding package from @acronym{GNU ELPA}.
+@code{use-package} supports the @file{diminish} and @file{delight}
+packages, both of which make it possible to remove or change minor mode
+strings in your mode-line.  Which one to use is up to you, but you
+should normally only use one or the other -- never both.@footnote{When
+in doubt, you might as well use @file{diminish}.}  To use either of them, you
+must first install the corresponding package from @acronym{GNU} @acronym{ELPA}.
 
 @menu
 * Diminish::                    Hiding minor modes with Diminish.
@@ -1241,61 +1435,72 @@ install the corresponding package from @acronym{GNU ELPA}.
 @subsection Diminish
 
 @findex :diminish
-When diminish@footnote{The diminish package is installable from
-@acronym{GNU ELPA}.} is installed, you can use the @code{:diminish}
-keyword.  If diminish is not installed, the @code{:diminish} keyword
+When diminish@footnote{The @file{diminish} package is installable from
+@acronym{GNU} @acronym{ELPA}.} is installed, you can use the @code{:diminish}
+keyword.  If @file{diminish} is not installed, the @code{:diminish} keyword
 does nothing.
 
 First, add the following declaration to the beginning of your init
-file.  The optional @w{@code{:ensure t}} makes sure the package is
-installed if it isn't already (@pxref{Installing packages}).
+file.
 
 @lisp
 (use-package diminish :ensure t)
 @end lisp
 
-The @code{:diminish} keyword takes either a minor mode symbol, a cons
-of the symbol and its replacement string, or just a replacement
-string, in which case the minor mode symbol is guessed to be the
-package name with @samp{-mode} appended at the end:
+@noindent
+The optional @w{@code{:ensure t}} makes sure the package is installed
+if it isn't already (@pxref{Installing packages}).
+
+The @code{:diminish} keyword takes as its argument either a minor mode
+symbol, a cons of the symbol and its replacement string, or just a
+replacement string, in which case the minor mode symbol is guessed to
+be the package name with @samp{-mode} appended at the end:
 
 @lisp
+@group
 (use-package abbrev
   :diminish abbrev-mode
   :config
   (if (file-exists-p abbrev-file-name)
       (quietly-read-abbrev-file)))
+@end group
 @end lisp
 
 @node Delight
 @subsection Delight
 
 @findex :delight
-When delight@footnote{The @samp{delight} package is installable from
-GNU ELPA.} is installed, you can use the @code{:delight} keyword.  If
-delight is not installed, the @code{:delight} keyword does nothing.
+When @file{delight}@footnote{The @file{delight} package is installable from
+@acronym{GNU} @acronym{ELPA}.} is installed, you can use the
+@code{:delight} keyword.  If @file{delight} is not installed, the
+@code{:delight} keyword does nothing.
 
 First, add the following declaration to the beginning of your init
-file.  The optional @w{@code{:ensure t}} makes sure the package is
-installed if it isn't already (@pxref{Installing packages}).
+file.
 
 @lisp
 (use-package delight :ensure t)
 @end lisp
 
-The @code{:delight} keyword takes a minor mode symbol, a replacement
-string, or quoted mode line data (in which case the minor mode symbol
-is assumed to be the package name with @samp{-mode} appended at the
-end), both of these, or several lists of both.  @xref{Mode Line
-Data,,, elisp, GNU Emacs Lisp Reference Manual}.  If no arguments are
-provided, the default mode name is hidden completely.
+@noindent
+The optional @w{@code{:ensure t}} makes sure the package is installed
+if it isn't already (@pxref{Installing packages}).
+
+The @code{:delight} keyword takes as its argument a minor mode symbol,
+a replacement string, or quoted mode line data (in which case the
+minor mode symbol is assumed to be the package name with @samp{-mode}
+appended at the end), both of these, or several lists of both.
+@xref{Mode Line Data,,, elisp, GNU Emacs Lisp Reference Manual}.  If
+no arguments are provided, the default mode name is hidden completely.
 
 For example, the following hides everything for the @samp{foo-mode}
 minor mode in the @samp{foo} package:
 
 @lisp
+@group
 (use-package foo
   :delight)
+@end group
 @end lisp
 
 If the mode name doesn't match the package name with @samp{-mode}
@@ -1303,28 +1508,35 @@ appended, provide a symbol instead.  For example, the following hides
 @code{auto-revert-mode} from the mode line:
 
 @lisp
+@group
 ;; Don't show anything for auto-revert-mode, which doesn't match
 ;; its package name.
 (use-package autorevert
   :delight auto-revert-mode)
+@end group
 @end lisp
 
-You can also run arbitrary Lisp code.  For example, to replace
-@samp{foo-mode} with the value of the current buffer:
+You can also use arbitrary Lisp code as argument of @code{:delight}.
+For example, to replace @samp{foo-mode} with the value of the current
+buffer:
 
 @lisp
+@group
 (use-package foo
   :delight '(:eval buffer-file-name))
+@end group
 @end lisp
 
 Here is an example of hiding several built-in minor modes:
 
 @lisp
+@group
 ;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
 (use-package emacs
   :delight
   (auto-fill-function " AF")
   (visual-line-mode))
+@end group
 @end lisp
 
 @c ----------------------------------------------------------------------------
@@ -1334,7 +1546,7 @@ Here is an example of hiding several built-in minor modes:
 The standard Emacs package manager is documented in the Emacs manual
 (@pxref{Package Installation,,, emacs, GNU Emacs Manual}).  The
 @code{use-package} macro provides the @code{:ensure} and @code{:pin}
-keywords, that interface with that package manager to automatically
+keywords that interface with that package manager to automatically
 install packages.  This is particularly useful if you use your init
 file on more than one system.
 
@@ -1346,6 +1558,7 @@ file on more than one system.
 
 @node Install package
 @section Installing package
+@cindex installing packages from archives
 
 @findex :ensure
 The @code{:ensure} keyword makes use-package ask the Emacs package
@@ -1355,25 +1568,32 @@ system.
 For example:
 
 @lisp
+@group
 (use-package magit
   :ensure t)
+@end group
 @end lisp
 
 If you need to install a different package from the one named by
 @code{use-package}, you can use a symbol:
 
 @lisp
+@group
 (use-package tex
   :ensure auctex)
+@end group
 @end lisp
 
+@vindex use-package-always-ensure
 You can customize the user option @code{use-package-always-ensure} to
-non-@code{nil} if you want this behavior to be global for all
-packages.
+a non-@code{nil} value if you want this behavior to be global for all
+packages:
 
 @lisp
+@group
 (require 'use-package-ensure)
 (setq use-package-always-ensure t)
+@end group
 @end lisp
 
 @noindent
@@ -1382,23 +1602,27 @@ You can override the above setting for a single package by adding
 
 @node Pinning packages
 @section Pinning packages using @code{:pin}
+@cindex installing package from specific archive
+@cindex pinning a package to archive
 
 @findex :pin
-use-package can pin a package to a specific archive using the
+use-package can @dfn{pin} a package to a specific archive using the
 @code{:pin} keyword.@footnote{The @code{:pin} keyword has no effect on
 Emacs versions older than 24.4.}  This allows you to mix and match
 packages from different archives.  The primary use-case for this is
-preferring to install packages from @acronym{GNU ELPA} or
-@acronym{NonGNU ELPA} (indicated by @code{gnu} and @code{nongnu},
+preferring to install packages from @acronym{GNU} @acronym{ELPA} or
+@acronym{NonGNU} @acronym{ELPA} (indicated by @code{gnu} and @code{nongnu},
 respectively), while installing specific packages from third-party
 archives.
 
 For example:
 
 @lisp
+@group
 (use-package company
   :ensure t
   :pin gnu)   ; GNU ELPA
+@end group
 @end lisp
 
 @vindex use-package-always-pin
@@ -1410,6 +1634,7 @@ strongly encourage you to customize @code{use-package-always-pin} to
 package that has been specifically marked for release by its
 developer, and not a development snapshot.
 
+@cindex manual update of packages
 @c FIXME: This needs clarifying.  AFAIK, :ensure does not update packages.
 If you want to manually keep a package updated and ignore upstream
 updates, you can pin it to @samp{manual}.  This will work as long as
@@ -1419,10 +1644,12 @@ you have not customized a repository to use that name in the
 Example:
 
 @lisp
+@group
 (use-package org
   :ensure t
   ;; ignore org-mode from upstream and use a manually installed version
   :pin manual)
+@end group
 @end lisp
 
 @code{use-package} signals an error if you try to pin a package to an
@@ -1431,10 +1658,13 @@ from the special @samp{manual} archive).
 
 @node Other package managers
 @section Non-standard package managers
+@cindex non-standard package managers
+@cindex package managers, other than @file{package.el}
+@cindex installing using non-standard package managers
 
-By default, use-package assumes that you are using the built-in
-@code{package.el} package manager.  We expect that most users will
-find that it is more than capable enough, even for advanced use cases.
+By default, use-package assumes that you are using the Emacs built-in
+@file{package.el} package manager.  We expect that most users will
+find that it is capable enough, even for advanced use cases.
 
 @vindex use-package-ensure-function
 However, some users might prefer to use a third-party package manager
@@ -1450,12 +1680,13 @@ them directly to the developers of that package manager.
 @c ----------------------------------------------------------------------------
 @node Byte-compiling
 @chapter Byte-compiling your init file
+@cindex byte-compiling your init file
 
 Some users might want to byte-compile their init file to make Emacs
-startup even faster.  This is not recommended in most cases, as the
+startup faster.  This is not recommended in most cases, as the
 speed-up is often too small to be worth it, and can lead to confusion
 if the byte-compiled files are out-of-date.  If you still want to do
-it, read on.
+it, this chapter explains how to do that.
 
 @code{use-package} always loads every library that it can while a file
 is being byte-compiled.  This helps silence spurious warnings about
@@ -1463,23 +1694,27 @@ unknown variables and functions.
 
 @findex :defines
 @findex :functions
+@cindex silence byte-compilation warnings
 However, there are times when this is just not enough.  For those
 times, use the @code{:defines} and @code{:functions} keywords to
 introduce dummy variable and function declarations solely for the sake
 of silencing byte-compiler warnings.  For example:
 
 @lisp
+@group
 (use-package texinfo
   :defines texinfo-section-list
   :commands texinfo-mode
   :init
   (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
+@end group
 @end lisp
 
 If you need to silence a missing function warning, you can use
 @code{:functions}:
 
 @lisp
+@group
 (use-package ruby-mode
   :mode "\\.rb\\'"
   :interpreter "ruby"
@@ -1488,12 +1723,14 @@ If you need to silence a missing function warning, you can use
   (defun my-ruby-mode-hook ()
     (require 'inf-ruby)
     (inf-ruby-keys))
+@end group
 
   (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
 @end lisp
 
 @findex :no-require
 @cindex prevent a package from loading at compile-time
+@cindex package loading at byte-compilation time, prevent
 Normally, @code{use-package} will load each package at compile time
 before compiling the configuration, to ensure that any necessary
 symbols are in scope to satisfy the byte-compiler.  At times this can
@@ -1503,21 +1740,23 @@ configuration to the @code{eval-after-load} hook.  In such cases, use
 the @code{:no-require} keyword:
 
 @lisp
+@group
 (use-package foo
   :no-require t
   :config
   (message "Evaluate this immediately after loading `foo'"))
+@end group
 @end lisp
 
 @c ----------------------------------------------------------------------------
 @node Troubleshooting
 @chapter Troubleshooting
 
-@cindex troubleshooting
-@cindex debugging
+@cindex troubleshooting use-package
+@cindex debugging use-package
 If an error occurs while initializing or configuring a package, this
 will not stop your Emacs from loading.  Instead, @code{use-package}
-captures the error and reports it in a special @code{*Warnings*} popup
+captures the error and reports it in a special @file{*Warnings*} popup
 buffer, so that you can debug the situation in an otherwise functional
 Emacs.
 
@@ -1528,11 +1767,13 @@ that flag, add the following to your init file (these options are
 documented below):
 
 @lisp
+@group
 (when init-file-debug
   (setq use-package-verbose t
         use-package-expand-minimally nil
         use-package-compute-statistics t
         debug-on-error t))
+@end group
 @end lisp
 
 @cindex reporting bugs
@@ -1552,6 +1793,8 @@ their output in any bugs you file for use-package.
 
 @node Troubleshooting Options
 @section Options that help when troubleshooting
+@cindex options for troubleshooting
+@cindex troubleshooting, options that help
 
 @vindex use-package-expand-minimally
 By default, use-package will attempts to catch and report errors that
@@ -1568,9 +1811,10 @@ the error object (as generated by @code{condition-case}).  For
 example:
 
 @lisp
+@group
 (use-package example
-  ;; Note that errors are never trapped in the preface, since doing so would
-  ;; hide definitions from the byte-compiler.
+  ;; Note that errors are never trapped in the preface, since
+  ;; doing so would hide definitions from the byte-compiler.
   :preface (message "I'm here at byte-compile and load time")
   :init (message "I'm always here at startup")
   :config
@@ -1580,20 +1824,23 @@ example:
   :no-require t
   :catch (lambda (keyword err)
            (message (error-message-string err))))
+@end group
 @end lisp
 
 Evaluating the above form will print these messages:
 
 @verbatim
-I’m here at byte-compile and load time
-I’m always here at startup
+I'm here at byte-compile and load time
+I'm always here at startup
 Configuring package example...
-I’m always here after the package is loaded
+I'm always here after the package is loaded
 oops
 @end verbatim
 
 @node Gathering Statistics
 @section Gathering Statistics
+@cindex gathering use-package statistics
+@cindex usage statistics for use-package
 
 @vindex use-package-verbose
 When a package is loaded, and if you have @code{use-package-verbose}
@@ -1616,21 +1863,21 @@ buffer displayed is a tabulated list.  To sort rows based on a
 particular column, move point to it and type @kbd{S}, or click the
 column name at the top of the buffer on graphical displays.
 
-@cindex use-package-reset-statistics
+@findex use-package-reset-statistics
 To reset all statistics that use-package has gathered for the current
 Emacs invocation, run the command @kbd{M-x use-package-reset-statistics}.
 
-Note that, if you are setting @code{use-package-compute-statistics}
+Note that if you are setting @code{use-package-compute-statistics}
 directly in your init file, and not with @code{customize}, you must do
 this after loading @code{use-package}, but before any
 @code{use-package} forms.
 
 @node Disabling a package
 @section Disabling a package
-
 @cindex disable package
+
 @findex :disabled
-The @code{:disabled} keyword inhibits loading a package, and all it's
+The @code{:disabled} keyword inhibits loading a package, and all its
 customizations.  It is equivalent to commenting out or deleting the
 definition.
 
@@ -1641,8 +1888,10 @@ you're not currently using.
 This example disables the @samp{foo} package:
 
 @lisp
+@group
 (use-package foo
   :disabled)
+@end group
 @end lisp
 
 When byte-compiling your init file, use-package omits disabled
@@ -1652,6 +1901,8 @@ faster.
 @c ----------------------------------------------------------------------------
 @node Keyword extensions
 @appendix Keyword extensions
+@cindex keyword extension
+@cindex extending use-package keywords
 
 use-package is based on an extensible framework that makes it easy for
 package authors to add new keywords, or modify the behavior of
@@ -1666,7 +1917,7 @@ be optionally enabled.
 @end menu
 
 @node use-package-ensure-system-package
-@section :use-package-ensure-system-package
+@appendixsec :use-package-ensure-system-package
 
 @findex :ensure-system-package
 The @code{:ensure-system-package} keyword allows you to ensure certain
@@ -1688,14 +1939,16 @@ Now you can use the @code{:ensure-system-package} keyword.
 Here's an example usage:
 
 @lisp
+@group
 (use-package foo
   :ensure-system-package foo)
+@end group
 @end lisp
 
 This will expect a global binary package to exist called @code{foo}.
 If it does not, it will use your system package manager to attempt an
 install of a binary by the same name asynchronously.  This requires
-the GNU ELPA package
+the @acronym{GNU} @acronym{ELPA} package
 @uref{https://gitlab.com/jabranham/system-packages,@samp{system-packages}},
 so for this to work you must install that first.
 
@@ -1703,8 +1956,10 @@ One way of making sure it is installed is with @code{use-package}
 together with @code{:ensure}.
 
 @lisp
+@group
 (use-package system-packages
   :ensure t)
+@end group
 @end lisp
 
 For example, on a @code{Debian GNU/Linux} system, this would call
@@ -1714,9 +1969,11 @@ If the package is named differently than the binary, you can use a
 cons in the form of @code{(binary . package-name)}.  For example:
 
 @lisp
+@group
 (use-package foo
   :ensure-system-package
   (foocmd . foo))
+@end group
 @end lisp
 
 On a @code{Debian GNU/Linux} system, this would call @code{apt install
@@ -1725,36 +1982,42 @@ foo} if Emacs could not locate the executable
 @code{executable-find} function, which is what @samp{system-packages}
 uses internally.}
 
-@code{:ensure-system-package} can also take a cons where its
+@code{:ensure-system-package} can also take a cons where the
 @code{cdr} is a string that will get called by
 @code{(async-shell-command)} to install if it isn't found.  This does
-not depend upon any external package.
+not depend on any external package.
 
 @lisp
+@group
 (use-package tern
   :ensure-system-package (tern . "npm i -g tern"))
+@end group
 @end lisp
 
 To install several packages, you can pass in a list of conses:
 
 @lisp
+@group
 (use-package ruby-mode
   :ensure-system-package
   ((rubocop     . "gem install rubocop")
    (ruby-lint   . "gem install ruby-lint")
    (ripper-tags . "gem install ripper-tags")
    (pry         . "gem install pry")))
+@end group
 @end lisp
 
 Finally, in case the package dependency does not provide a global
-executable, you can ensure packages exist by checking the presence of a
-file path by providing a string like so:
+executable, you can ensure that packages exist by checking the
+presence of a file by providing a string like so:
 
 @lisp
+@group
 (use-package dash-at-point
   :if (eq system-type 'darwin)
   :ensure-system-package
   ("/Applications/Dash.app" . "brew cask install dash"))
+@end group
 @end lisp
 
 @code{:ensure-system-package} will use @code{system-packages-install}
@@ -1768,7 +2031,8 @@ commands.  Custom commands should include the call to sudo in the
 command if needed.
 
 @node Creating an extension
-@section How to create an extension keyword
+@appendixsec How to create an extension keyword
+@cindex extension keywords
 
 This section describes how to create a new keyword.
 
@@ -1794,6 +2058,7 @@ Define a normalizer for your keyword by defining a function named
 after the keyword, for example:
 
 @lisp
+@group
 (defun use-package-normalize/:pin (name-symbol keyword args)
   (use-package-only-one (symbol-name keyword) args
     (lambda (label arg)
@@ -1803,6 +2068,7 @@ after the keyword, for example:
        (t
         (use-package-error
          ":pin wants an archive name (a string)"))))))
+@end group
 @end lisp
 
 @item
@@ -1810,13 +2076,13 @@ Create a handler.
 
 Once you have a normalizer, you must create a handler for the keyword.
 
-Handlers can affect the handling of keywords in two ways.  First, it
+Handlers can affect the handling of keywords in two ways.  First, they
 can modify the @code{state} plist before recursively processing the
 remaining keywords, to influence keywords that pay attention to the
 state (one example is the state keyword @code{:deferred}, not to be
 confused with the @code{use-package} keyword @code{:defer}).  Then,
 once the remaining keywords have been handled and their resulting
-forms returned, the handler may manipulate, extend, or just ignore
+forms returned, the handlers may manipulate, extend, or just ignore
 those forms.
 
 The task of each handler is to return a @emph{list of forms}
@@ -1830,6 +2096,7 @@ minimum code necessary is emitted as the result of a
 This is an example handler:
 
 @lisp
+@group
 (defun use-package-handler/:pin (name-symbol keyword archive-name rest state)
   (let ((body (use-package-process-keywords name-symbol rest state)))
     ;; This happens at macro expansion time, not when the expanded code is
@@ -1841,16 +2108,17 @@ This is an example handler:
        body
        `((push '(,name-symbol . ,archive-name)
                package-pinned-packages))))))
+@end group
 @end lisp
 
 @item
 Test it.
 
 After the keyword has been inserted into @code{use-package-keywords},
-and a normalizer and a handler defined, you can now test it by seeing
-how usages of the keyword will expand.  For this, use @code{M-x
-pp-macroexpand-last-sexp} with the cursor set immediately after the
-@code{(use-package ...)} expression.
+and a normalizer and a handler has been defined, you can now test the
+keyword by seeing how usages of the keyword will expand.  For this,
+use @w{@kbd{M-x pp-macroexpand-last-sexp}} with the cursor set
+immediately after the @code{(use-package @dots{})} expression.
 @end enumerate
 
 @c ----------------------------------------------------------------------------
diff --git a/etc/NEWS.29 b/etc/NEWS.29
index 67711fd7666..e4a19e29869 100644
--- a/etc/NEWS.29
+++ b/etc/NEWS.29
@@ -2002,14 +2002,14 @@ After Emacs 29.1, some aspects of EUDC will be deprecated.  The goal
 of these deprecations is to simplify EUDC server configuration by
 making 'eudc-server-hotlist' the only place to add servers.  There
 will not be a need to set the server using the 'eudc-set-server'
-function.  Instead, the 'eudc-server-hotlist' variable should be
+command.  Instead, the 'eudc-server-hotlist' user option should be
 customized to have an entry for the server.  The plan is to obsolete
-the 'eudc-hotlist' editor since Customize is sufficient for changing
-'eudc-server-hotlist'.  How the 'eudc-server' variable works in this
+the 'eudc-hotlist' package since Customize is sufficient for changing
+'eudc-server-hotlist'.  How the 'eudc-server' user option works in this
 context is to-be-determined; it can't be removed, because that would
 break compatibility, but it may become synchronized with
-'eudc-server-hotlist' so that 'eudc-server' is always equal to (first
-eudc-server-hotlist).  The first entry in 'eudc-server-hotlist' is the
+'eudc-server-hotlist' so that 'eudc-server' is always equal to '(car
+eudc-server-hotlist)'.  The first entry in 'eudc-server-hotlist' is the
 first server tried by 'eudc-expand-try-all'.  The hotlist
 simplification will allow 'eudc-query-form' to show a drop down of
 possible servers, instead of requiring a call to 'eudc-set-server'
@@ -2967,7 +2967,7 @@ Protocol (LSP).
 use-package is shipped with Emacs.  It provides the 'use-package'
 macro, which allows you to isolate package configuration in your init
 file in a way that is declarative, tidy, and performance-oriented.
-See the new Info manual 'use-package' for more.
+See the new Info manual "(use-package) Top" for more.
 
 +++
 ** New commands 'image-crop' and 'image-cut'.
@@ -3017,13 +3017,13 @@ when visiting JSON files.
 A major mode based on the tree-sitter library for editing programs
 in the TypeScript language.  It includes support for font-locking,
 indentation, and navigation.  This mode will be auto-enabled for
-files with the '.ts' extension.
+files with the ".ts" extension.
 
 ** New major mode 'tsx-ts-mode'.
 A major mode based on the tree-sitter library for editing programs
 in the TypeScript language, with support for TSX.  It includes
 support for font-locking, indentation, and navigation.  This mode
-will be auto-enabled for files with the '.tsx' extension.
+will be auto-enabled for files with the ".tsx" extension.
 
 ** New major mode 'c-ts-mode'.
 A major mode based on the tree-sitter library for editing programs
@@ -4418,7 +4418,7 @@ variable for compatibility but its limiting powers have been taken away.
 This function returns a completion table designed to ease
 communication between Emacs's completion facilities and external tools
 offering completion services, particularly tools whose full working
-set is too big to transfer to Emacs's every time a completion is
+set is too big to transfer to Emacs every time a completion is
 needed.  The table uses new 'external' completion style exclusively
 and cannot work with regular styles such as 'basic' or 'flex'.
 
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 268d83dc449..6bb2e013c3b 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -5994,18 +5994,17 @@ See also `erc-downcase'."
   (and (erc--target-channel-p erc--target)
        (erc-get-channel-user (erc-current-nick)) t))
 
-;; This function happens to return nil in channel buffers previously
-;; parted or those from which a user had been kicked.  While this
-;; "works" for detecting whether a channel is currently subscribed to,
-;; new code should consider using
+;; While `erc-default-target' happens to return nil in channel buffers
+;; you've parted or from which you've been kicked, using it to detect
+;; whether a channel is currently joined may become unreliable in the
+;; future.  For now, new code should consider using
 ;;
 ;;   (erc-get-channel-user (erc-current-nick))
 ;;
-;; instead.  For retrieving a target regardless of subscription or
-;; connection status, use replacements based on `erc--target'.
-;; (Coming soon.)
-;;
-;; TODO deprecate this
+;; and expect a nicer option eventually.  For retrieving a target
+;; regardless of subscription or connection status, use replacements
+;; based on `erc--target' instead.  See also `erc--default-target'.
+
 (defun erc-default-target ()
   "Return the current default target (as a character string) or nil if none."
   (let ((tgt (car erc-default-recipients)))
diff --git a/lisp/net/tramp-gvfs.el b/lisp/net/tramp-gvfs.el
index 73f773e8f4d..da7641774fb 100644
--- a/lisp/net/tramp-gvfs.el
+++ b/lisp/net/tramp-gvfs.el
@@ -690,7 +690,7 @@ It has been changed in GVFS 1.14.")
     ("gvfs-set-attribute" . "set"))
   "List of cons cells, mapping \"gvfs-<command>\" to \"gio <command>\".")
 
-;; <http://www.pygtk.org/docs/pygobject/gio-constants.html>
+;; <https://www.pygtk.org/docs/pygobject/gio-constants.html>
 (eval-and-compile
   (defconst tramp-gvfs-file-attributes
     '("name"
diff --git a/lisp/progmodes/csharp-mode.el b/lisp/progmodes/csharp-mode.el
index f08e8d6506e..d0465b26f05 100644
--- a/lisp/progmodes/csharp-mode.el
+++ b/lisp/progmodes/csharp-mode.el
@@ -505,7 +505,7 @@ compilation and evaluation time conflicts."
 
 (defun csharp--compilation-error-file-resolve ()
   "Resolve an msbuild error to a (filename . dirname) cons cell."
-  ;; http://stackoverflow.com/a/18049590/429091
+  ;; https://stackoverflow.com/a/18049590/429091
   (cons (match-string 1) (file-name-directory (match-string 4))))
 
 (defconst csharp-compilation-re-msbuild-error
diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index cafb99c6d80..a53f62fc565 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -387,6 +387,11 @@ done by `eglot-reconnect'."
   "String displayed in mode line when Eglot is active."
   :type 'string)
 
+(defcustom eglot-report-progress t
+  "If non-nil, show progress of long running LSP server work"
+  :type 'boolean
+  :version "29.1")
+
 (defvar eglot-withhold-process-id nil
   "If non-nil, Eglot will not send the Emacs process id to the language server.
 This can be useful when using docker to run a language server.")
@@ -471,6 +476,7 @@ This can be useful when using docker to run a language server.")
       (TextDocumentEdit (:textDocument :edits) ())
       (TextEdit (:range :newText))
       (VersionedTextDocumentIdentifier (:uri :version) ())
+      (WorkDoneProgress (:kind) (:title :message :percentage :cancellable))
       (WorkspaceEdit () (:changes :documentChanges))
       (WorkspaceSymbol (:name :kind) (:containerName :location :data)))
     "Alist (INTERFACE-NAME . INTERFACE) of known external LSP interfaces.
@@ -541,7 +547,7 @@ on unknown notifications and errors on unknown requests."))
        for type = (or (cdr (assoc k types)) t) ;; FIXME: enforce nil type?
        unless (cl-typep v type)
        do (eglot--error "A `%s' must have a %s as %s, but has %s"
-                        interface-name )))
+                        interface-name)))
     t))
 
 (eval-and-compile
@@ -832,6 +838,9 @@ treated as in `eglot--dbind'."
    (project
     :documentation "Project associated with server."
     :accessor eglot--project)
+   (progress-reporters
+    :initform (make-hash-table :test #'equal) :accessor eglot--progress-reporters
+    :documentation "Maps LSP progress tokens to progress reporters.")
    (inhibit-autoreconnect
     :initform t
     :documentation "Generalized boolean inhibiting auto-reconnection if true."
@@ -1126,11 +1135,11 @@ INTERACTIVE is t if called interactively."
   (let ((buffer (current-buffer)))
     (cl-labels
         ((maybe-connect
-          ()
-          (remove-hook 'post-command-hook #'maybe-connect nil)
-          (eglot--when-live-buffer buffer
-            (unless eglot--managed-mode
-              (apply #'eglot--connect (eglot--guess-contact))))))
+           ()
+           (remove-hook 'post-command-hook #'maybe-connect nil)
+           (eglot--when-live-buffer buffer
+             (unless eglot--managed-mode
+               (apply #'eglot--connect (eglot--guess-contact))))))
       (when buffer-file-name
         (add-hook 'post-command-hook #'maybe-connect 'append nil)))))
 
@@ -1182,7 +1191,7 @@ Each function is passed the server as an argument")
       (list "sh" "-c"
             (string-join (cons "stty raw > /dev/null;"
                                (mapcar #'shell-quote-argument contact))
-             " "))
+                         " "))
     contact))
 
 (defvar-local eglot--cached-server nil
@@ -1236,7 +1245,7 @@ This docstring appeases checkdoc, that's all."
                      ,@more-initargs)))))
          (spread (lambda (fn) (lambda (server method params)
                                 (let ((eglot--cached-server server))
-                                 (apply fn server method (append params nil))))))
+                                  (apply fn server method (append params nil))))))
          (server
           (apply
            #'make-instance class
@@ -1570,7 +1579,7 @@ Doubles as an indicator of snippet support."
       (setq-local markdown-fontify-code-blocks-natively t)
       (insert string)
       (let ((inhibit-message t)
-            (message-log-max nil))
+            (message-log-max nil))
         (ignore-errors (delay-mode-hooks (funcall mode))))
       (font-lock-ensure)
       (string-trim (buffer-string)))))
@@ -1855,8 +1864,8 @@ If it is activated, also signal textDocument/didOpen."
                                            (force-mode-line-update t))))))
 
 (defun eglot-manual () "Open documentation."
-  (declare (obsolete info "29.1"))
-  (interactive) (info "(eglot)"))
+       (declare (obsolete info "29.1"))
+       (interactive) (info "(eglot)"))
 
 (easy-menu-define eglot-menu nil "Eglot"
   `("Eglot"
@@ -1960,17 +1969,17 @@ Uses THING, FACE, DEFS and PREPEND."
            'keymap (let ((map (make-sparse-keymap)))
                      (define-key map [mode-line down-mouse-1] eglot-server-menu)
                      map))
-       ,@(when last-error
+         ,@(when last-error
              `("/" ,(eglot--mode-line-props
                      "error" 'compilation-mode-line-fail
                      '((mouse-3 eglot-clear-status  "Clear this status"))
                      (format "An error occurred: %s\n" (plist-get last-error
-                                                                 :message)))))
-       ,@(when (cl-plusp pending)
-           `("/" ,(eglot--mode-line-props
-                   (format "%d" pending) 'warning
-                   '((mouse-3 eglot-forget-pending-continuations
-                              "Forget pending continuations"))
+                                                                  :message)))))
+         ,@(when (cl-plusp pending)
+             `("/" ,(eglot--mode-line-props
+                     (format "%d" pending) 'warning
+                     '((mouse-3 eglot-forget-pending-continuations
+                                "Forget pending continuations"))
                      "Number of outgoing, \
 still unanswered LSP requests to the server\n"))))))))
 
@@ -1988,13 +1997,13 @@ still unanswered LSP requests to the server\n"))))))))
 (defalias 'eglot--diag-data 'flymake-diagnostic-data)
 
 (cl-loop for i from 1
-         for type in '(eglot-note eglot-warning eglot-error )
+         for type in '(eglot-note eglot-warning eglot-error)
          do (put type 'flymake-overlay-control
                  `((mouse-face . highlight)
                    (priority . ,(+ 50 i))
                    (keymap . ,(let ((map (make-sparse-keymap)))
                                 (define-key map [mouse-1]
-                                  (eglot--mouse-call 'eglot-code-actions))
+                                            (eglot--mouse-call 'eglot-code-actions))
                                 map)))))
 
 
@@ -2051,6 +2060,27 @@ COMMAND is a symbol naming the command."
   "Handle notification telemetry/event.") ;; noop, use events buffer
 
 (cl-defmethod eglot-handle-notification
+  (server (_method (eql $/progress)) &key token value)
+  "Handle $/progress notification identified by TOKEN from SERVER."
+  (when eglot-report-progress
+    (cl-flet ((fmt (&rest args) (mapconcat #'identity args " ")))
+      (eglot--dbind ((WorkDoneProgress) kind title percentage message) value
+        (pcase kind
+          ("begin"
+           (let* ((prefix (format (concat "[eglot] %s %s:" (when percentage " "))
+                                  (eglot-project-nickname server) token))
+                  (pr (puthash token
+                       (if percentage
+                           (make-progress-reporter prefix 0 100 percentage 1 0)
+                         (make-progress-reporter prefix nil nil nil 1 0))
+                       (eglot--progress-reporters server))))
+             (progress-reporter-update pr percentage (fmt title message))))
+          ("report"
+           (when-let ((pr (gethash token (eglot--progress-reporters server))))
+             (progress-reporter-update pr percentage (fmt title message))))
+          ("end" (remhash token (eglot--progress-reporters server))))))))
+
+(cl-defmethod eglot-handle-notification
   (_server (_method (eql textDocument/publishDiagnostics)) &key uri diagnostics
            &allow-other-keys) ; FIXME: doesn't respect `eglot-strict-mode'
   "Handle notification publishDiagnostics."
@@ -2174,7 +2204,7 @@ THINGS are either registrations or unregisterations (sic)."
   (append
    (eglot--VersionedTextDocumentIdentifier)
    (list :languageId
-         (eglot--language-id (eglot--current-server-or-lose))
+         (eglot--language-id (eglot--current-server-or-lose))
          :text
          (eglot--widening
           (buffer-substring-no-properties (point-min) (point-max))))))
@@ -2636,7 +2666,7 @@ If BUFFER, switch to it before."
                                                uri range))))))
        (if (vectorp response) response (and response (list response)))))))
 
-(cl-defun eglot--lsp-xref-helper (method &key extra-params capability )
+(cl-defun eglot--lsp-xref-helper (method &key extra-params capability)
   "Helper for `eglot-find-declaration' & friends."
   (let ((eglot--lsp-xref-refs (eglot--lsp-xrefs-for-method
                                method
@@ -2668,7 +2698,7 @@ If BUFFER, switch to it before."
             (get-text-property 0 'eglot--lsp-workspaceSymbol probe)
           (eglot--dbind ((Location) uri range) location
             (list (eglot--xref-make-match name uri range))))
-        (eglot--lsp-xrefs-for-method :textDocument/definition))))
+      (eglot--lsp-xrefs-for-method :textDocument/definition))))
 
 (cl-defmethod xref-backend-references ((_backend (eql eglot)) _identifier)
   (or
@@ -2707,7 +2737,7 @@ for which LSP on-type-formatting should be requested."
                  `(:textDocument/onTypeFormatting
                    :documentOnTypeFormattingProvider
                    ,`(:position ,(eglot--pos-to-lsp-position beg)
-                      :ch ,(string on-type-format))))
+                                :ch ,(string on-type-format))))
                 ((and beg end)
                  `(:textDocument/rangeFormatting
                    :documentRangeFormattingProvider
@@ -3280,24 +3310,24 @@ at point.  With prefix argument, prompt for ACTION-KIND."
                                 (eglot--project server))))))
     (cl-labels
         ((handle-event
-          (event)
-          (pcase-let* ((`(,desc ,action ,file ,file1) event)
-                       (action-type (cl-case action
-                                      (created 1) (changed 2) (deleted 3)))
-                       (action-bit (when action-type
-                                     (ash 1 (1- action-type)))))
-            (cond
-             ((and (memq action '(created changed deleted))
-                   (cl-loop for (glob . kind-bitmask) in globs
-                            thereis (and (> (logand kind-bitmask action-bit) 0)
-                                         (funcall glob file))))
-              (jsonrpc-notify
-               server :workspace/didChangeWatchedFiles
-               `(:changes ,(vector `(:uri ,(eglot--path-to-uri file)
-                                          :type ,action-type)))))
-             ((eq action 'renamed)
-              (handle-event `(,desc 'deleted ,file))
-              (handle-event `(,desc 'created ,file1)))))))
+           (event)
+           (pcase-let* ((`(,desc ,action ,file ,file1) event)
+                        (action-type (cl-case action
+                                       (created 1) (changed 2) (deleted 3)))
+                        (action-bit (when action-type
+                                      (ash 1 (1- action-type)))))
+             (cond
+              ((and (memq action '(created changed deleted))
+                    (cl-loop for (glob . kind-bitmask) in globs
+                             thereis (and (> (logand kind-bitmask action-bit) 0)
+                                          (funcall glob file))))
+               (jsonrpc-notify
+                server :workspace/didChangeWatchedFiles
+                `(:changes ,(vector `(:uri ,(eglot--path-to-uri file)
+                                           :type ,action-type)))))
+              ((eq action 'renamed)
+               (handle-event `(,desc 'deleted ,file))
+               (handle-event `(,desc 'created ,file1)))))))
       (unwind-protect
           (progn
             (dolist (dir dirs-to-watch)
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index adb984c3e59..a4a8cd84050 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -54,9 +54,8 @@
 ;; (question mark) if no backends were even configured.
 ;;
 ;; For programmers interested in writing a new Flymake backend, the
-;; docstring of `flymake-diagnostic-functions', the Flymake manual,
-;; and the code of existing backends are probably a good starting
-;; point.
+;; docstring of `flymake-diagnostic-functions', the Flymake manual, and the
+;; code of existing backends are probably good starting points.
 ;;
 ;; The user wishing to customize the appearance of error types should
 ;; set properties on the symbols associated with each diagnostic type.
diff --git a/lisp/replace.el b/lisp/replace.el
index c7ae77d128b..6f59166e352 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -1101,7 +1101,10 @@ Hence, a match starting on the same line at which another match
 ended is ignored.
 
 Return the number of killed matching lines.  When called
-interactively, also print the number."
+interactively, also print the number.
+
+If you merely want to delete the lines, without adding them to
+the kill ring, the \\[flush-lines] command is faster."
   (interactive
    (progn
      (barf-if-buffer-read-only)
diff --git a/lisp/textmodes/emacs-news-mode.el b/lisp/textmodes/emacs-news-mode.el
index ebb31da9cf4..26f8f610eff 100644
--- a/lisp/textmodes/emacs-news-mode.el
+++ b/lisp/textmodes/emacs-news-mode.el
@@ -226,7 +226,7 @@ untagged NEWS entry."
         ;; Do manual references.
         (goto-char (point-min))
         (search-forward "\f" nil t)
-        (while (re-search-forward "\"\\(([a-z0-9]+)[ \n][^\"]\\{1,80\\}\\)\""
+        (while (re-search-forward "\"\\(([a-z0-9-]+)[ \n][^\"]\\{1,80\\}\\)\""
                                   nil t)
           (buttonize-region (match-beginning 1) (match-end 1)
                             (lambda (node) (info node))
diff --git a/lisp/use-package/bind-key.el b/lisp/use-package/bind-key.el
index 95685410b82..0d4c3de5d11 100644
--- a/lisp/use-package/bind-key.el
+++ b/lisp/use-package/bind-key.el
@@ -282,7 +282,7 @@ Accepts keyword arguments:
                          key in the repeat map, but will not set the
                          `repeat-map' property of the bound command.
 :continue BINDINGS     - Within the scope of `:repeat-map' forces the
-                         same behaviour as if no special keyword had
+                         same behavior as if no special keyword had
                          been used (that is, the command is bound, and
                          it's `repeat-map' property set)
 :filter FORM           - optional form to determine when bindings apply
@@ -429,7 +429,7 @@ Accepts keyword arguments:
                          key in the repeat map, but will not set the
                          `repeat-map' property of the bound command.
 :continue BINDINGS     - Within the scope of `:repeat-map' forces the
-                         same behaviour as if no special keyword had
+                         same behavior as if no special keyword had
                          been used (that is, the command is bound, and
                          it's `repeat-map' property set)
 :filter FORM           - optional form to determine when bindings apply
diff --git a/lisp/use-package/use-package-bind-key.el b/lisp/use-package/use-package-bind-key.el
index 44242c9e01d..4ebf54825c6 100644
--- a/lisp/use-package/use-package-bind-key.el
+++ b/lisp/use-package/use-package-bind-key.el
@@ -38,15 +38,14 @@
 
 ;;;###autoload
 (defun use-package-autoload-keymap (keymap-symbol package override)
-  "Loads PACKAGE and then binds the key sequence used to invoke
-this function to KEYMAP-SYMBOL. It then simulates pressing the
-same key sequence a again, so that the next key pressed is routed
-to the newly loaded keymap.
+  "Load PACKAGE and bind key sequence invoking this function to KEYMAP-SYMBOL.
+Then simulate pressing the same key sequence a again, so that the
+next key pressed is routed to the newly loaded keymap.
 
-This function supports use-package's :bind-keymap keyword. It
+This function supports use-package's :bind-keymap keyword.  It
 works by binding the given key sequence to an invocation of this
-function for a particular keymap. The keymap is expected to be
-defined by the package. In this way, loading the package is
+function for a particular keymap.  The keymap is expected to be
+defined by the package.  In this way, loading the package is
 deferred until the prefix key sequence is pressed."
   (if (not (require package nil t))
       (use-package-error (format "Cannot load package.el: %s" package))
diff --git a/src/itree.c b/src/itree.c
index 04fa9e827a2..975f3a8e4fb 100644
--- a/src/itree.c
+++ b/src/itree.c
@@ -15,7 +15,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
+along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 
 #include <config.h>
 #include <math.h>
diff --git a/src/itree.h b/src/itree.h
index 248ea9b84d2..f1e2bf3bfde 100644
--- a/src/itree.h
+++ b/src/itree.h
@@ -15,7 +15,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
+along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 
 #ifndef ITREE_H
 #define ITREE_H