9 files changed, 147 insertions, 75 deletions
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 8be8307c75f..cfef5c12d1e 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1362,6 +1362,11 @@ while matching the remainder of the specifications at this level.  This
 is primarily used to generate more specific syntax error messages.  See
 @ref{Backtracking}, for more details.  Also see the @code{let} example.
 
+@item &error
+@code{&error} should be followed by a string, an error message, in the
+edebug-spec; it aborts the instrumentation, displaying the message in
+the minibuffer.
+
 @item @var{other-symbol}
 @cindex indirect specifications
 Any other symbol in a specification list may be a predicate or an
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 0c42ebfd67a..a8d95a21011 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2192,10 +2192,11 @@ it and see if it works.)
 @vindex ns-appearance@r{, a frame parameter}
 @item ns-appearance
 Only available on macOS, if set to @code{dark} draw this frame's
-window-system window using the ``vibrant dark'' theme, otherwise use
-the system default.  The ``vibrant dark'' theme can be used to set the
-toolbar and scrollbars to a dark appearance when using an Emacs theme
-with a dark background.
+window-system window using the ``vibrant dark'' theme, and if set to
+@code{light} use the ``aqua'' theme, otherwise use the system default.
+The ``vibrant dark'' theme can be used to set the toolbar and
+scrollbars to a dark appearance when using an Emacs theme with a dark
+background.
 
 @vindex ns-transparent-titlebar@r{, a frame parameter}
 @item ns-transparent-titlebar
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 325841d8f8a..442f6d156b6 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1228,9 +1228,9 @@ the @var{runtime} structure with the value compiled into the module:
 
 @example
 int
-emacs_module_init (struct emacs_runtime *ert)
+emacs_module_init (struct emacs_runtime *runtime)
 @{
-  if (ert->size < sizeof (*ert))
+  if (runtime->size < sizeof (*runtime))
     return 1;
 @}
 @end example
@@ -1247,7 +1247,7 @@ assumes it is part of the @code{emacs_module_init} function shown
 above:
 
 @example
-  emacs_env *env = ert->get_environment (ert);
+  emacs_env *env = runtime->get_environment (runtime);
   if (env->size < sizeof (*env))
     return 2;
 @end example
@@ -1264,7 +1264,7 @@ Emacs, by comparing the size of the environment passed by Emacs with
 known sizes, like this:
 
 @example
-  emacs_env *env = ert->get_environment (ert);
+  emacs_env *env = runtime->get_environment (runtime);
   if (env->size >= sizeof (struct emacs_env_26))
     emacs_version = 26;  /* Emacs 26 or later.  */
   else if (env->size >= sizeof (struct emacs_env_25))
@@ -1314,7 +1314,8 @@ subsection describes how to write such @dfn{module functions}.
 
 A module function has the following general form and signature:
 
-@deftypefn Function emacs_value module_func (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data})
+@deftypefn Function emacs_value emacs_function (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data})
+@tindex emacs_function
 The @var{env} argument provides a pointer to the @acronym{API}
 environment, needed to access Emacs objects and functions.  The
 @var{nargs} argument is the required number of arguments, which can be
@@ -1323,7 +1324,7 @@ of the argument number), and @var{args} is a pointer to the array of
 the function arguments.  The argument @var{data} points to additional
 data required by the function, which was arranged when
 @code{make_function} (see below) was called to create an Emacs
-function from @code{module_func}.
+function from @code{emacs_function}.
 
 Module functions use the type @code{emacs_value} to communicate Lisp
 objects between Emacs and the module (@pxref{Module Values}).  The
@@ -1338,6 +1339,10 @@ However, if the user typed @kbd{C-g}, or if the module function or its
 callees signaled an error or exited nonlocally (@pxref{Module
 Nonlocal}), Emacs will ignore the returned value and quit or throw as
 it does when Lisp code encounters the same situations.
+
+The header @file{emacs-module.h} provides the type
+@code{emacs_function} as an alias type for a function pointer to a
+module function.
 @end deftypefn
 
 After writing your C code for a module function, you should make a
@@ -1348,11 +1353,11 @@ normally done in the module initialization function (@pxref{module
 initialization function}), after verifying the @acronym{API}
 compatibility.
 
-@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, subr @var{func}, const char *@var{docstring}, void *@var{data})
+@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, emacs_function @var{func}, const char *@var{docstring}, void *@var{data})
 @vindex emacs_variadic_function
 This returns an Emacs function created from the C function @var{func},
-whose signature is as described for @code{module_func} above (assumed
-here to be @code{typedef}'ed as @code{subr}).  The arguments
+whose signature is as described for @code{emacs_function} above.
+The arguments
 @var{min_arity} and @var{max_arity} specify the minimum and maximum
 number of arguments that @var{func} can accept.  The @var{max_arity}
 argument can have the special value @code{emacs_variadic_function},
@@ -1388,7 +1393,7 @@ Combining the above steps, code that arranges for a C function
 look like this, as part of the module initialization function:
 
 @example
- emacs_env *env = ert->get_environment (ert);
+ emacs_env *env = runtime->get_environment (runtime);
  emacs_value func = env->make_function (env, min_arity, max_arity,
                                         module_func, docstring, data);
  emacs_value symbol = env->intern (env, "module-func");
@@ -1442,6 +1447,54 @@ The Lisp package which goes with your module could then load the
 module using the @code{load} primitive (@pxref{Dynamic Modules}) when
 the package is loaded into Emacs.
 
+@anchor{Module Function Finalizers}
+If you want to run some code when a module function object (i.e., an
+object returned by @code{make_function}) is garbage-collected, you can
+install a @dfn{function finalizer}.  Function finalizers are available
+since Emacs 28.  For example, if you have passed some heap-allocated
+structure to the @var{data} argument of @code{make_function}, you can
+use the finalizer to deallocate the structure.  @xref{Basic
+Allocation,,,libc}, and @pxref{Freeing after Malloc,,,libc}.  The
+finalizer function has the following signature:
+
+@example
+void finalizer (void *@var{data})
+@end example
+
+Here, @var{data} receives the value passed to @var{data} when calling
+@code{make_function}.  Note that the finalizer can't interact with
+Emacs in any way.
+
+Directly after calling @code{make_function}, the newly-created
+function doesn't have a finalizer.  Use @code{set_function_finalizer}
+to add one, if desired.
+
+@deftypefun void emacs_finalizer (void *@var{ptr})
+The header @file{emacs-module.h} provides the type
+@code{emacs_finalizer} as a type alias for an Emacs finalizer
+function.
+@end deftypefun
+
+@deftypefun emacs_finalizer get_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg})
+This function, which is available since Emacs 28, returns the function
+finalizer associated with the module function represented by
+@var{arg}.  @var{arg} must refer to a module function, that is, an
+object returned by @code{make_function}.  If no finalizer is
+associated with the function, @code{NULL} is returned.
+@end deftypefun
+
+@deftypefun void set_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin})
+This function, which is available since Emacs 28, sets the function
+finalizer associated with the module function represented by @var{arg}
+to @var{fin}.  @var{arg} must refer to a module function, that is, an
+object returned by @code{make_function}.  @var{fin} can either be
+@code{NULL} to clear @var{arg}'s function finalizer, or a pointer to a
+function to be called when the object represented by @var{arg} is
+garbage-collected.  At most one function finalizer can be set per
+function; if @var{arg} already has a finalizer, it is replaced by
+@var{fin}.
+@end deftypefun
+
 @node Module Values
 @subsection Conversion Between Lisp and Module Values
 @cindex module values, conversion
@@ -1541,12 +1594,11 @@ This function returns the value of a Lisp float specified by
 @var{arg}, as a C @code{double} value.
 @end deftypefn
 
-@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{time})
-This function, which is available since Emacs 27, interprets
-@var{time} as an Emacs Lisp time value and returns the corresponding
-@code{struct timespec}.  @xref{Time of Day}.  @code{struct timespec}
-represents a timestamp with nanosecond precision.  It has the
-following members:
+@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{arg})
+This function, which is available since Emacs 27, interprets @var{arg}
+as an Emacs Lisp time value and returns the corresponding @code{struct
+timespec}.  @xref{Time of Day}.  @code{struct timespec} represents a
+timestamp with nanosecond precision.  It has the following members:
 
 @table @code
 @item time_t tv_sec
@@ -1744,9 +1796,9 @@ next_prime (emacs_env *env, ptrdiff_t nargs, emacs_value *args,
 @}
 
 int
-emacs_module_init (struct emacs_runtime *ert)
+emacs_module_init (struct emacs_runtime *runtime)
 @{
-  emacs_env *env = ert->get_environment (ert);
+  emacs_env *env = runtime->get_environment (runtime);
   emacs_value symbol = env->intern (env, "next-prime");
   emacs_value func
     = env->make_function (env, 1, 1, next_prime, NULL, NULL);
@@ -1773,16 +1825,15 @@ there's no requirement that @var{time} be normalized.  This means that
 @code{@var{time}.tv_nsec} can be negative or larger than 999,999,999.
 @end deftypefn
 
-@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen})
+@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{len})
 This function creates an Emacs string from C text string pointed by
 @var{str} whose length in bytes, not including the terminating null
-byte, is @var{strlen}.  The original string in @var{str} can be either
-an @acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII}
-string; it can include embedded null bytes, and doesn't have to end in
-a terminating null byte at @code{@var{str}[@var{strlen}]}.  The
-function raises the @code{overflow-error} error condition if
-@var{strlen} is negative or exceeds the maximum length of an Emacs
-string.
+byte, is @var{len}.  The original string in @var{str} can be either an
+@acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII} string;
+it can include embedded null bytes, and doesn't have to end in a
+terminating null byte at @code{@var{str}[@var{len}]}.  The function
+raises the @code{overflow-error} error condition if @var{len} is
+negative or exceeds the maximum length of an Emacs string.
 @end deftypefn
 
 The @acronym{API} does not provide functions to manipulate Lisp data
@@ -1839,27 +1890,32 @@ garbage-collected.  Don't run any expensive code in a finalizer,
 because GC must finish quickly to keep Emacs responsive.
 @end deftypefn
 
-@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value val)
+@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value @var{arg})
 This function extracts the C pointer from the Lisp object represented
-by @var{val}.
+by @var{arg}.
 @end deftypefn
 
-@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr})
+@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{arg}, void *@var{ptr})
 This function sets the C pointer embedded in the @code{user-ptr}
-object represented by @var{value} to @var{ptr}.
+object represented by @var{arg} to @var{ptr}.
 @end deftypefn
 
-@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val)
+@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg})
 This function returns the finalizer of the @code{user-ptr} object
-represented by @var{val}, or @code{NULL} if it doesn't have a finalizer.
+represented by @var{arg}, or @code{NULL} if it doesn't have a
+finalizer.
 @end deftypefn
 
-@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, emacs_finalizer @var{fin})
+@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin})
 This function changes the finalizer of the @code{user-ptr} object
-represented by @var{val} to be @var{fin}.  If @var{fin} is a
-@code{NULL} pointer, the @code{user-ptr} object will have no finalizer.
+represented by @var{arg} to be @var{fin}.  If @var{fin} is a
+@code{NULL} pointer, the @code{user-ptr} object will have no
+finalizer.
 @end deftypefn
 
+Note that the @code{emacs_finalizer} type works for both user pointer
+an module function finalizers.  @xref{Module Function Finalizers}.
+
 @node Module Misc
 @subsection Miscellaneous Convenience Functions for Modules
 
@@ -1870,20 +1926,20 @@ be called via the @code{emacs_env} pointer.  Description of functions
 that were introduced after Emacs 25 calls out the first version where
 they became available.
 
-@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{val1}, emacs_value @var{val2})
+@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{a}, emacs_value @var{b})
 This function returns @code{true} if the Lisp objects represented by
-@var{val1} and @var{val2} are identical, @code{false} otherwise.  This
-is the same as the Lisp function @code{eq} (@pxref{Equality
-Predicates}), but avoids the need to intern the objects represented by
-the arguments.
+@var{a} and @var{b} are identical, @code{false} otherwise.  This is
+the same as the Lisp function @code{eq} (@pxref{Equality Predicates}),
+but avoids the need to intern the objects represented by the
+arguments.
 
 There are no @acronym{API} functions for other equality predicates, so
 you will need to use @code{intern} and @code{funcall}, described
 below, to perform more complex equality tests.
 @end deftypefn
 
-@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{val})
-This function tests whether the Lisp object represented by @var{val}
+@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{arg})
+This function tests whether the Lisp object represented by @var{arg}
 is non-@code{nil}; it returns @code{true} or @code{false} accordingly.
 
 Note that you could implement an equivalent test by using
@@ -1892,12 +1948,12 @@ then use @code{eq}, described above, to test for equality.  But using
 this function is more convenient.
 @end deftypefn
 
-@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{object})
-This function returns the type of @var{object} as a value that
-represents a symbol: @code{string} for a string, @code{integer} for an
-integer, @code{process} for a process, etc.  @xref{Type Predicates}.
-You can use @code{intern} and @code{eq} to compare against known type
-symbols, if your code needs to depend on the object type.
+@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{arg})
+This function returns the type of @var{arg} as a value that represents
+a symbol: @code{string} for a string, @code{integer} for an integer,
+@code{process} for a process, etc.  @xref{Type Predicates}.  You can
+use @code{intern} and @code{eq} to compare against known type symbols,
+if your code needs to depend on the object type.
 @end deftypefn
 
 @anchor{intern}
@@ -1917,8 +1973,7 @@ calling the more powerful Emacs @code{intern} function
 emacs_value fintern = env->intern (env, "intern");
 emacs_value sym_name =
   env->make_string (env, name_str, strlen (name_str));
-emacs_value intern_args[] = @{ sym_name, env->intern (env, "nil") @};
-emacs_value symbol = env->funcall (env, fintern, 2, intern_args);
+emacs_value symbol = env->funcall (env, fintern, 1, &sym_name);
 @end example
 
 @end deftypefn
@@ -2071,11 +2126,12 @@ One use of this function is when you want to re-throw a non-local exit
 from one of the called @acronym{API} or Lisp functions.
 @end deftypefn
 
-@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{error}, emacs_value @var{data})
-This function signals the error represented by @var{error} with the
-specified error data @var{data}.  The module function should return
-soon after calling this function.  This function could be useful,
-e.g., for signaling errors from module functions to Emacs.
+@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{symbol}, emacs_value @var{data})
+This function signals the error represented by the error symbol
+@var{symbol} with the specified error data @var{data}.  The module
+function should return soon after calling this function.  This
+function could be useful, e.g., for signaling errors from module
+functions to Emacs.
 @end deftypefn
 
 
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 58936686ad7..28942820793 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1170,10 +1170,13 @@ extension, a.k.a.@: ``suffix''.  This suffix is platform-dependent.
 
 @defvar module-file-suffix
 This variable holds the system-dependent value of the file-name
-extension of the module files.  Its value is @file{.so} on POSIX hosts
-and @file{.dll} on MS-Windows.
+extension of the module files.  Its value is @file{.so} on POSIX
+hosts, @file{.dylib} on macOS, and @file{.dll} on MS-Windows.
 @end defvar
 
+  On macOS, dynamic modules can also have the suffix @file{.so} in
+addition to @file{.dylib}.
+
 @findex emacs_module_init
 @vindex plugin_is_GPL_compatible
 Every dynamic module should export a C-callable function named
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index ab806a9055d..0f60b3fd00d 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -645,6 +645,15 @@ A history list for variable-name arguments read by
 @code{read-variable}.
 @end defvar
 
+@defvar read-number-history
+A history list for numbers read by @code{read-number}.
+@end defvar
+
+@defvar goto-line-history
+A history list for arguments to @code{goto-line}.  This variable is
+buffer local.
+@end defvar
+
 @c Less common: coding-system-history, input-method-history,
 @c command-history, grep-history, grep-find-history,
 @c read-envvar-name-history, setenv-history, yes-or-no-p-history.
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index a8ddd45f891..f380f1669e0 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2673,6 +2673,7 @@ Setting this variable makes it buffer-local in the current buffer.
 @node Font Lock Mode
 @section Font Lock Mode
 @cindex Font Lock mode
+@cindex syntax highlighting and coloring
 
   @dfn{Font Lock mode} is a buffer-local minor mode that automatically
 attaches @code{face} properties to certain parts of the buffer based on
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 4be2eb6918b..4242223a48e 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -2336,8 +2336,12 @@ same sequence of character codes and all these codes are in the range
 @end group
 @end example
 
-However, two distinct buffers are never considered @code{equal}, even if
-their textual contents are the same.
+The @code{equal} function recursively compares the contents of objects
+if they are integers, strings, markers, vectors, bool-vectors,
+byte-code function objects, char-tables, records, or font objects.
+Other objects are considered @code{equal} only if they are @code{eq}.
+For example, two distinct buffers are never considered @code{equal},
+even if their textual contents are the same.
 @end defun
 
   For @code{equal}, equality is defined recursively; for example, given
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 6970f718ee0..f515213615e 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -2426,18 +2426,15 @@ server is stopped; a non-@code{nil} value means yes.
 @cindex encrypted network connections
 @cindex @acronym{TLS} network connections
 @cindex @acronym{STARTTLS} network connections
-Emacs can create encrypted network connections, using either built-in
-or external support.  The built-in support uses the GnuTLS
-Transport Layer Security Library; see
+Emacs can create encrypted network connections, using the built-in
+support for the GnuTLS Transport Layer Security Library; see
 @uref{https://www.gnu.org/software/gnutls/, the GnuTLS project page}.
 If your Emacs was compiled with GnuTLS support, the function
 @code{gnutls-available-p} is defined and returns non-@code{nil}.  For
 more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}.
-The external support uses the @file{starttls.el} library, which
-requires a helper utility such as @command{gnutls-cli} to be installed
-on the system.  The @code{open-network-stream} function can
-transparently handle the details of creating encrypted connections for
-you, using whatever support is available.
+The @code{open-network-stream} function can transparently handle the
+details of creating encrypted connections for you, using whatever
+support is available.
 
 @defun open-network-stream name buffer host service &rest parameters
 This function opens a TCP connection, with optional encryption, and
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index c9301c9d186..d0791d40196 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -5915,10 +5915,6 @@ This function compares two window configurations as regards the
 structure of windows, but ignores the values of point and the
 saved scrolling positions---it can return @code{t} even if those
 aspects differ.
-
-The function @code{equal} can also compare two window configurations; it
-regards configurations as unequal if they differ in any respect, even a
-saved point.
 @end defun
 
 @defun window-configuration-frame config