bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Manuel Giraud <manuel@ledu-giraud.fr>]

[-- Attachment #1: Type: text/plain, Size: 327 bytes --]

Here is a rewrite/reshuffle of (Saving Emacs Sessions) node.

I tried to explain desktop-save-mode right from the start.  Then go on
with the options by order of importance.  As you suggest, I left
desktop-load-locked-desktop quite high even though I find it a bit
verbose and quite « implementation detail ».  WDYT?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Rewrite-Saving-Emacs-Sessions-bug-60600.patch --]
[-- Type: text/x-patch, Size: 9462 bytes --]

From 7b38bc4b21ebb488a434a5c658f8d463d0131714 Mon Sep 17 00:00:00 2001
From: Manuel Giraud <manuel@ledu-giraud.fr>
Date: Fri, 6 Jan 2023 11:29:20 +0100
Subject: [PATCH] Rewrite "Saving Emacs Sessions" (bug#60600)

* doc/emacs/misc.texi (Saving Emacs Sessions): Organize this node more
logically with main behaviour and important features at the top.
---
 doc/emacs/misc.texi | 136 +++++++++++++++++++++++---------------------
 1 file changed, 70 insertions(+), 66 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index c706b727e6f..167181f5d1e 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2704,38 +2704,13 @@ Saving Emacs Sessions
 @cindex reload files
 @cindex desktop
 
-@vindex desktop-restore-frames
    Use the desktop library to save the state of Emacs from one session
-to another.  Once you save the Emacs @dfn{desktop}---the buffers,
-their file names, major modes, buffer positions, and so on---then
-subsequent Emacs sessions reload the saved desktop.  By default,
-the desktop also tries to save the frame and window configuration.
-To disable this, set @code{desktop-restore-frames} to @code{nil}.
-(See that variable's documentation for some related options
-that you can customize to fine-tune this behavior.)
-
-@vindex desktop-files-not-to-save
-Information about buffers visiting remote files is not saved by
-default.  Customize the variable @code{desktop-files-not-to-save} to
-change this.
+to another.  The Emacs @dfn{desktop} consists of the buffers, their
+file names, major modes, buffer positions, and so on.
 
-@vindex frameset-filter-alist
-   When the desktop restores the frame and window configuration, it
-uses the recorded values of frame parameters, disregarding any
-settings for those parameters you have in your init file (@pxref{Init
-File}).  This means that frame parameters such as fonts and faces for
-the restored frames will come from the desktop file, where they were
-saved when you exited your previous Emacs session; any settings for
-those parameters in your init file will be ignored.  To disable this,
-customize the value of @code{frameset-filter-alist} to filter out the
-frame parameters you don't want to be restored.
-
-@findex desktop-save
 @vindex desktop-save-mode
-  You can save the desktop manually with the command @kbd{M-x
-desktop-save}.  You can also enable automatic saving of the desktop
-when you exit Emacs, and automatic restoration of the last saved
-desktop when Emacs starts: use the Customization buffer (@pxref{Easy
+@findex desktop-save-mode
+To enable this feature, use the Customization buffer (@pxref{Easy
 Customization}) to set @code{desktop-save-mode} to @code{t} for future
 sessions, or add this line in your init file (@pxref{Init File}):
 
@@ -2743,25 +2718,69 @@ Saving Emacs Sessions
 (desktop-save-mode 1)
 @end example
 
-@findex desktop-change-dir
-@findex desktop-revert
 @vindex desktop-path
+@vindex desktop-auto-save-timeout
   If you turn on @code{desktop-save-mode} in your init file, then when
-Emacs starts, it looks for a saved desktop in the current directory.
-(More precisely, it looks in the directories specified by
-@code{desktop-path}, and uses the first desktop it finds.)
-Thus, you can have separate saved desktops in different directories,
-and the starting directory determines which one Emacs reloads.  You
+Emacs starts, it looks for a saved desktop in @code{desktop-path}
+(which defaults to @code{user-emacs-directory} and then your home
+directory) and uses the first desktop it finds.  While Emacs runs with
+@code{desktop-save-mode} turned on, it by default auto-saves the
+desktop whenever any of it changes.  The variable
+@code{desktop-auto-save-timeout} determines how frequently Emacs
+checks for modifications to your desktop.  The desktop is also saved
+when you exit Emacs.
+
+@findex desktop-change-dir
+@findex desktop-revert
+  You can have separate saved desktops in different directories.  You
 can save the current desktop and reload one saved in another directory
 by typing @kbd{M-x desktop-change-dir}.  Typing @kbd{M-x
 desktop-revert} reverts to the desktop previously reloaded.
 
-  Specify the option @samp{--no-desktop} on the command line when you
-don't want it to reload any saved desktop.  This turns off
-@code{desktop-save-mode} for the current session.  Starting Emacs with
-the @samp{--no-init-file} option also disables desktop reloading,
-since it bypasses the init file, where @code{desktop-save-mode} is
-usually turned on.
+@vindex desktop-load-locked-desktop
+  The file in which Emacs saves the desktop is locked while the
+session runs, to avoid inadvertently overwriting it from another Emacs
+session.  That lock is normally removed when Emacs exits, but if Emacs
+or your system crashes, the lock stays, and when you restart Emacs, it
+will by default ask you whether to use the locked desktop file.  You
+can avoid the question by customizing the variable
+@code{desktop-load-locked-desktop} to either @code{nil}, which means
+never load the desktop in this case, or @code{t}, which means load the
+desktop without asking.  Finally, the @code{check-pid} value means to
+load the file if the Emacs process that has locked the desktop is not
+running on the local machine.  This should not be used in
+circumstances where the locking Emacs might still be running on
+another machine.  This could be the case in multi-user environments
+where your home directory is mounted remotely using NFS or similar.
+
+@findex desktop-save
+@findex desktop-read
+  Whenever you want, you can use the command @kbd{M-x desktop-save} to
+force saving the current desktop.  If you do not want to use the
+automatic @code{desktop-save-mode}, you can use @kbd{M-x desktop-save}
+and then @kbd{M-x desktop-read} to restore a previous desktop.
+
+@vindex desktop-restore-frames
+  By default, the desktop also tries to save the frame and window
+configuration.  To disable this, set @code{desktop-restore-frames} to
+@code{nil}.  (See that variable's documentation for some related
+options that you can customize to fine-tune this behavior.)
+
+@vindex desktop-files-not-to-save
+  Information about buffers visiting remote files is not saved by
+default.  Customize the variable @code{desktop-files-not-to-save} to
+change this.
+
+@vindex frameset-filter-alist
+   When the desktop restores the frame and window configuration, it
+uses the recorded values of frame parameters, disregarding any
+settings for those parameters you have in your init file (@pxref{Init
+File}).  This means that frame parameters such as fonts and faces for
+the restored frames will come from the desktop file, where they were
+saved when you exited your previous Emacs session; any settings for
+those parameters in your init file will be ignored.  To disable this,
+customize the value of @code{frameset-filter-alist} to filter out the
+frame parameters you don't want to be restored.
 
 @vindex desktop-restore-eager
   By default, all the buffers in the desktop are restored in one go.
@@ -2780,30 +2799,12 @@ Saving Emacs Sessions
 @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
 expression matching the names of buffers not to kill.
 
-  If you want to save minibuffer history from one session to
-another, use the @code{savehist} library.
-
-@vindex desktop-auto-save-timeout
-  While Emacs runs with @code{desktop-save-mode} turned on, it by
-default auto-saves the desktop whenever any of it changes.  The
-variable @code{desktop-auto-save-timeout} determines how frequently
-Emacs checks for modifications to your desktop.
-
-@vindex desktop-load-locked-desktop
-  The file in which Emacs saves the desktop is locked while the
-session runs, to avoid inadvertently overwriting it from another Emacs
-session.  That lock is normally removed when Emacs exits, but if Emacs
-or your system crashes, the lock stays, and when you restart Emacs, it
-will by default ask you whether to use the locked desktop file.  You
-can avoid the question by customizing the variable
-@code{desktop-load-locked-desktop} to either @code{nil}, which means
-never load the desktop in this case, or @code{t}, which means load the
-desktop without asking.  Finally, the @code{check-pid} value means to
-load the file if the Emacs process that has locked the desktop is not
-running on the local machine.  This should not be used in
-circumstances where the locking Emacs might still be running on
-another machine.  This could be the case in multi-user environments
-where your home directory is mounted remotely using NFS or similar.
+  Specify the option @samp{--no-desktop} on the command line when you
+don't want it to reload any saved desktop.  This turns off
+@code{desktop-save-mode} for the current session.  Starting Emacs with
+the @samp{--no-init-file} option also disables desktop reloading,
+since it bypasses the init file, where @code{desktop-save-mode} is
+usually turned on.
 
 @cindex desktop restore in daemon mode
   When Emacs starts in daemon mode, it cannot ask you any questions,
@@ -2817,6 +2818,9 @@ Saving Emacs Sessions
 function that you add to @code{server-after-make-frame-hook}
 (@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}).
 
+  If you want to save minibuffer history from one session to
+another, use the @code{savehist} library.
+
 @node Recursive Edit
 @section Recursive Editing Levels
 @cindex recursive editing level
-- 
2.39.0


[-- Attachment #3: Type: text/plain, Size: 18 bytes --]

-- 
Manuel Giraud