Improve documentation of desktop restoring

* doc/emacs/misc.texi (Saving Emacs Sessions): Document
'desktop-auto-save-timeout', 'desktop-load-locked-desktop', and
how to restore desktop in daemon mode.  (Bug#30421)

1 files changed, 30 insertions, 1 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 5babd5081a9..ae6f9446f28 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2485,7 +2485,7 @@ since it bypasses the init file, where @code{desktop-save-mode} is
 usually turned on.
 
 @vindex desktop-restore-eager
-  By default, all the buffers in the desktop are restored at one go.
+  By default, all the buffers in the desktop are restored in one go.
 However, this may be slow if there are a lot of buffers in the
 desktop.  You can specify the maximum number of buffers to restore
 immediately with the variable @code{desktop-restore-eager}; the
@@ -2504,6 +2504,35 @@ 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.
+
+@cindex desktop restore in daemon mode
+  When Emacs starts in daemon mode, it cannot ask you any questions,
+so if it finds the desktop file locked, it will not load it, unless
+@code{desktop-load-locked-desktop} is @code{t}.  Note that restoring
+the desktop in daemon mode is somewhat problematic for other reasons:
+e.g., the daemon cannot use GUI features, so parameters such as frame
+position, size, and decorations cannot be restored.  For that reason,
+you may wish to delay restoring the desktop in daemon mode until the
+first client connects, by calling @code{desktop-read} in a hook
+function that you add to @code{after-make-frame-functions}
+(@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}).
+
 @node Recursive Edit
 @section Recursive Editing Levels
 @cindex recursive editing level