[Emacs-diffs] master 4e15d26: Document 'major-mode-suspend' and 'major-mode-restore'

[Eli Zaretskii]

branch: master
commit 4e15d263134fdb8c9ff75e70f3f86225ad32ad31
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/lispref/modes.texi | 22 +++++++++++++++++++++-
 etc/NEWS               |  7 ++++---
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d7e217c..49b7e1e 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
address@hidden 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
address@hidden 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
 
address@hidden 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
address@hidden (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.
address@hidden defun
+
address@hidden major-mode-restore &optional avoided-modes
+This function restores the major mode recorded by
address@hidden  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
address@hidden, if that argument is address@hidden
address@hidden 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 83e106c..12757f6 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'.