Document 'major-mode-suspend' and 'major-mode-restore'

* doc/lispref/modes.texi (Major Modes): Document
'major-mode-suspend' and 'major-mode-restore'.  (Bug#31551)

* etc/NEWS: Mark the corresponding entry as documented in
manuals.

2 files changed, 25 insertions, 4 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d7e217c5287..49b7e1ea3fb 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -197,6 +197,7 @@ from the buffer-local hook list instead of from the global hook list.
 @cindex major mode
 
 @cindex major mode command
+@cindex suspend major mode temporarily
   Major modes specialize Emacs for editing or interacting with
 particular kinds of text.  Each buffer has exactly one major mode at a
 time.  Every major mode is associated with a @dfn{major mode command},
@@ -205,7 +206,8 @@ switching to that mode in the current buffer, by setting various
 buffer-local variables such as a local keymap.  @xref{Major Mode
 Conventions}.  Note that unlike minor modes there is no way to ``turn
 off'' a major mode, instead the buffer must be switched to a different
-one.
+one.  However, you can temporarily @dfn{suspend} a major mode and later
+@dfn{restore} the suspended mode, see below.
 
   The least specialized major mode is called @dfn{Fundamental mode},
 which has no mode-specific definitions or variable settings.
@@ -216,6 +218,24 @@ commands, it does @emph{not} run any mode hooks (@pxref{Major Mode
 Conventions}), since you are not supposed to customize this mode.
 @end deffn
 
+@defun major-mode-suspend
+This function works like @code{fundamental-mode}, in that it kills all
+buffer-local variables, but it also records the major mode in effect,
+so that it could subsequently be restored.  This function and
+@code{major-mode-restore} (described next) are useful when you need to
+put a buffer under some specialized mode other than the one Emacs
+chooses for it automatically (@pxref{Auto Major Mode}), but would also
+like to be able to switch back to the original mode later.
+@end defun
+
+@defun major-mode-restore &optional avoided-modes
+This function restores the major mode recorded by
+@code{major-mode-suspend}.  If no major mode was recorded, this
+function calls @code{normal-mode} (@pxref{Auto Major Mode,
+normal-mode}), but tries to force it not to choose any modes in
+@var{avoided-modes}, if that argument is non-@code{nil}.
+@end defun
+
   The easiest way to write a major mode is to use the macro
 @code{define-derived-mode}, which sets up the new mode as a variant of
 an existing major mode.  @xref{Derived Modes}.  We recommend using
diff --git a/etc/NEWS b/etc/NEWS
index 83e106ced8c..12757f61d20 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -658,9 +658,10 @@ manual for more details.
 
 * Lisp Changes in Emacs 27.1
 
-** New functions 'major-mode-suspend' and 'major-mode-restore'
-Used when switching temporarily to another major mode, e.g. for hexl-mode,
-or to switch between c-mode and image-mode in XPM.
++++
+** New functions 'major-mode-suspend' and 'major-mode-restore'.
+Use them when switching temporarily to another major mode, e.g. for
+'hexl-mode', or to switch between 'c-mode' and 'image-mode' in XPM.
 
 +++
 ** New macro 'dolist-with-progress-reporter'.