Merge from origin/emacs-28

067361f3a2 ; Improve documentation of 'C-M-i'
fdb6f7cf26 ; Fix documentation of 'comp-enable-subr-trampolines'
be30369e01 ; Avoid incorrect indentation in an @example.
4bd3dd505e Document how to control where the *.eln files are written
b7d7c2d9e9 Add cross-reference to alternative syntaxes for Unicode

# Conflicts:
#	doc/emacs/custom.texi

1 files changed, 15 insertions, 2 deletions

diff --git a/src/comp.c b/src/comp.c
index b7541c5d9f7..14012634ccc 100644
--- a/src/comp.c
+++ b/src/comp.c
@@ -5868,8 +5868,21 @@ The last directory of this list is assumed to be the system one.  */);
   Vnative_comp_eln_load_path = Fcons (build_string ("../native-lisp/"), Qnil);
 
   DEFVAR_BOOL ("comp-enable-subr-trampolines", comp_enable_subr_trampolines,
-	       doc: /* If non-nil enable primitive trampoline synthesis.
-This makes primitive functions redefinable or advisable effectively.  */);
+	       doc: /* If non-nil, enable primitive trampoline synthesis.
+This makes Emacs respect redefinition or advises of primitive functions
+when they are called from Lisp code natively-compiled at `native-comp-speed'
+of 2.
+
+By default, this is enabled, and when Emacs sees a redefined or advised
+primitive called from natively-compiled Lisp, it generates a trampoline
+for it on-the-fly.
+
+Disabling this, when a trampoline for a redefined or advised primitive is
+not available from previous compilations, means that such redefinition
+or advise will not have effect on calls from natively-compiled Lisp code.
+That is, calls to primitives without existing trampolines from
+natively-compiled Lisp will behave as if the primitive was called
+directly from C.  */);
 
   DEFVAR_LISP ("comp-installed-trampolines-h", Vcomp_installed_trampolines_h,
 	       doc: /* Hash table subr-name -> installed trampoline.