Merge from origin/emacs-26

643df63 (origin/emacs-26) Avoid byte-compiler warning in em-rebind.el
d0eca49 ; * doc/emacs/mark.texi (Disabled Transient Mark): Fix last c...
af80b10 Improve indexing of 'C-SPC C-SPC'
89a7301 ; * doc/lispref/internals.texi (Writing Dynamic Modules): Fix...
a108eaa Fix bug with precious entries in Gnus registry
ce8b458 Document in the ELisp manual how to write loadable modules
a7ebc6b dired-do-shell-command: Notify users after abort the command

# Conflicts:
#	lisp/registry.el

8 files changed, 750 insertions, 25 deletions

diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
index 10505873c53..626f9dda25f 100644
--- a/doc/emacs/mark.texi
+++ b/doc/emacs/mark.texi
@@ -444,12 +444,13 @@ from point to the end of the buffer.  Commands that act this way are
 identified in their own documentation.
 @end itemize
 
+@cindex enabling Transient Mark mode temporarily
   While Transient Mark mode is off, you can activate it temporarily
 using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}.
 
 @table @kbd
 @item C-@key{SPC} C-@key{SPC}
-@kindex C-SPC C-SPC@r{, disabling Transient Mark}
+@kindex C-SPC C-SPC@r{, enabling Transient Mark mode temporarily}
 Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable
 Transient Mark mode just once, until the mark is deactivated.  (This
 is not really a separate command; you are using the @kbd{C-@key{SPC}}
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a615fcb4b7c..0b846291a07 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1590,9 +1590,18 @@ GNU Emacs Internals
 * Memory Usage::            Info about total size of Lisp objects made so far.
 * C Dialect::               What C variant Emacs is written in.
 * Writing Emacs Primitives::  Writing C code for Emacs.
+* Writing Dynamic Modules::   Writing loadable modules for Emacs.
 * Object Internals::        Data formats of buffers, windows, processes.
 * C Integer Types::         How C integer types are used inside Emacs.
 
+Writing Dynamic Modules
+
+* Module Initialization::
+* Module Functions::
+* Module Values::
+* Module Misc::
+* Module Nonlocal::
+
 Object Internals
 
 * Buffer Internals::        Components of a buffer structure.
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index d42e2444e68..0679537844e 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -18,6 +18,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
 * Memory Usage::        Info about total size of Lisp objects made so far.
 * C Dialect::           What C variant Emacs is written in.
 * Writing Emacs Primitives::   Writing C code for Emacs.
+* Writing Dynamic Modules::    Writing loadable modules for Emacs.
 * Object Internals::    Data formats of buffers, windows, processes.
 * C Integer Types::     How C integer types are used inside Emacs.
 @end menu
@@ -969,6 +970,708 @@ in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
 @code{side-effect-and-error-free-fns} so that the compiler optimizer
 knows about it.
 
+@node Writing Dynamic Modules
+@section Writing Dynamically-Loaded Modules
+@cindex writing emacs modules
+@cindex dynamic modules, writing
+
+@cindex module @acronym{API}
+  This section describes the Emacs module @acronym{API} and how to use
+it as part of writing extension modules for Emacs.  The module
+@acronym{API} is defined in the C programming language, therefore the
+description and the examples in this section assume the module is
+written in C@.  For other programming languages, you will need to use
+the appropriate bindings, interfaces and facilities for calling C code.
+Emacs C code requires a C99 or later compiler (@pxref{C Dialect}), and
+so the code examples in this section also follow that standard.
+
+Writing a module and integrating it into Emacs comprises the following
+tasks:
+
+@itemize @bullet
+@item
+Writing initialization code for the module.
+
+@item
+Writing one or more module functions.
+
+@item
+Communicating values and objects between Emacs and your module
+functions.
+
+@item
+Handling of error conditions and nonlocal exits.
+@end itemize
+
+@noindent
+The following subsections describe these tasks and the @acronym{API}
+itself in more detail.
+
+Once your module is written, compile it to produce a shared library,
+according to the conventions of the underlying platform.  Then place
+the shared library in a directory mentioned in @code{load-path}
+(@pxref{Library Search}), where Emacs will find it.
+
+If you wish to verify the conformance of a module to the Emacs dynamic
+module @acronym{API}, invoke Emacs with the @kbd{--module-assertions}
+option.  @xref{Initial Options,,,emacs, The GNU Emacs Manual}.
+
+@menu
+* Module Initialization::
+* Module Functions::
+* Module Values::
+* Module Misc::
+* Module Nonlocal::
+@end menu
+
+@node Module Initialization
+@subsection Module Initialization Code
+@cindex module initialization
+
+  Begin your module by including the header file @file{emacs-module.h}
+and defining the GPL compatibility symbol:
+
+@example
+#include <emacs-module.h>
+
+int plugin_is_GPL_compatible;
+@end example
+
+The @file{emacs-module.h} file is installed into your system's include
+tree as part of the Emacs installation.  Alternatively, you can find
+it in the Emacs source tree.
+
+@anchor{module initialization function}
+Next, write an initialization function for the module.
+
+@deftypefn Function int emacs_module_init (struct emacs_runtime *@var{runtime})
+Emacs calls this function when it loads a module.  If a module does
+not export a function named @code{emacs_module_init}, trying to load
+the module will signal an error.  The initialization function should
+return zero if the initialization succeeds, non-zero otherwise.  In
+the latter case, Emacs will signal an error, and the loading of the
+module will fail.  If the user presses @kbd{C-g} during the
+initialization, Emacs ignores the return value of the initialization
+function and quits (@pxref{Quitting}).  (If needed, you can catch user
+quitting inside the initialization function, @pxref{should_quit}.)
+
+The argument @var{runtime} is a pointer to a C @code{struct} that
+includes 2 public fields: @code{size}, which provides the size of the
+structure in bytes; and @code{get_environment}, which provides a
+pointer to a function that allows the module initialization function
+access to the Emacs environment object and its interfaces.
+
+The initialization function should perform whatever initialization is
+required for the module.  In addition, it can perform the following
+tasks:
+
+@table @asis
+@cindex compatibility, between modules and Emacs
+@item Compatibility verification
+A module can verify that the Emacs executable which loads the module
+is compatible with the module, by comparing the @code{size} member of
+the @var{runtime} structure with the value compiled into the module:
+
+@example
+int
+emacs_module_init (struct emacs_runtime *ert)
+@{
+  if (ert->size < sizeof (*ert))
+    return 1;
+@}
+@end example
+
+@noindent
+If the size of the runtime object passed to the module is smaller than
+what it expects, it means the module was compiled for an Emacs version
+newer (later) than the one which attempts to load it, i.e.@: the
+module might be incompatible with the Emacs binary.
+
+In addition, a module can verify the compatibility of the module
+@acronym{API} with what the module expects.  The following sample code
+assumes it is part of the @code{emacs_module_init} function shown
+above:
+
+@example
+  emacs_env *env = ert->get_environment (ert);
+  if (env->size < sizeof (*env))
+    return 2;
+@end example
+
+@noindent
+@cindex module runtime environment
+This calls the @code{get_environment} function using the pointer
+provided in the @code{runtime} structure to retrieve a pointer to the
+@acronym{API}'s @dfn{environment}, a C @code{struct} which also has a
+@code{size} field holding the size of the structure in bytes.
+
+Finally, you can write a module that will work with older versions of
+Emacs, by comparing the size of the environment passed by Emacs with
+known sizes, like this:
+
+@example
+  emacs_env *env = ert->get_environment (ert);
+  if (env->size >= sizeof (struct emacs_env_26))
+    emacs_version = 26;  /* Emacs 26 or later.  */
+  else if (env->size >= sizeof (struct emacs_env_25))
+    emacs_version = 25;
+  else
+    return 2; /* Unknown or unsupported version.  */
+@end example
+
+@noindent
+This works because later Emacs versions always @emph{add} members to
+the environment, never @emph{remove} any members, so the size can only
+grow with new Emacs releases.  Given the version of Emacs, the module
+can use only the parts of the module @acronym{API} that existed in
+that version, since those parts are identical in later versions.
+
+We recommend that modules always perform the compatibility
+verification, unless they do their job entirely in the initialization
+function, and don't access any Lisp objects or use any Emacs functions
+accessible through the environment structure.
+
+@item Binding module functions to Lisp symbols
+This gives the module functions names so that Lisp code could call it
+by that name.  We describe how to do this in @ref{Module Functions}
+below.
+@end table
+@end deftypefn
+
+@node Module Functions
+@subsection Writing Module Functions
+@cindex writing module functions
+@cindex module functions
+
+  The main reason for writing an Emacs module is to make additional
+functions available to Lisp programs that load the module.  This
+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})
+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
+zero (see @code{make_function} below for more flexible specification
+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}.
+
+Module functions use the type @code{emacs_value} to communicate Lisp
+objects between Emacs and the module (@pxref{Module Values}).  The
+@acronym{API}, described below and in the following subsections,
+provides facilities for conversion between basic C data types and the
+corresponding @code{emacs_value} objects.
+
+A module function always returns a value.  If the function returns
+normally, the Lisp code which called it will see the Lisp object
+corresponding to the @code{emacs_value} value the function returned.
+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.
+@end deftypefn
+
+After writing your C code for a module function, you should make a
+Lisp function object from it using @code{make_function}.  This is
+normally done in the module initialization function (@pxref{module
+initialization function}), after verifying the @acronym{API}
+compatibility, and uses the pointer to @code{make_function} provided
+in the environment (recall that the pointer to the environment is
+returned by @code{get_environment}).
+
+@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})
+@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
+@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},
+which makes the function accept an unlimited number of arguments, like
+the @code{&rest} keyword in Lisp (@pxref{Argument List}).
+
+The argument @var{data} is a way to arrange for arbitrary additional
+data to be passed to @var{func} when it is called.  Whatever pointer
+is passed to @code{make_function} will be passed unaltered to
+@var{func}.
+
+The argument @var{docstring} specifies the documentation string for
+the function.  It should be either an @acronym{ASCII} string, or a
+UTF-8 encoded non-@acronym{ASCII} string, or a @code{NULL} pointer; in
+the latter case the function will have no documentation.  The
+documentation string can end with a line that specifies the advertised
+calling convention, see @ref{Function Documentation}.
+
+Since every module function must accept the pointer to the environment
+as its first argument, the call to @code{make_function} could be made
+from any module function, but you will normally want to do that from
+the module initialization function, so that all the module functions
+are known to Emacs once the module is loaded.
+@end deftypefn
+
+Finally, you should bind the Lisp function to a symbol, so that Lisp
+code could call your function by name.  For that, use the module
+@acronym{API} function @code{intern} (@pxref{intern}) whose pointer is
+also provided in the environment that module functions can access.
+
+Combining the above steps, code that arranges for a C function
+@code{module_func} to be callable as @code{module-func} from Lisp will
+look like this, as part of the module initialization function:
+
+@example
+ emacs_env *env = ert->get_environment (ert);
+ emacs_value func = env->make_function (env, min_arity, max_arity,
+                                        module_func, docstring, data);
+ emacs_value symbol = env->intern (env, "module-func");
+ emacs_value args[] = @{symbol, func@};
+ env->funcall (env, env->intern (env, "defalias"), 2, args);
+@end example
+
+@noindent
+This makes the symbol @code{module-func} known to Emacs by calling
+@code{env->intern}, then invokes @code{defalias} from Emacs to bind
+the function to that symbol.  Note that it is possible to use
+@code{fset} instead of @code{defalias}; the differences are described
+in @ref{Defining Functions, defalias}.
+
+Using the module @acronym{API}, it is possible to define more complex
+function and data types: interactive functions, inline functions,
+macros, etc.  However, the resulting C code will be cumbersome and
+hard to read.  Therefore, we recommend that you limit the module code
+which creates functions and data structures to the absolute minimum,
+and leave the rest for a Lisp package that will accompany your module,
+because doing these additional tasks in Lisp is much easier, and will
+produce a much more readable code.  For example, given a module
+function @code{module-func} defined as above, one way of making an
+interactive command @code{module-cmd} based on it is with the
+following simple Lisp wrapper:
+
+@lisp
+(defun module-cmd (&rest args)
+  "Documentation string for the command."
+  (interactive @var{spec})
+  (apply 'module-func args))
+@end lisp
+
+The Lisp package which goes with your module could then load the
+module using the @code{module-load} primitive (@pxref{Dynamic
+Modules}) when the package is loaded into Emacs.
+
+@node Module Values
+@subsection Conversion Between Lisp and Module Values
+@cindex module values, conversion
+
+@cindex @code{emacs_value} data type
+  With very few exceptions, most modules need to exchange data with
+Lisp programs that call them: accept arguments to module functions and
+return values from module functions.  For this purpose, the module
+@acronym{API} provides the @code{emacs_value} type, which represents
+Emacs Lisp objects communicated via the @acronym{API}; it is the
+functional equivalent of the @code{Lisp_Object} type used in Emacs C
+primitives (@pxref{Writing Emacs Primitives}).  This section describes
+the parts of the module @acronym{API} that allow to create
+@code{emacs_value} objects corresponding to basic Lisp data types, and
+how to access from C data in @code{emacs_value} objects that
+correspond to Lisp objects.
+
+All of the functions described below are actually @emph{function
+pointers} provided via the pointer to the environment which every
+module function accepts.  Therefore, module code should call these
+functions through the environment pointer, like this:
+
+@example
+emacs_env *env;  /* the environment pointer */
+env->some_function (arguments@dots{});
+@end example
+
+@noindent
+The @code{emacs_env} pointer will usually come from the first argument
+to the module function, or from the call to @code{get_environment} if
+you need the environment in the module initialization function.
+
+Most of the functions described below became available in Emacs 25,
+the first Emacs release that supported dynamic modules.  For the few
+functions that became available in later Emacs releases, we mention
+the first Emacs version that supported them.
+
+The following @acronym{API} functions extract values of various C data
+types from @code{emacs_value} objects.  They all raise the
+@code{wrong-type-argument} error condition (@pxref{Type Predicates})
+if the argument @code{emacs_value} object is not of the type expected
+by the function.  @xref{Module Nonlocal}, for details of how signaling
+errors works in Emacs modules, and how to catch error conditions
+inside the module before they are reported to Emacs.  The
+@acronym{API} function @code{type_of} (@pxref{Module Misc, type_of})
+can be used to obtain the type of a @code{emacs_value} object.
+
+@deftypefn Function intmax_t extract_integer (emacs_env *@var{env}, emacs_value @var{arg})
+This function returns the value of a Lisp integer specified by
+@var{arg}.  The C data type of the return value, @code{intmax_t}, is
+the widest integral data type supported by the C compiler, typically
+@w{@code{long long}}.
+@end deftypefn
+
+@deftypefn Function double extract_float (emacs_env *@var{env}, emacs_value @var{arg})
+This function returns the value of a Lisp float specified by
+@var{arg}, as a C @code{double} value.
+@end deftypefn
+
+@deftypefn Function bool copy_string_contents (emacs_env *@var{env}, emacs_value @var{arg}, char *@var{buf}, ptrdiff_t *@var{len})
+This function stores the UTF-8 encoded text of a Lisp string specified
+by @var{arg} in the array of @code{char} pointed by @var{buf}, which
+should have enough space to hold at least @code{*@var{len}} bytes,
+including the terminating null byte.  The argument @var{len} must not
+be a @code{NULL} pointer, and, when the function is called, it should
+point to a value that specifies the size of @var{buf} in bytes.
+
+If the buffer size specified by @code{*@var{len}} is large enough to
+hold the string's text, the function stores in @code{*@var{len}} the
+actual number of bytes copied to @var{buf}, including the terminating
+null byte, and returns @code{true}.  If the buffer is too small, the
+function raises the @code{args-out-of-range} error condition, stores
+the required number of bytes in @code{*@var{len}}, and returns
+@code{false}.  @xref{Module Nonlocal}, for how to handle pending error
+conditions.
+
+The argument @var{buf} can be a @code{NULL} pointer, in which case the
+function stores in @code{*@var{len}} the number of bytes required for
+storing the contents of @var{arg}, and returns @code{true}.  This is
+how you can determine the size of @var{buf} needed to store a
+particular string: first call @code{copy_string_contents} with
+@code{NULL} as @var{buf}, then allocate enough memory to hold the
+number of bytes stored by the function in @code{*@var{len}}, and call
+the function again with non-@code{NULL} @var{buf} to actually perform
+the text copying.
+@end deftypefn
+
+@deftypefn Function emacs_value vec_get (emacs_env *@var{env}, emacs_value @var{vector}, ptrdiff_t @var{index})
+This function returns the element of @var{vector} at @var{index}.  The
+@var{index} of the first vector element is zero.  The function raises
+the @code{args-out-of-range} error condition if the value of
+@var{index} is invalid.  To extract C data from the value the function
+returns, use the other extraction functions described here, as
+appropriate for the Lisp data type stored in that element of the
+vector.
+@end deftypefn
+
+@deftypefn Function ptrdiff_t vec_size (emacs_env *@var{env}, emacs_value @var{vector})
+This function returns the number of elements in @var{vector}.
+@end deftypefn
+
+@deftypefn Function void vec_set (emacs_env *@var{env}, emacs_value @var{vector}, ptrdiff_t @var{index}, emacs_value @var{value})
+This function stores @var{value} in the element of @var{vector} whose
+index is @var{index}.  It raises the @code{args-out-of-range} error
+condition if the value of @var{index} is invalid.
+@end deftypefn
+
+The following @acronym{API} functions create @code{emacs_value}
+objects from basic C data types.  They all return the created
+@code{emacs_value} object.
+
+@deftypefn Function emacs_value make_integer (emacs_env *@var{env}, intmax_t @var{n})
+This function takes an integer argument @var{n} and returns the
+corresponding @code{emacs_value} object.  It raises the
+@code{overflow-error} error condition if the value of @var{n} cannot
+be represented as an Emacs integer, i.e.@: is not inside the limits
+set by @code{most-negative-fixnum} and @code{most-positive-fixnum}
+(@pxref{Integer Basics}).
+@end deftypefn
+
+@deftypefn Function emacs_value make_float (emacs_env *@var{env}, double @var{d})
+This function takes a @code{double} argument @var{d} and returns the
+corresponding Emacs floating-point value.
+@end deftypefn
+
+@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen})
+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.
+@end deftypefn
+
+The @acronym{API} does not provide functions to manipulate Lisp data
+structures, for example, create lists with @code{cons} and @code{list}
+(@pxref{Building Lists}), extract list members with @code{car} and
+@code{cdr} (@pxref{List Elements}), create vectors with @code{vector}
+(@pxref{Vector Functions}), etc.  For these, use @code{intern} and
+@code{funcall}, described in the next subsection, to call the
+corresponding Lisp functions.
+
+Normally, @code{emacs_value} objects have a rather short lifetime: it
+ends when the @code{emacs_env} pointer used for their creation goes
+out of scope.  Occasionally, you may need to create @dfn{global
+references}: @code{emacs_value} objects that live as long as you
+wish.  Use the following two functions to manage such objects.
+
+@deftypefn Function emacs_value make_global_ref (emacs_env *@var{env}, emacs_value @var{value})
+This function returns a global reference for @var{value}.
+@end deftypefn
+
+@deftypefn Function void free_global_ref (emacs_env *@var{env}, emacs_value @var{global_value})
+This function frees the @var{global_value} previously created by
+@code{make_global_ref}.  The @var{global_value} is no longer valid
+after the call.  Your module code should pair each call to
+@code{make_global_ref} with the corresponding @code{free_global_ref}.
+@end deftypefn
+
+@cindex user pointer, using in module functions
+An alternative to keeping around C data structures that need to be
+passed to module functions later is to create @dfn{user pointer}
+objects.  A user pointer, or @code{user-ptr}, object is a Lisp object
+that encapsulates a C pointer and can have an associated finalizer
+function, which is called when the object is garbage-collected
+(@pxref{Garbage Collection}).  The module @acronym{API} provides
+functions to create and access @code{user-ptr} objects.  These
+functions raise the @code{wrong-type-argument} error condition if they
+are called on @code{emacs_value} that doesn't represent a
+@code{user-ptr} object.
+
+@deftypefn Function emacs_value make_user_ptr (emacs_env *@var{env}, emacs_finalizer @var{fin}, void *@var{ptr})
+This function creates and returns a @code{user-ptr} object which wraps
+the C pointer @var{ptr}.  The finalizer function @var{fin} can be a
+@code{NULL} pointer (meaning no finalizer), or it can be a function of
+the following signature:
+
+@example
+typedef void (*emacs_finalizer) (void *@var{ptr});
+@end example
+
+@noindent
+If @var{fin} is not a @code{NULL} pointer, it will be called with the
+@var{ptr} as the argument when the @code{user-ptr} object is
+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)
+This function extracts the C pointer from the Lisp object represented
+by @var{val}.
+@end deftypefn
+
+@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr})
+This function sets the C pointer embedded in the @code{user-ptr}
+object represented by @var{value} to @var{ptr}.
+@end deftypefn
+
+@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val)
+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.
+@end deftypefn
+
+@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, 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.
+@end deftypefn
+
+@node Module Misc
+@subsection Miscellaneous Convenience Functions for Modules
+
+  This subsection describes a few convenience functions provided by
+the module @acronym{API}.  Like the functions described in previous
+subsections, all of them are actually function pointers, and need to
+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})
+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.
+
+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}
+is non-@code{nil}; it returns @code{true} or @code{false} accordingly.
+
+Note that you could implement an equivalent test by using
+@code{intern} to get an @code{emacs_value} representing @code{nil},
+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.
+@end deftypefn
+
+@anchor{intern}
+@deftypefn Function emacs_value intern (emacs_env *@var{env}, const char *name)
+This function returns an interned Emacs symbol whose name is
+@var{name}, which should be an @acronym{ASCII} null-terminated string.
+It creates a new symbol if one does not already exist.
+
+Together with @code{funcall}, described below, this function provides
+a means for invoking any Lisp-callable Emacs function, provided that
+its name is a pure @acronym{ASCII} string.  For example, here's how to
+intern a symbol whose name @code{name_str} is non-@acronym{ASCII}, by
+calling the more powerful Emacs @code{intern} function
+(@pxref{Creating Symbols}):
+
+@example
+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);
+@end example
+
+@end deftypefn
+
+@deftypefn Function emacs_value funcall (emacs_env *@var{env}, emacs_value @var{func}, ptrdiff_t @var{nargs}, emacs_value *@var{args})
+This function calls the specified @var{func} passing it @var{nargs}
+arguments from the array pointed to by @var{args}.  The argument
+@var{func} can be a function symbol (e.g., returned by @code{intern}
+described above), a module function returned by @code{make_function}
+(@pxref{Module Functions}), a subroutine written in C, etc.  If
+@var{nargs} is zero, @var{args} can be a @code{NULL} pointer.
+
+The function returns the value that @var{func} returned.
+@end deftypefn
+
+If your module includes potentially long-running code, it is a good
+idea to check from time to time in that code whether the user wants to
+quit, e.g., by typing @kbd{C-g} (@pxref{Quitting}).  The following
+function, which is available since Emacs 26.1, is provided for that
+purpose.
+
+@anchor{should_quit}
+@deftypefn Function bool should_quit (emacs_env *@var{env})
+This function returns @code{true} if the user wants to quit.  In that
+case, we recommend that your module function aborts any on-going
+processing and returns as soon as possible.
+@end deftypefn
+
+@node Module Nonlocal
+@subsection Nonlocal Exits in Modules
+@cindex nonlocal exits, in modules
+
+  Emacs Lisp supports nonlocal exits, whereby program control is
+transfered from one point in a program to another remote point.
+@xref{Nonlocal Exits}.  Thus, Lisp functions called by your module
+might exit nonlocally by calling @code{signal} or @code{throw}, and
+your module functions must handle such nonlocal exits properly.  Such
+handling is needed because C programs will not automatically release
+resources and perform other cleanups in these cases; your module code
+must itself do it.  The module @acronym{API} provides facilities for
+that, described in this subsection.  They are generally available
+since Emacs 25; those of them that became available in later releases
+explicitly call out the first Emacs version where they became part of
+the @acronym{API}.
+
+When some Lisp code called by a module function signals an error or
+throws, the nonlocal exit is trapped, and the pending exit and its
+associated data are stored in the environment.  Whenever a nonlocal
+exit is pending in the environment, any module @acronym{API} function
+called with a pointer to that environment will return immediately
+without any processing (the functions @code{non_local_exit_check},
+@code{non_local_exit_get}, and @code{non_local_exit_clear} are
+exceptions from this rule).  If your module function then does nothing
+and returns to Emacs, a pending nonlocal exit will cause Emacs to act
+on it: signal an error or throw to the corresponding @code{catch}.
+
+So the simplest ``handling'' of nonlocal exits in module functions is
+to do nothing special and let the rest of your code to run as if
+nothing happened.  However, this can cause two classes of problems:
+
+@itemize @minus
+@item
+Your module function might use uninitialized or undefined values,
+since @acronym{API} functions return immediately without producing the
+expected results.
+
+@item
+Your module might leak resources, because it might not have the
+opportunity to release them.
+@end itemize
+
+Therefore, we recommend that your module functions check for nonlocal
+exit conditions and recover from them, using the functions described
+below.
+
+@deftypefn Function enum emacs_funcall_exit non_local_exit_check (emacs_env *@var{env})
+This function returns the kind of nonlocal exit condition stored in
+@var{env}.  The possible values are:
+
+@vindex emacs_funcall_exit@r{, enumeration}
+@vtable @code
+@item emacs_funcall_exit_return
+The last @acronym{API} function exited normally.
+@item emacs_funcall_exit_signal
+The last @acronym{API} function signaled an error.
+@item emacs_funcall_exit_throw
+The last @acronym{API} function exited via @code{throw}.
+@end vtable
+@end deftypefn
+
+@deftypefn Function emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data})
+This function returns the kind of nonlocal exit condition stored in
+@var{env}, like @code{non_local_exit_check} does, but it also returns
+the full information about the nonlocal exit, if any.  If the return
+value is @code{emacs_funcall_exit_signal}, the function stores the
+error symbol in @code{*@var{symbol}} and the error data in
+@code{*@var{data}} (@pxref{Signaling Errors}).  If the return value is
+@code{emacs_funcall_exit_throw}, the function stores the @code{catch}
+tag symbol in @code{*@var{symbol}} and the @code{throw} value in
+@code{*@var{data}}.  The function doesn't store anything in memory
+pointed by these arguments when the return value is
+@code{emacs_funcall_exit_return}.
+@end deftypefn
+
+You should check nonlocal exit conditions where it matters: before you
+allocated some resource or after you allocated a resource that might
+need freeing, or where a failure means further processing is
+impossible or infeasible.
+
+Once your module function detected that a nonlocal exit is pending, it
+can either return to Emacs (after performing the necessary local
+cleanup), or it can attempt to recover from the nonlocal exit.  The
+following @acronym{API} functions will help with these tasks.
+
+@deftypefn Function void non_local_exit_clear (emacs_env *@var{env})
+This function clears the pending nonlocal exit conditions and data
+from @var{env}.  After calling it, the module @acronym{API} functions
+will work normally.  Use this function if your module function can
+recover from nonlocal exits of the Lisp functions it calls and
+continue, and also before calling any of the following two functions
+(or any other @acronym{API} functions, if you want them to perform
+their intended processing when a nonlocal exit is pending).
+@end deftypefn
+
+@deftypefn Function void non_local_exit_throw (emacs_env *@var{env}, emacs_value @var{tag}, emacs_value @var{value})
+This function throws to the Lisp @code{catch} symbol represented by
+@var{tag}, passing it @var{value} as the value to return.  Your module
+function should in general return soon after calling this function.
+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.
+@end deftypefn
+
+
 @node Object Internals
 @section Object Internals
 @cindex object internals
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 82c133de753..6f15cd9c60a 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1139,8 +1139,6 @@ Features}).
 @section Emacs Dynamic Modules
 @cindex dynamic modules
 
-@c FIXME: This is intentionally incomplete, as the module integration
-@c is not yet finished.  To be refined later.
   A @dfn{dynamic Emacs module} is a shared library that provides
 additional functionality for use in Emacs Lisp programs, just like a
 package written in Emacs Lisp would.
@@ -1162,30 +1160,43 @@ Every dynamic module should export a C-callable function named
 @code{load} or @code{require} which loads the module.  It should also
 export a symbol named @code{plugin_is_GPL_compatible} to indicate that
 its code is released under the GPL or compatible license; Emacs will
-refuse to load modules that don't export such a symbol.
+signal an error if your program tries to load modules that don't
+export such a symbol.
 
 If a module needs to call Emacs functions, it should do so through the
-API defined and documented in the header file @file{emacs-module.h}
-that is part of the Emacs distribution.
+@acronym{API} (Application Programming Interface) defined and
+documented in the header file @file{emacs-module.h} that is part of
+the Emacs distribution.  @xref{Writing Dynamic Modules}, for details
+of using that API when writing your own modules.
 
 @cindex user-ptr object
+@cindex user pointer object
 Modules can create @code{user-ptr} Lisp objects that embed pointers to
 C struct's defined by the module.  This is useful for keeping around
 complex data structures created by a module, to be passed back to the
 module's functions.  User-ptr objects can also have associated
 @dfn{finalizers} -- functions to be run when the object is GC'ed; this
 is useful for freeing any resources allocated for the underlying data
-structure, such as memory, open file descriptors, etc.
+structure, such as memory, open file descriptors, etc.  @xref{Module
+Values}.
 
 @defun user-ptrp object
 This function returns @code{t} if its argument is a @code{user-ptr}
 object.
 @end defun
 
+@defun module-load file
+Emacs calls this low-level primitive to load a module from the
+specified @var{file} and perform the necessary initialization of the
+module.  This is the primitive which makes sure the module exports the
+@code{plugin_is_GPL_compatible} symbol, calls the module's
+@code{emacs_module_init} function, and signals an error if that
+function returns an error indication, or if the use typed @kbd{C-g}
+during the initialization.  If the initialization succeeds,
+@code{module-load} returns @code{t}.  Note that @var{file} must
+already have the proper file-name extension, as this function doesn't
+try looking for files with known extensions, unlike @code{load}.
+@end defun
+
 Loadable modules in Emacs are enabled by using the
 @kbd{--with-modules} option at configure time.
-
-If you write your own dynamic modules, you may wish to verify their
-conformance to the Emacs dynamic module API.  Invoking Emacs with the
-@kbd{--module-assertions} option will help you in this matter.
-@xref{Initial Options,,,emacs, The GNU Emacs Manual}.
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 2f7d8407fc4..fb9113f4608 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -26194,7 +26194,7 @@ Get the data under @code{key} for message @code{id}.
 If any extra entries are precious, their presence will make the
 registry keep the whole entry forever, even if there are no groups for
 the Message-ID and if the size limit of the registry is reached.  By
-default this is just @code{(marks)} so the custom registry marks are
+default this is just @code{(mark)} so the custom registry marks are
 precious.
 @end defvar
 
diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 1f13204b7cf..90bfa096b08 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -763,16 +763,17 @@ can be produced by `dired-get-marked-files', for example."
                     (y-or-n-p (format-message
                                "Confirm--do you mean to use `?' as a wildcard? ")))
                    (t))))
-    (when ok
-      (if on-each
-          (dired-bunch-files (- 10000 (length command))
-                             (lambda (&rest files)
-                               (dired-run-shell-command
-                                (dired-shell-stuff-it command files t arg)))
-                             nil file-list)
-        ;; execute the shell command
-        (dired-run-shell-command
-         (dired-shell-stuff-it command file-list nil arg)))))))
+    (cond ((not ok) (message "Command canceled"))
+          (t
+           (if on-each
+               (dired-bunch-files (- 10000 (length command))
+                                  (lambda (&rest files)
+                                    (dired-run-shell-command
+                                     (dired-shell-stuff-it command files t arg)))
+                                  nil file-list)
+             ;; execute the shell command
+             (dired-run-shell-command
+              (dired-shell-stuff-it command file-list nil arg))))))))
 
 ;; Might use {,} for bash or csh:
 (defvar dired-mark-prefix ""
diff --git a/lisp/eshell/em-rebind.el b/lisp/eshell/em-rebind.el
index e6f04b68e0c..064dcc762d2 100644
--- a/lisp/eshell/em-rebind.el
+++ b/lisp/eshell/em-rebind.el
@@ -223,7 +223,7 @@ lock it at that."
   (interactive "P")
   (let ((count (prefix-numeric-value n)))
     (if (eshell-point-within-input-p (- (point) count))
-        (delete-backward-char count n)
+        (delete-char (- count) n)
       (beep))))
 
 (defun eshell-delchar-or-maybe-eof (arg)
diff --git a/lisp/registry.el b/lisp/registry.el
index 4928dd9b202..c3184a820f3 100644
--- a/lisp/registry.el
+++ b/lisp/registry.el
@@ -358,7 +358,7 @@ return LIMIT such candidates.  If SORTFUNC is provided, sort
 entries first and return candidates from beginning of list."
   (let* ((precious (oref db precious))
          (precious-p (lambda (entry-key)
-                       (cdr (memq (car-safe entry-key) precious))))
+                       (memq (car-safe entry-key) precious)))
          (data (oref db data))
          (candidates (cl-loop for k being the hash-keys of data
                               using (hash-values v)